API: Episodes
In this page
- The Episode object
- Retrieving a Single Episode
- Example
- Updating an Episode
- Example
- Deleting an Episode
- Example
- Downloading an Episode
- Example
- Playing an Episode
- Example
- Uploading a Recorded Episode
- Example
- Creating a Draft Episode
- Example
- Retrieving a User’s Episodes
- Example
- Retrieving a Show’s Episodes
- Example
- Adding an Episode to Likes
- Example
- Removing an Episode from Likes
- Example
- Checking if an User likes an Episode
- Example
- Retrieving Liked Episodes
- Example
- Retrieving Users that Liked an Episode
- Example
- Adding an Episode to Bookmarks
- Example
- Removing an Episode from Bookmarks
- Example
- Publishing an episode to YouTube
- Retrieving the status of Episode publishing to YouTube
- Publishing an episode to SoundCloud
- Retrieving the status of Episode publishing to SoundCloud
- Publishing an episode to iHeart
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 |
downloads_count |
Numeric | The number of overall downloads of this episode |
likes_count |
Numeric | The number of overall likes of this episode |
messages_count |
Numeric | The number of overall messages of this episode |
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). |
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. Theduration
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 theduration
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 theduration
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 settingpublished_at
, or scheduled to be published later by settingauto_published_at
(in both cases thetype
will switch toRECORDED
).
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 parameterepisode_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,
"description": "Spreaker Live Show #45 for Feb 10th, 2016",
"created_at": "2016-02-10 23:00:40",
"plays_count": 125,
"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 , SOUNDCLOUD , 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. |
ihr_publish |
Boolean | If false the episode will not be published on iHeart (defaults to true ). This option is ignored if the episode’s show has not been submitted and approved for publishing on iHeart. Please, see Publishing an episode to iHeart for more information. |
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,
"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
},
"segments": [{
"type": "audio_ad",
"target": {
"content_category": "finance",
"content_safe": "false",
"content_explicit": "false"
}
}, {
"type": "episode",
"http_url": "https://d1kuc8t06fl24.cloudfront.net/episodes/high/3099.mp3",
"http_url_expires_at": "2016-04-20 15:03:57"
}],
"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. The application_id
parameter is optional.
Parameter | Type | Description |
---|---|---|
application_id |
Numeric | Your application’s ID, if you want the download attributed to it. |
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. The application_id
parameter is optional.
Parameter | Type | Description |
---|---|---|
application_id |
Numeric | Your application’s ID, if you want the play attributed to it. |
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,
"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
},
"segments": [{
"type": "episode",
"http_url": "https://d1kuc8t06fl24.cloudfront.net/episodes/high/6093.mp3",
"http_url_expires_at": "2016-07-06 09:51:57"
}],
"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,
"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
},
"segments": [],
"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 YouTubevideos
: 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 benull
if the video has been removed).video_url
: the YouTube video url (can benull
if the video has been removed).video_status
: the status of the video on YouTube (can benull
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.
Publishing an episode to SoundCloud
POST /v2/episodes/EPISODE-ID/soundcloud
Authenticated: yes
This API requests to publish an episode to SoundCloud, 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 SoundCloud, to get updates about the progress.
The response contains the current status of the publishing to SoundCloud:
{
"response": {
"soundcloud": {
"status": "PENDING",
"track": null
}
}
}
Retrieving the status of Episode publishing to SoundCloud
GET /v2/episodes/EPISODE-ID/soundcloud
Authenticated: yes
This API returns the current status of an episode publishing to SoundCloud, 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 SoundCloudtrack
: the SoundCloud track’s metadata if was successfully uploaded to SoundCloud, otherwisenull
{
"response": {
"soundcloud": {
"status": "UPLOADED",
"track": {
"track_title": "Track title",
"track_id": 100000,
"track_url": "https://soundcloud.com/track",
"track_status": "READY"
}
}
}
}
The status
property can have the following values:
Value | Description |
---|---|
UNPUBLISHED |
The episode has not been published to SoundCloud. |
PENDING |
The episode has been enqueued for publishing to SoundCloud. |
DOWNLOADING |
The publishing tool is downloading the episode audio file. |
UPLOADING |
The publishing tool is uploading the audio to SoundCloud. |
UPLOADED |
The audio track has been successfully uploaded to SoundCloud. |
ERROR_AUTH |
The publishing tool was unable to upload the audio on SoundCloud, due to an authentication error. |
ERROR_DOWNLOAD |
The publishing tool was unable to upload the audio on SoundCloud, because unable to download the episode audio file. |
ERROR_UPLOAD |
The publishing tool was unable to upload the audio on SoundCloud, due to a network error. |
ERROR_QUOTA |
The publishing tool was unable to upload the audio on SoundCloud, because the SoundCloud account has reached the storage limit. |
ERROR_UNVERIFIED |
The publishing tool was unable to upload the audio on SoundCloud, because the SoundCloud account is not verified. Please visit https://soundcloud.com/settings to verify your account. |
The track
property contains some information about the uploaded SoundCloud track:
track_title
: the SoundCloud track title.track_id
: the SoundCloud track id.track_url
: the SoundCloud track url (can benull
if unable to retrieve it from SoundCloud).track_status
: the status of the track on SoundCloud (can benull
if unable to retrieve it from SoundCloud).
The track_status
property can have the following values:
Value | Description |
---|---|
PROCESSING |
The track has been uploaded to SoundCloud and it’s currently being processed. |
ERROR_PROCESSING |
An error occurred while processing the track on SoundCloud. |
READY |
The track has been successfully uploaded and processed on SoundCloud. |
null |
Spreaker is unable to retrieve the current status of your track on SoundCloud (ie. the Spreaker account is not more connected to SoundCloud). |
Publishing an episode to iHeart
POST /v2/episodes/EPISODE-ID/iheart
Authenticated: yes
This API requests to publish an episode to iHeart, and requires to be authenticated with the episode’s author credentials.
To publish an episode to iHeart, it’s required the episode’s show has been submitted and approved to be published on iHeart. We currently don’t provide a public API to submit your shows to iHeart, so you should do it thru the Spreaker CMS (it’s a one-time operation you have to do per each show you want to publish to iHeart).
The response contains the current status of the publishing to iHeart:
{
"response": {
"iheart": {
"ihr_status": "PUBLISHED",
"ihr_publish": true
}
}
}
The iheart
property contains two pieces of information:
ihr_status
: the current status of publishing to iHeart (can beUNPUBLISHED
,PENDING
orPUBLISHED
). Please note thatPUBLISHED
means the episode has been successfully submitted for publishing to iHeart, but then it could take some time to display on iHeart apps and website, due to their internal publishing mechanisms.ihr_publish
: this flag explicits your intention. Its value istrue
if you do want to publish the episode on iHeart,false
otherwise.