API: Episodes

In this page

The Episode object

An Episode is an audio track that can be listened to. It can be recorded or broadcasted live, and always belongs to a Show. An episode could be a podcast episode, a music track or song, a radio show episode, or a live broadcast.

An episode has several properties. Each API can return an Episode model all those properties, or just a subset. All the properties are listed here:

Property Type Description
episode_id Numeric Unique episode identifier
type String The episode type. It could be DRAFT, RECORDED, LIVE or EXTERNAL
title String Episode title
description String Episode description
duration Numeric Episode duration expressed in milliseconds
site_url String Public URL of the episode on Spreaker’s website
image_original_url String Original size image URL
image_url String 200x200px size image URL
published_at String The date/time on which this episode has been published
auto_published_at String The date/time on which this episode has been scheduled to be published later
author User The author/owner of the episode
author_id Numeric User ID of the episode author
show Show The show the episode belongs to
show_id Numeric Show ID of the show this episodes belongs to
download_enabled Boolean true if the author allowed this episode to be downloaded, otherwise false
plays_count Numeric The number of overall plays of this episode (both live and on demand). The value is null if the Statistics are temporarily not available.
downloads_count Numeric The number of overall downloads of this episode. The value is null if the Statistics are temporarily not available.
plays_ondemand_count Numeric The number of overall on demand plays of this episode. The value is null if the Statistics are temporarily not available.
plays_live_count Numeric The number of overall live plays of this episode. The value is null if the Statistics are temporarily not available.
likes_count Numeric The number of overall likes of this episode. The value is null if the Statistics are temporarily not available.
messages_count Numeric The number of overall messages of this episode. The value is null if the Statistics are temporarily not available.
is_on_air Boolean This property is exported only on LIVE episodes. The value is true if the episode’s live stream is currently active (broadcasting), otherwise it’s false
is_non_stop Boolean This property is exported only on LIVE episodes. The value is true if the episode live stream is 24/7 (non stop), otherwise it’s false
encoding_status String The episode’s status, whether it’s either processing or encoding. The episode can be listened to only when the encoding_status is READY.
waveform_url String URL of the episode’s waveform data points (see Displaying the Episode Waveform for more information). The value is null if the episode has no waveform (ie. LIVE episodes or DRAFT episodes without any media file yet).
tags Array List of tags/keywords related to the content.
hidden Boolean Whether the episode is accessible publicly, either on website or RSS feeds.
visibility String The specific visibility status of the episode. It could be PUBLIC, PRIVATE or LIMITED.
site_limited_url String The site link that gives access to a LIMITED episode. This is generated when the visibility of an episode is changed to LIMITED. LIMITED episodes are not listed on the website or RSS feeds.
site_limited_key String The episode private key that provides access to the episode.
media_id Numeric The ID of the episode media
media_url String URL of the episode’s media. The value is null if the episode has no media or media is not available (ie. LIVE episodes or DRAFT episodes without any media file yet).
download_url String URL for episodes’s download.
playback_url String URL for episodes’s playback.

The type field can have the following values:

  • LIVE: the episode is currently LIVE. By playing this episode you’ll be able to listen directly to its live stream. The duration field could be absent or null, because the duration of a live episode is unknown.
  • RECORDED: the episode has been uploaded, or it was once a LIVE episode that ended and has been archived. You can safely read and display the duration field.
  • EXTERNAL: the episode is not hosted on Spreaker, but on a 3rd party and is available to be listened to. You can safely read and display the duration field. This type of episode cannot be created via APIs.
  • DRAFT: the episode is in a draft state and has not been published yet. In this state, the episode could have no audio file associated with it yet: once it does have an audio file, it can be immediately published by setting published_at, or scheduled to be published later by setting auto_published_at (in both cases the type will switch to RECORDED).

The encoding_status field can have the following values:

  • PENDING: the episode is in queue and waiting to be processed or it has no audio file yet (see Working with draft episodes).
  • PROCESSING: the episode is currently processing. This operation could take a while, depending on the episode’s duration.
  • READY: the episode has been successfully processed and is ready to be listened to.
  • ERROR: an error occurred while processing the episode.

The visibility field can have the following values:

  • PUBLIC: the episode is publicly accessible through Website, Widget, Apps and on RSS feed.
  • PRIVATE: the episode is not accessible in any platform in a public way. Only the owner of the episode can see it.
  • LIMITED: the episode is accessible on the Website through a special url and in the Widget using the following query parameter episode_key=<SITE_LIMITED_KEY>

Retrieving a Single Episode

GET /v2/episodes/EPISODE-ID

The returned Episode contains most of all its public information, from its title and description, to its author (a User model) and its show (a Show model).

Example

curl https://api.spreaker.com/v2/episodes/7760317

The response body is a JSON object containing all the episodes fields (plus the author and show public fields).

{
    "response": {
        "episode": {
            "episode_id": 7760317,
            "type": "RECORDED",
            "title": "SLS45: Music in Podcasts, Aaron Roden, Air-Raid Podcast",
            "duration": 2240180,
            "show_id": 1433865,
            "author_id": 8114541,
            "site_url": "https://www.spreaker.com/episode/7760317",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "published_at": "2016-02-10 23:00:40",
            "download_enabled": true,
            "download_url": "https://api.spreaker.com/v2/episodes/7760317/download.mp3",
            "playback_url": "https://api.spreaker.com/v2/episodes/7760317/play.mp3",
            "description": "Spreaker Live Show #45 for Feb 10th, 2016",
            "created_at": "2016-02-10 23:00:40",
            "plays_count": 125,
            "plays_ondemand_count": 100,
            "plays_live_count": 25,
            "downloads_count": 90,
            "likes_count": 4,
            "messages_count": 9,
            "visibility": "PUBLIC",
            "author": {
                "user_id": 8114541,
                "fullname": "Spreaker Live Show",
                "site_url": "https://www.spreaker.com/user/spreakerliveevents",
                "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/da9b085ab425d819e5de6f978487a487.jpg",
                "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/da9b085ab425d819e5de6f978487a487.jpg"
            },
            "show": {
                "show_id": 1433865,
                "title": "Spreaker Live Show with Rob Greenlee",
                "site_url": "https://www.spreaker.com/show/spreaker-live-show",
                "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
                "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
                "author_id": 8114541
            }
        }
    }
}

Updating an Episode

POST /v2/episodes/EPISODE-ID

Authenticated: yes. Owner: yes

The API POST /v2/episodes/EPISODE-ID supports these parameters, none of which are required, as you should specify only the ones you want to update:

Parameter Type Description
title String Max length: 140
description String -
show_id Numeric The unique show ID that this episode belongs to. Changing this value means moving the episode to another show.
explicit Boolean true if the episode contains explicit content (defaults to false)
download_enabled Boolean true if the episode can be downloaded (defaults to true)
hidden Boolean true if the episode should not be visible on public pages and listings (defaults to false)
visibility String The specific visibility status of the episode. It could be PUBLIC, PRIVATE or LIMITED. If the LIMITED visibility is set but it’s not available, PRIVATE will be used instead.
tags String Comma-separated list of tags/keywords related to the content. Adding tags improves searchability.
autopermalink Boolean true to automatically generate a unique permalink based on the episode’s title (defaults to false)
permalink String Allows you to change the episode’s permalink (keeping it unchanged if not provided). The provided permalink must be unique across the owner’s episodes.
location_latitude Numeric Latitude of the GPS coordinates related to this episode
location_longitude Numeric Longitude of the GPS coordinates related to this episode
image_file File At least 400x400, Max size: 5MB, Formats: JPG, PNG
image_crop String Comma-separated coordinates (top left X, top left Y, bottom right X, bottom right Y) used to crop an image_file. If not specified, the image_file will not be cropped. This parameter is effective only if the request contains an image_file.
published_at String The date/time when the episode was published. It can be edited only for RECORDED episodes.
auto_published_at String The date/time when the episode has been scheduled to be published (as in published at a later date/time). If the episode has been scheduled to be published later, it can be edited by changing the date / time it will be published or by setting an empty string to switch it back to an “unscheduled” state.
media_file File The audio file that should be associated with this episode. You can use this API to both upload a media_file for the first time, or replace the media_file associated with an episode that already has one.
chapters String JSON-encoded array of chapters that should be associated with this episode. Chapters are a sort of bookmarks for your episode and are mainly used to give listeners an easy way to fast forward to certain topics within your episode. See Uploading an Episode with Chapters for more information about the format.
autoshares String Enable auto-sharing to social networks. The value can be a comma separated list of values: FACEBOOK, TWITTER, TUMBLR, YOUTUBE. Auto-sharing can be configured only on non published episodes and it’s required your account to be connected to the respective social network in order to work.
season_episode_type String Type of the episode. It could be FULL, TRAILER, and BONUS.
season_number Numeric Season number of the episode.
episode_number Numeric Episode number of the episode.
rss_guid String Unique identifier for the episode exposed in the RSS feed.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "title=Title" https://api.spreaker.com/v2/episodes/12345678

The response body is a JSON object containing all the episode fields (and some related data).

{
    "response": {
        "episode": {
            "episode_id": 77180,
            "type": "RECORDED",
            "title": "Title",
            "duration": 193698,
            "show_id": 1,
            "author_id": 1,
            "site_url": "https://www.spreaker.com/episode/77180",
            "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/1ab1c553452369f36344fd84a55ef837.jpg",
            "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/1ab1c553452369f36344fd84a55ef837.jpg",
            "published_at": "2016-02-07 13:54:54",
            "download_enabled": true,
            "description": null,
            "explicit": false,
            "permalink": "i-love-coldplay",
            "plays_count": 0,
            "plays_ondemand_count": 0,
            "plays_live_count": 0,
            "downloads_count": 1,
            "likes_count": 0,
            "messages_count": 0,
            "author": {
                "user_id": 1,
                "fullname": "Marco",
                "site_url": "https://www.spreaker.com/user/marco",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/ccd7e21f9b6fc580178db084356094b6.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/ccd7e21f9b6fc580178db084356094b6.jpg"
            },
            "show": {
                "show_id": 1,
                "title": "rgsdfgaaaaasdfgsfg",
                "site_url": "https://www.spreaker.com/show/aaaaa_5",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/1ab1c553452369f36344fd84a55ef837.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/1ab1c553452369f36344fd84a55ef837.jpg",
                "author_id": 1
            },
            "tags": [],
            "encoding_status": "READY",
            "hidden": false,
            "visibility": "PUBLIC",
            "auto_published_at": null,
            "autoshares": [],
            "created_at": "2016-02-07 13:54:54",
            "updated_at": "2016-04-18 15:03:57"
        }
    }
}

Deleting an Episode

DELETE /v2/episodes/EPISODE-ID

Authenticated: yes

Delete a particular episode. This requires the request to be authenticated with the episode’s author credentials.

Example

curl -X DELETE -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/episodes/7912694

Downloading an Episode

Authenticated: optional

GET /v2/episodes/EPISODE-ID/download
GET /v2/episodes/EPISODE-ID/download.mp3

Downloads a particular episode. This action is only available on episodes with download_enabled set to true or if the request is authenticated as the owner of the content.

We strongly suggest to use a well formatted User-Agent of all your requests, and expecially for episode play and download endpoints, because the name of your application will appear in our Sources Statistics. See User Agent format to learn more.

Example

curl https://api.spreaker.com/v2/episodes/7760317/download
curl -H "Authorization: Bearer OAUTH-TOKEN" "https://api.spreaker.com/v2/episodes/EPISODE-ID/download"

Playing an Episode

GET /v2/episodes/EPISODE-ID/play
GET /v2/episodes/EPISODE-ID/play.mp3

Plays/streams a particular episode.

We strongly suggest to use a well formatted User-Agent of all your requests, and expecially for episode play and download endpoints, because the name of your application will appear in our Sources Statistics. See User Agent format guide to learn more.

Example

curl https://api.spreaker.com/v2/episodes/7760317/play

Uploading a Recorded Episode

POST /v2/shows/SHOW-ID/episodes

Authenticated: yes. Owner: yes

The API POST /v2/shows/SHOW-ID/episodes creates a new RECORDED episode with the uploaded media_file audio file. The request must be authenticated with the SHOW-ID’s owner credentials.

The only required parameters are the title and media_file: all other parameters are optional and can be edited later. Check out the Upload an Episode guide to get more information and working examples.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F media_file=@audio.mp3 -F "title=Daily News" https://api.spreaker.com/v2/shows/1/episodes

The response body is a JSON object containing all the episode fields (and some related data).

{
    "response": {
        "episode": {
            "episode_id": 129229,
            "type": "RECORDED",
            "title": "Daily News",
            "duration": 256104,
            "show_id": 64,
            "author_id": 1,
            "site_url": "https://www.spreaker.com/episode/129229",
            "image_url": null,
            "image_original_url": null,
            "published_at": "2016-07-04 09:51:57",
            "download_enabled": true,
            "description": null,
            "explicit": false,
            "permalink": "daily-news_5",
            "plays_count": 0,
            "plays_ondemand_count": 0,
            "plays_live_count": 0,
            "downloads_count": 0,
            "likes_count": 0,
            "messages_count": 0,
            "author": {
                "user_id": 1,
                "fullname": "Marco",
                "site_url": "https://www.spreaker.com/user/marco",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/ccd7e21f9b6fc580178db084356094b6.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/ccd7e21f9b6fc580178db084356094b6.jpg"
            },
            "show": {
                "show_id": 64,
                "title": "La bamba",
                "site_url": "https://www.spreaker.com/show/la-bamba",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/b91c2eac2986522f7ab1e5904768407f.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/b91c2eac2986522f7ab1e5904768407f.jpg",
                "author_id": 1
            },
            "tags": [],
            "media_id": 6093,
            "media_url": "http://d1xg9iidblidzv.cloudfront.net/episodes/original/6093",
            "encoding_status": "READY",
            "hidden": false,
            "visibility": "PUBLIC",
            "auto_published_at": null,
            "autoshares": [],
            "created_at": "2016-07-04 09:51:57",
            "updated_at": "2016-07-04 09:51:57"
        }
    }
}

Creating a Draft Episode

POST /v2/episodes/drafts

Authenticated: yes.

The API POST /v2/episodes/drafts creates a new DRAFT episode and supports all the parameters of the Updating an Episode API.

The only required parameters are the title and show_id: all other parameters are optional and can be edited later. Check out the working with draft episodes guide to get more details about draft episodes.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "title=Daily News" -F "show_id=SHOW-ID" https://api.spreaker.com/v2/episodes/drafts

The response body is a JSON object containing all the episode fields (and some related data).

{
    "response": {
        "episode": {
            "episode_id": 101067,
            "type": "DRAFT",
            "title": "Daily News",
            "duration": null,
            "show_id": 64,
            "author_id": 1,
            "site_url": "https://www.spreaker.com/episode/101067",
            "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/51d3ff4fec6a4f74c8014ae98c0fdb59.jpg",
            "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/51d3ff4fec6a4f74c8014ae98c0fdb59.jpg",
            "published_at": null,
            "download_enabled": true,
            "description": null,
            "explicit": false,
            "permalink": "daily-news_4",
            "plays_count": 0,
            "plays_ondemand_count": 0,
            "plays_live_count": 0,
            "downloads_count": 0,
            "likes_count": 0,
            "messages_count": 0,
            "author": {
                "user_id": 1,
                "fullname": "Marco",
                "site_url": "https://www.spreaker.com/user/marco",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/ccd7e21f9b6fc580178db084356094b6.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/ccd7e21f9b6fc580178db084356094b6.jpg"
            },
            "show": {
                "show_id": 64,
                "title": "La bamba",
                "site_url": "https://www.spreaker.com/show/la-bamba",
                "image_url": "https://d16p0vxkuq1hni.cloudfront.net/large/51d3ff4fec6a4f74c8014ae98c0fdb59.jpg",
                "image_original_url": "https://d1botjg6upurv.cloudfront.net/images.spreaker.com/original/51d3ff4fec6a4f74c8014ae98c0fdb59.jpg",
                "author_id": 1
            },
            "tags": [],
            "media_id": null,
            "encoding_status": "PENDING",
            "hidden": false,
            "visibility": "PUBLIC",
            "auto_published_at": null,
            "autoshares": [],
            "created_at": "2016-04-28 09:01:16",
            "updated_at": "2016-04-28 09:01:16"
        }
    }
}

Retrieving a User’s Episodes

GET /v2/users/USER-ID/episodes

This API returns a paginated list of Episodes that belong to a USER-ID. Each has just a subset of Episode properties.

Parameter Type Description
filter String Filter episodes by listenable or editable (defaults to listenable). If you specify filter=editable the request must be authenticated with the USER-ID’s owner credentials.
direction String Scans episodes forward or backward according to their natural order (defaults to forward). If you specify direction=backward the request must also include last_id.

Example

curl https://api.spreaker.com/v2/users/8114541/episodes?limit=3

The response body is a paginated list of Episodes.

{
    "response": {
        "items": [{
            "episode_id": 8937153,
            "type": "RECORDED",
            "title": "SLSPM70: Rob Cesternino, Host of Rob Has A Podcast, Post Show Recaps",
            "duration": 1166160,
            "show_id": 1433865,
            "author_id": 8114541,
            "site_url": "https://www.spreaker.com/episode/8937153",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "published_at": "2016-07-07 17:13:41",
            "download_enabled": true,
            "waveform_url": "https://d3770qakewhkht.cloudfront.net/episode_8937153.gz.json?v=j1qecT"
        }, {
            "episode_id": 8936994,
            "type": "RECORDED",
            "title": "SLSPM69: Marty Michael, Co-Founder of HeadGum Podcast Network",
            "duration": 1460430,
            "show_id": 1433865,
            "author_id": 8114541,
            "site_url": "https://www.spreaker.com/episode/8936994",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "published_at": "2016-07-07 16:47:54",
            "download_enabled": true,
            "waveform_url": "https://d3770qakewhkht.cloudfront.net/episode_8936994.gz.json?v=2fAdf6"
        }, {
            "episode_id": 8929762,
            "type": "RECORDED",
            "title": "SLSPM67: Rob McCracken, Director of Digital Solutions Group at Scripps Media/Midroll Media/Stitcher",
            "duration": 1866890,
            "show_id": 1433865,
            "author_id": 8114541,
            "site_url": "https://www.spreaker.com/episode/8929762",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
            "published_at": "2016-07-06 17:38:16",
            "download_enabled": true,
            "waveform_url": "https://d3770qakewhkht.cloudfront.net/episode_8929762.gz.json?v=AadaWY"
        }],
        "next_url": "https://api.spreaker.com/v2/users/8114541/episodes?filter=listenable&last_id=8929762&limit=3"
    }
}

Retrieving a Show’s Episodes

GET /v2/shows/SHOW-ID/episodes

This API returns a paginated list of Episodes that belong to a SHOW-ID. Each has just a subset of Episode properties.

Parameter Type Description
filter String Filter episodes by listenable or editable (defaults to listenable). If you specify filter=editable the request must be authenticated with the SHOW-ID’s owner credentials.
sorting String Sort episodes by newest first or oldest first (defaults to show’s settings - usually it’s newest).
direction String Scans episodes forward or backward according to their natural order (defaults to forward). If you specify direction=backward the request must also include last_id.

Example

curl https://api.spreaker.com/v2/shows/1433865/episodes?limit=3

The response body is a paginated list of Episodes.

{
  "response": {
    "items": [{
      "episode_id": 7869337,
      "type": "RECORDED",
      "title": "SLS48: Christian Radio Syndication and Podcasting, Matt Thomas of Know The Truth (KTT.org)",
      "duration": 1911380,
      "show_id": 1433865,
      "author_id": 8114541,
      "site_url": "https://www.spreaker.com/episode/7869337",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "published_at": "2016-02-25 20:30:27",
      "download_enabled": true
    }, {
      "episode_id": 7869150,
      "type": "RECORDED",
      "title": "SLS47: Christian Radio to Podcasting, Wayne Shepherd, Radio/Podcast Host",
      "duration": 1648200,
      "show_id": 1433865,
      "author_id": 8114541,
      "site_url": "https://www.spreaker.com/episode/7869150",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "published_at": "2016-02-25 20:01:34",
      "download_enabled": true
    }, {
      "episode_id": 7811083,
      "type": "RECORDED",
      "title": "SLS46: Faith-Based Podcasting, Dr. Jerry Johnson, CEO of National Religious Broadcasters",
      "duration": 1522700,
      "show_id": 1433865,
      "author_id": 8114541,
      "site_url": "https://www.spreaker.com/episode/7811083",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/5273f7f99089a54f85f58bd6b8c01cea.jpg",
      "published_at": "2016-02-17 23:00:57",
      "download_enabled": true
    }],
    "next_url": "https://api.spreaker.com/v2/shows/1433865/episodes?last_id=7811083&limit=3"
  }
}

Adding an Episode to Likes

PUT /v2/users/USER-ID/likes/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters. You can add an episode to your Likes list only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X PUT https://api.spreaker.com/v2/users/123/likes/456

The response body is an empty object.

{"response":[]}

Removing an Episode from Likes

DELETE /v2/users/USER-ID/likes/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters. You can remove an episode from Likes only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X DELETE https://api.spreaker.com/v2/users/123/likes/456

The response body is an empty object

{"response":[]}

Checking if an User likes an Episode

GET /v2/users/USER-ID/likes/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters, and return 200 if you like EPISODE-ID, 404 otherwise. You can check Likes only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X GET https://api.spreaker.com/v2/users/123/likes/456

The response body is an empty object

{"response":[]}

Retrieving Liked Episodes

GET /v2/users/USER-ID/likes

This API returns a paginated list of Episodes liked by the USER-ID. Each has just a subset of Episode properties.

Example

curl https://api.spreaker.com/v2/users/1/likes?limit=3

The response body is a paginated list of Episodes.

{
    "response": {
        "items": [{
            "episode_id": 7711204,
            "type": "LIVE",
            "title": "FQ Radio - Live",
            "duration": null,
            "show_id": 1632400,
            "author_id": 8587991,
            "site_url": "https://www.spreaker.com/episode/7711204",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/ad931f30150db8bc14409269db81826e.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/ad931f30150db8bc14409269db81826e.jpg",
            "published_at": "2016-02-04 14:05:14",
            "download_enabled": false,
            "is_non_stop": true
        }, {
            "episode_id": 7703522,
            "type": "EXTERNAL",
            "title": "Talking Heads - Psycho Killer",
            "duration": 146290,
            "show_id": 1555199,
            "author_id": 8432030,
            "site_url": "https://www.spreaker.com/episode/7703522",
            "image_url": null,
            "image_original_url": null,
            "published_at": "2016-02-02 10:25:23",
            "download_enabled": true
        }, {
            "episode_id": 7489480,
            "type": "RECORDED",
            "title": "New Year's Eve (w/Chris Radford)",
            "duration": 2494010,
            "show_id": 1607991,
            "author_id": 8457160,
            "site_url": "https://www.spreaker.com/episode/7489480",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/a8dfc4f39fcfc24eb783359bfb0b95bd.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/a8dfc4f39fcfc24eb783359bfb0b95bd.jpg",
            "published_at": "2016-01-04 11:00:28",
            "download_enabled": true
        }],
        "next_url": "https://api.spreaker.com/v2/users/1/likes?last_id=7489480&limit=3"
    }
}

Retrieving Users that Liked an Episode

GET /v2/episodes/EPISODE-ID/likes

This API returns a paginated list of Users that liked the EPISODE-ID. Each has just a subset of User properties.

Example

https://api.spreaker.com/v2/episodes/7711204/likes?limit=3

The response body is a paginated list of Users.

{
    "response": {
        "items": [{
            "user_id": 8559276,
            "fullname": "Best Hit Radio Dance",
            "site_url": "https://www.spreaker.com/user/8559276",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/97b370923d29db9318666a75f407124a.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/97b370923d29db9318666a75f407124a.jpg"
        }, {
            "user_id": 4696233,
            "fullname": "Gaia Bocelli",
            "site_url": "https://www.spreaker.com/user/4696233",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/a0f4aea20d19e2bdc74f9aa4d585f20c.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/a0f4aea20d19e2bdc74f9aa4d585f20c.jpg"
        }, {
            "user_id": 4633161,
            "fullname": "Tony R. Williams",
            "site_url": "https://www.spreaker.com/user/4633161",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/780255f43c15c77b8c480e7d6fa90487.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/780255f43c15c77b8c480e7d6fa90487.jpg"
        }],
        "next_url": "https://api.spreaker.com/v2/episodes/7711204/likes?last_id=4633161&limit=3"
    }
}

Adding an Episode to Bookmarks

PUT /v2/users/USER-ID/bookmarks/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters. You can add an episode to bookmarks only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X PUT https://api.spreaker.com/v2/users/123/bookmarks/456

The response body is an empty object

{"response":[]}

Removing an Episode from Bookmarks

DELETE /v2/users/USER-ID/bookmarks/EPISODE-ID

Authenticated: yes

This API does not have any additional parameters. You can remove an episode from bookmarks only on your own account, so the USER-ID parameter must match the owner of the token you’re using to authenticate the request.

Example

curl -X DELETE https://api.spreaker.com/v2/users/123/bookmarks/456

The response body is an empty object

{"response":[]}

Publishing an episode to YouTube

POST /v2/episodes/EPISODE-ID/youtube

Authenticated: yes

This API requests to publish an episode to YouTube, and requires to be authenticated with the episode’s author credentials. This operation is asynchronous and can take some time: you can poll the API to retrieve the status of the publishing to YouTube, to get updates about the progress.

The response contains the current status of the publishing to YouTube:

{
    "response": {
        "youtube": {
            "status": "PENDING",
            "videos": []
        }
    }
}

Retrieving the status of Episode publishing to YouTube

GET /v2/episodes/EPISODE-ID/youtube

Authenticated: yes

This API returns the current status of an episode publishing to YouTube, and requires to be authenticated with the episode’s author credentials. In particular, this API returns two main information:

  • status: the current status of the publishing to YouTube
  • videos: an ordered list of videos that have been generated to upload your episode to YouTube (if was successfully uploaded to YouTube)
{
    "response": {
        "youtube": {
            "status": "UPLOADED_PARTIAL",
            "videos": [{
                "video_title": "My episode (part 1 of 3)",
                "video_id": "1",
                "video_url": "https://www.youtube.com/watch?v=1",
                "video_status": "UPLOADED"
            }, {
                "video_title": "My episode (part 2 of 3)",
                "video_id": null,
                "video_url": null,
                "video_status": "DELETED"
            }, {
                "video_title": "My episode (part 3 of 3)",
                "video_id": "3",
                "video_url": "https://www.youtube.com/watch?v=3",
                "video_status": "UPLOADED"
            }]
        }
    }
}

The status property can have the following values:

Value Description
UNPUBLISHED The episode has not been published to YouTube.
PENDING The episode has been enqueued for publishing to YouTube.
DOWNLOADING The video generator is downloading the episode audio file.
PROCESSING The video generator is making the video file.
UPLOADING The video generator is uploading the video to YouTube.
UPLOADED The video has been successfully uploaded to YouTube.
UPLOADED_PARTIAL The video generator has splitted your episode into multiple video files (due to the max video duration limit on your YouTube account) and only few videos have been successfully uploaded to YouTube.
ERROR_AUTH The video generator was unable to upload the video on YouTube, due to an authentication error.
ERROR_DOWNLOAD The video generator was unable to make the video, because unable to download the episode audio file.
ERROR_PROCESSING The video generator has encountered an unexpected error while making the video.
ERROR_UPLOAD The video generator was unable to upload the video on YouTube, due to a network error.

The videos property is an array containing one or more videos. For each video you will find the following properties:

  • video_title: the YouTube video title.
  • video_id: the YouTube video id (can be null if the video has been removed).
  • video_url: the YouTube video url (can be null if the video has been removed).
  • video_status: the status of the video on YouTube (can be null if unable to retrieve it from YouTube).

The video_status property can have the following values:

Value Description
DELETED The video has been removed.
ERROR_PROCESSING An error occurred while processing the video on YouTube.
ERROR_REJECTED The video has been rejected by YouTube (ie. due to copyright infringement issues).
UPLOADED The video has been successfully uploaded and published to Youtube.
null Spreaker is unable to retrieve the current status of your video on YouTube (ie. the Spreaker account is not more connected to YouTube).

Why Spreaker sometimes split the episode into multiple videos?
YouTube has a limit of the max video duration that depends on your account. This limit is generally 15 minutes if your YouTube account has not been verified, or several hours otherwise. If your episodes get splitted into multiple videos, it means that your YouTube account has not been verified yet.