CINXE.COM
Overview | Spreaker Developers Guide
<!DOCTYPE html> <html lang="en" xml:lang="en" xmlns="http://www.w3.org/1999/xhtml"> <head> <meta charset='utf-8'> <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" /> <title>Overview | Spreaker Developers Guide</title> <meta name="description" content="Spreaker API Reference and Guides" /> <!-- Theme color --> <meta name="theme-color" content="#2b2e32"> <!-- Facebook --> <meta property="fb:app_id" content="215002133707" /> <meta property="og:site_name" content="Spreaker for Developers" /> <meta property="og:type" content="article" /> <meta property="og:title" content="Overview | Spreaker Developers Guide" /> <meta property="og:description" content="Spreaker API Reference and Guides" /> <meta property="og:image" content="https://developers.spreaker.com/assets/share_picture_default-14fd08b1e96453864723d8a8ae2521d80a27aafb9be46821f95f9e9a3ef654a5.jpg" /> <!-- Favicon --> <link rel="apple-touch-icon" sizes="57x57" href="https://developers.spreaker.com/assets/favicon/apple-icon-57x57-b276c120fcd029c7b1017d275d711b79ee5bb6e29e54baf265f8d6f2b794ad4c.png"> <link rel="apple-touch-icon" sizes="60x60" href="https://developers.spreaker.com/assets/favicon/apple-icon-60x60-24a615764e329edaa3189e292fa8e65e1d20ee3a15558a8f1b421a74ee595c96.png"> <link rel="apple-touch-icon" sizes="72x72" href="https://developers.spreaker.com/assets/favicon/apple-icon-72x72-6f8c7becbddbcb63a3a707f83a32f5300228c4a3476696d7c107fdf50c459bc7.png"> <link rel="apple-touch-icon" sizes="76x76" href="https://developers.spreaker.com/assets/favicon/apple-icon-76x76-0d4bcbc5ee09aac893e27d05398ef76b16517bfdadfa8c8fe853ac07fb3ee414.png"> <link rel="apple-touch-icon" sizes="114x114" href="https://developers.spreaker.com/assets/favicon/apple-icon-114x114-ab7356f8ad7fbdf13cb9ee9fd48c710dff76c1c5884f07f7bd400fc3458225ed.png"> <link rel="apple-touch-icon" sizes="120x120" href="https://developers.spreaker.com/assets/favicon/apple-icon-120x120-7b780e00c482712d068a4681eb1ec8bec1dae4158b9a8ce54ffac26f9bbef852.png"> <link rel="apple-touch-icon" sizes="144x144" href="https://developers.spreaker.com/assets/favicon/apple-icon-144x144-589692ddbc9404f9531584fa90f6a84709f89ae0870f216a73b3b9b2c9292fad.png"> <link rel="apple-touch-icon" sizes="152x152" href="https://developers.spreaker.com/assets/favicon/apple-icon-152x152-a82061a36d11cff67363fb902dce448c13d5780afd3341ffc1b77c0541821903.png"> <link rel="apple-touch-icon" sizes="180x180" href="https://developers.spreaker.com/assets/favicon/apple-icon-180x180-05c3c16650de1ff094cfa4bc79437a20afc2fa9ab0dbe418360d949fc8fc7b27.png"> <link rel="icon" type="image/png" sizes="192x192" href="https://developers.spreaker.com/assets/favicon/android-icon-192x192-15aee1271338376079efb14758fed72ec4b5f141322a8bdfca7806d7f142a4cd.png"> <link rel="icon" type="image/png" sizes="32x32" href="https://developers.spreaker.com/assets/favicon/favicon-32x32-1730b74ab227bb2f65ba1aa095fa2f7b3cdf65f2edb422c9761e22ea9a6a6df5.png"> <link rel="icon" type="image/png" sizes="96x96" href="https://developers.spreaker.com/assets/favicon/favicon-96x96-d6825e13beecae90c201bab1e467b027804a2c53175a1f9020eb83caa2b9e9e8.png"> <link rel="icon" type="image/png" sizes="16x16" href="https://developers.spreaker.com/assets/favicon/favicon-16x16-0abbd9089e7aa3d4fef4ded2d344c0e1c0457c3d90c67fc80567623d8c856408.png"> <meta name="msapplication-TileImage" content="https://developers.spreaker.com/assets/favicon/ms-icon-144x144-589692ddbc9404f9531584fa90f6a84709f89ae0870f216a73b3b9b2c9292fad.png"> <!-- CSS --> <link type="text/css" rel="stylesheet" href="/assets/all-0d9972c3c0b2e2bafda864207e3e20faae5282d52a778af56d99bd8a28c5c130.css"> </head> <body> <!-- Header --> <header> <nav class="hd_nav"> <a class="hd_logo" href="/">Spreaker for Developers</a> <ul class="hd_menu"> <li><a href="/api/">API</a></li> <li><a href="/guides/">Guides</a></li> <li><a href="https://help.spreaker.com" target="_blank">Support</a></li> </ul> </nav> </header> <!-- Content --> <main> <div class="page page_with_sidebar"> <!-- Content --> <div class="page_content"> <!-- <div class="announcement"> <p>Interested in working with us? We offer a superb REMOTE work opportunity for a DEVOP.</p> <p><a target="_blank" href="https://www.spreaker.com/jobs/devop">Click here to find out more.</a></p> </div> --> <h1 id="overview">Overview</h1> <ol> <li><a href="#url">URL</a></li> <li><a href="#authentication">Authentication</a></li> <li><a href="#request-and-response-format">Request and Response Format</a></li> <li><a href="#charset-utf-8">Charset (UTF-8)</a></li> <li><a href="#pagination">Pagination</a></li> <li><a href="#localization">Localization</a></li> <li><a href="#rate-limiting">Rate Limiting</a></li> <li><a href="#command-line-tools-used-in-examples">Command Line Tools Used in Examples</a></li> </ol> <h2 id="url">URL</h2> <p>All API access is over <strong>HTTPS</strong>, and accessed from <code>api.spreaker.com</code>. The current API version is <strong>v2</strong>, so each API URL will start with:</p> <pre><code>https://api.spreaker.com/v2/ </code></pre> <h2 id="authentication">Authentication</h2> <p>Spreaker APIs use OAuth2 to handle user authentication. See <a href="/guides/authentication/">Authentication</a> to understand how you can obtain a valid OAuth2 token to perform API requests on behalf of the user.</p> <p>In general, all <code>PUT</code>, <code>POST</code> and <code>DELETE</code> requests MUST be authenticated in order to succeed. However, <code>GET</code> requests do not require authentication unless otherwise documented.</p> <p>Once you have a valid token, you can use it in two different ways:</p> <p>#### OAuth2 Token (sent in a header)</p> <figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span></span>curl -H <span class="s2">"Authorization: Bearer OAUTH-TOKEN"</span> https://api.spreaker.com/v2/me</code></pre></figure> <h4 id="oauth2-token-sent-as-a-parameter">OAuth2 Token (sent as a parameter)</h4> <figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span></span>curl https://api.spreaker.com/v2/me?oauth2_access_token<span class="o">=</span>OAUTH-TOKEN</code></pre></figure> <p>Authenticating with invalid credentials will return as <code>401 Unauthorized</code>.</p> <h2 id="request-and-response-format">Request and Response Format</h2> <p>All data is received as <strong>JSON</strong> and wrapped in a <code>response</code> property.</p> <h4 id="example-successful-response">Example: Successful Response</h4> <figure class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span> <span class="nt">"response"</span><span class="p">:</span> <span class="p">{</span> <span class="nt">"user"</span><span class="p">:</span> <span class="p">{</span> <span class="nt">"user_id"</span><span class="p">:</span> <span class="mi">1</span><span class="p">,</span> <span class="nt">"fullname"</span><span class="p">:</span> <span class="s2">"Marco Pracucci"</span><span class="p">,</span> <span class="nt">"site_url"</span><span class="p">:</span> <span class="s2">"https://www.spreaker.com/user/marco"</span> <span class="p">}</span> <span class="p">}</span> <span class="p">}</span></code></pre></figure> <p>If there are any errors, you will receive the most appropriate <code>4xx</code> or <code>5xx</code> HTTP status code and the <code>response</code> will include an <code>error</code> object containing one or more error messages.</p> <h4 id="example-error-response">Example: Error Response</h4> <figure class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span> <span class="nt">"response"</span><span class="p">:</span> <span class="p">{</span> <span class="nt">"error"</span><span class="p">:</span> <span class="p">{</span> <span class="nt">"messages"</span><span class="p">:</span> <span class="p">[</span><span class="s2">"The provided API uri is unknown"</span><span class="p">],</span> <span class="nt">"code"</span><span class="p">:</span> <span class="mi">404</span> <span class="p">}</span> <span class="p">}</span> <span class="p">}</span></code></pre></figure> <h3 id="timestamps">Timestamps</h3> <p>All timestamps are in <code>YYYY-MM-DD HH:MM:SS</code> format and in the <strong>UTC</strong> timezone, except where otherwise stated.</p> <h2 id="charset-utf-8">Charset (UTF-8)</h2> <p>Spreaker APIs currently support only <strong>UTF-8 charset encoding</strong>. Please, make sure your request body data is encoded in <strong>UTF-8</strong>.</p> <h2 id="pagination">Pagination</h2> <p>Requests that return multiple items are paginated. The responses will contain <code>items</code>, an array of JSON objects, and <code>next_url</code>, the URL of the next “page” of data.</p> <p>By default, each “page” contains 50 items. You can customize this value using the <code>limit</code> query parameter to request up to 100 items.</p> <p>Each API can use a different parameter to select a “page”. That way the response will contain the <code>next_url</code> property. You should use that particular URL for loading more content instead of constructing your own.</p> <h4 id="example">Example</h4> <figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span></span>curl https://api.spreaker.com/v2/users/8114541/shows?limit<span class="o">=</span><span class="m">3</span></code></pre></figure> <p>Response</p> <figure class="highlight"><pre><code class="language-json" data-lang="json"><span></span><span class="p">{</span> <span class="nt">"response"</span><span class="p">:</span> <span class="p">{</span> <span class="nt">"items"</span><span class="p">:</span> <span class="p">[</span> <span class="p">{</span> <span class="nt">"show_id"</span><span class="p">:</span> <span class="mi">1396918</span><span class="p">,</span> <span class="err">...</span> <span class="p">},</span> <span class="p">{</span> <span class="nt">"show_id"</span><span class="p">:</span> <span class="mi">1433865</span><span class="p">,</span> <span class="err">...</span> <span class="p">},</span> <span class="p">{</span> <span class="nt">"show_id"</span><span class="p">:</span> <span class="mi">1634369</span><span class="p">,</span> <span class="err">...</span> <span class="p">}</span> <span class="p">],</span> <span class="nt">"next_url"</span><span class="p">:</span> <span class="s2">"https://api.spreaker.com/v2/users/8114541/shows?offset=3&limit=3"</span> <span class="p">}</span> <span class="p">}</span></code></pre></figure> <h2 id="localization">Localization</h2> <p>Some Spreaker APIs return content that can be localized, passing a supported culture via the <code>c</code> parameter.</p> <h4 id="example-1">Example</h4> <p>The <code>GET /v2/show-categories</code> returns all available show categories in English by default, but you can get Italian category name translations by invoking:</p> <figure class="highlight"><pre><code class="language-bash" data-lang="bash"><span></span>curl https://api.spreaker.com/v2/show-categories?c<span class="o">=</span>it_IT</code></pre></figure> <h4 id="supported-cultures">Supported cultures</h4> <ul> <li><code>en_US</code> (default)</li> <li><code>it_IT</code></li> <li><code>es_ES</code></li> </ul> <h2 id="rate-limiting">Rate Limiting</h2> <p>Spreaker APIs adopt a rate limiting policy. We kindly ask you to play nicely with our APIs, and you should never hit the rate limit. In case you do hit the limit, your IP address will be temporarily blacklisted and each subsequent API request will result in the <code>429 Too Many Requests</code> response.</p> <h2 id="command-line-tools-used-in-examples">Command Line Tools Used in Examples</h2> <p>Looking at the examples you can find the following command-line tools:</p> <ul> <li><a href="https://curl.haxx.se/">curl</a></li> <li><a href="https://github.com/trentm/json">json</a></li> </ul> </div> <!-- Menu --> <nav id="page_menu" class="page_menu"> <div class="page_menu_item"> <h2><a href="/api/">API</a></h2> <h3>Complete API Reference</h3> <ul> <li> <h4><a href="/api/users/" title="Users">Users</a></h4> </li> <li> <h4><a href="/api/shows/" title="Shows">Shows</a></h4> </li> <li> <h4><a href="/api/show-rss-metadata/" title="Show RSS Metadata">Show RSS Metadata</a></h4> </li> <li> <h4><a href="/api/episodes/" title="Episodes">Episodes</a></h4> </li> <li> <h4><a href="/api/episode-messages/" title="Episode Messages">Episode Messages</a></h4> </li> <li> <h4><a href="/api/episode-chapters/" title="Episode Chapters">Episode Chapters</a></h4> </li> <li> <h4><a href="/api/episode-cuepoints/" title="Episode Cuepoints">Episode Cuepoints</a></h4> </li> <li> <h4><a href="/api/statistics/" title="Statistics">Statistics</a></h4> </li> <li> <h4><a href="/api/search/" title="Search">Search</a></h4> </li> <li> <h4><a href="/api/explore/" title="Explore">Explore</a></h4> </li> <li> <h4><a href="/api/tags/" title="Tags">Tags</a></h4> </li> <li> <h4><a href="/api/widgets/" title="Widgets">Widgets</a></h4> </li> <li> <h4><a href="/api/miscellaneous/" title="Miscellaneous">Miscellaneous</a></h4> </li> </ul> </div> <div class="page_menu_item"> <h2><a href="/guides/">GUIDES</a></h2> <h3>Getting Started Guides</h3> <ul> <li> <h4><a href="/guides/overview/" title="Overview">Overview</a></h4> <ul class="section-nav"> <li class="toc-entry toc-h2"><a href="#url">URL</a></li> <li class="toc-entry toc-h2"><a href="#authentication">Authentication</a></li> <li class="toc-entry toc-h4"><a href="#oauth2-token-sent-as-a-parameter">OAuth2 Token (sent as a parameter)</a></li> <li class="toc-entry toc-h2"><a href="#request-and-response-format">Request and Response Format</a></li> <li class="toc-entry toc-h4"><a href="#example-successful-response">Example: Successful Response</a></li> <li class="toc-entry toc-h4"><a href="#example-error-response">Example: Error Response</a></li> <li class="toc-entry toc-h3"><a href="#timestamps">Timestamps</a></li> <li class="toc-entry toc-h2"><a href="#charset-utf-8">Charset (UTF-8)</a></li> <li class="toc-entry toc-h2"><a href="#pagination">Pagination</a></li> <li class="toc-entry toc-h4"><a href="#example">Example</a></li> <li class="toc-entry toc-h2"><a href="#localization">Localization</a></li> <li class="toc-entry toc-h4"><a href="#example-1">Example</a></li> <li class="toc-entry toc-h4"><a href="#supported-cultures">Supported cultures</a></li> <li class="toc-entry toc-h2"><a href="#rate-limiting">Rate Limiting</a></li> <li class="toc-entry toc-h2"><a href="#command-line-tools-used-in-examples">Command Line Tools Used in Examples</a></li> </ul> </li> <li> <h4><a href="/guides/authentication/" title="Authentication">Authentication</a></h4> </li> <li> <h4><a href="/guides/upload-an-episode/" title="Upload an episode">Upload an episode</a></h4> </li> <li> <h4><a href="/guides/manage-your-shows/" title="Manage your Shows">Manage your Shows</a></h4> </li> <li> <h4><a href="/guides/manage-your-episodes/" title="Manage Your Episodes">Manage Your Episodes</a></h4> </li> <li> <h4><a href="/guides/working-with-draft-episodes/" title="Working with Draft Episodes">Working with Draft Episodes</a></h4> </li> <li> <h4><a href="/guides/displaying-the-episode-s-waveform/" title="Displaying the Episode's Waveform">Displaying the Episode's Waveform</a></h4> </li> <li> <h4><a href="/guides/embedding-the-player/" title="Embedding the Player">Embedding the Player</a></h4> </li> <li> <h4><a href="/guides/user-agent-format/" title="User Agent format">User Agent format</a></h4> </li> <li> <h4><a href="/guides/terminology/" title="Terminology">Terminology</a></h4> </li> </ul> </div> </nav> </div> </main> <!-- Footer --> <footer> <ul class="ft_links"> <li><a href="https://www.spreaker.com">Spreaker</a></li> <li><a href="https://www.spreaker.com/terms">Terms</a></li> <li><a href="https://www.spreaker.com/privacy">Privacy</a></li> <li><a href="https://help.spreaker.com">Support</a></li> <li><a href="https://status.spreaker.com">Status</a></li> </ul> <small class="ft_copyright">Copyright 2024 - Spreaker Inc. - New York, NY</small> </footer> </body> </html>