API: Shows

The Show object

A Show is a collection of Episodes owned by a single User called an Author.

A show has several properties. Each API can return a Show model in its entirety or with just a subset. All properties are listed here:

Property Type Description
show_id Numeric Unique show identifier
author User The author/owner of the show
author_id Numeric User ID of the show author
category_id Numeric Category ID of the show category
description String Show description
email String Contact email
facebook_url String Facebook page URL
itunes_url String iTunes page URL
image_original_url String Original size image URL
image_url String 200x200px size image URL
cover_image_url String The show’s cover image displayed on the Spreaker website
cover_offset Numeric Vertical offset that should be applied to the show’s cover image
last_episode_at String Date of a show’s latest published episode
site_url String Public URL of the show on the Spreaker website
skype_name String Skype username
sms_number String Text number
tel_number String Telephone (voice) number
title String Show title
twitter_name String Twitter username
website_url String Contact website
language String Show language
permalink String Show permalink
episodes_sorting String Type of episode sorting when getting show episodes

Many of the resources on the show APIs are related to a single show. If a request URL includes SHOW-ID it could be the numeric Show ID or the permalink.

Retrieving a Single Show

GET /v2/shows/SHOW-ID

The returned Show contains most of all its public information, from its title and description, to its author (a User model), to some contact information like the email, facebook_url or twitter_name.

Example

curl https://api.spreaker.com/v2/shows/1433865

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

{
  "response": {
    "show": {
      "author": {
        "description": "Hear the latest Spreaker Live Show every Weds at 3pm PST/6pm EST and New Media Expo, Podcast Movement, RAIN Summit, Dash Conference, Nielsen Audio Client Conference events.",
        "fullname": "Spreaker Live Show",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/da9b085ab425d819e5de6f978487a487.jpg",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/da9b085ab425d819e5de6f978487a487.jpg",
        "kind": "producer",
        "plan": "station",
        "site_url": "https://www.spreaker.com/user/spreakerliveevents",
        "user_id": 8114541,
        "username": "spreakerliveevents"
      },
      "author_id": 8114541,
      "description": "Tune in to the Spreaker Live Show, hosted by Rob Greenlee, Head of Content at Spreaker (@robgreenlee) for podcasting news, tips, and interviews with leading podcast hosts.

Every Wednesday at 3pm PST/6pm EST, you’ll catch Rob Greenlee guiding a new conversation on podcasting and its potential with experts in the industry. From microphones, to developing content, to monetization, podcast gurus will be offering up their own advice and experiences to draw from. Past guests include Adam Sachs, Chris Brogan, Robert Scoble, Todd Pringle, Sarah Van Mosel, and Rob Cesternino - with many more to come!

You’ll also hear the latest news on Spreaker, from newly released features to exciting new partnerships. Don’t miss tips on using the platform to its fullest potential and get yourself sounding like a pro. Podcasting has never been easier!

So come participate and interact with a rich community of audio creators and listeners using the best medium we know! Listen in live, and don’t forget to leave us your comments and feedback!",
      "email": null,
      "facebook_url": null,
      "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
      "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/b7c5bbccf92d94a33c384bd8eaab6f1d.jpg",
      "show_id": 1433865,
      "site_url": "https://www.spreaker.com/show/spreaker-live-show",
      "skype_name": null,
      "sms_number": null,
      "tel_number": null,
      "title": "Spreaker Live Show with Rob Greenlee",
      "twitter_name": null,
      "website_url": null
    }
  }
}

Updating a Show

POST /v2/shows/SHOW-ID

Authenticated: yes. Owner: yes

The API POST /v2/shows/SHOW-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 Min length: 5, Max length: 40
description String -
email String -
website_url String -
twitter_name String A Twitter handle, with or without the initial @, Max length: 15
skype_name String Min length: 6, Max length: 32
tel_number String Max length: 16
sms_number String Max length: 16
category_id Numeric See: Categories
language String ISO 639-1 language code. Allowed: sq ar be bg cs zh hr da et fi fr ja el is lt it en mk no nl pl pt ro ru sr sk sl es sv de tr uk hu
autopermalink Boolean true to automatically generate a unique permalink based on the show’s title (defaults to false)
permalink String Allows the show’s permalink to be changed (keeping it unchanged if not provided). The provided permalink must be unique.
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) are used to crop the image_file. If not specified, the image_file will not be cropped. This parameter is effective only if the request contains an image_file.
cover_image_file File The show’s cover image, Max size: 5MB, Formats: JPG, PNG
cover_offset Numeric Vertical offset that should be applied to the show’s cover image
episode_sorting String Type of episode sorting for this show: newest (newest to oldest) or oldest (oldest to newest)

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F image_file=@image.jpg -F "title=Title" -F "description=Text" -F "email=youremail@gmail.com" -F "website_url=www.yoursite.com" -F "twitter_name=yourtwitterhandle" -F "skype_name=yourskypename" -F "tel_number=123456789" -F "sms_number=987654321" -F "category_id=38" -F "language=it" https://api.spreaker.com/v2/shows/12345678

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

{
  "response": {
    "show": {
      "author": {...},
      "author_id": 12345678,
      "description": "Text",
      "email": "youremail@gmail.com",
      "facebook_url": "http://www.facebook.com/12345fg234234",
      "image_original_url": "IMAGE-ORIGINAL-URL",
      "image_url": "IMAGE-URL",
      "show_id": 12345678,
      "site_url": "https://www.spreaker.com/show/title",
      "permalink": "title",
      "skype_name": "yourskypename",
      "sms_number": "987654321",
      "tel_number": "123456789",
      "title": "Title",
      "twitter_name": "yourtwitterhandle",
      "website_url": "www.yoursite.com",
      "language": "it",
      "category_id": 38
    }
  }
}

Deleting a Show

DELETE /v2/shows/SHOW-ID

Authenticated: yes

Delete a particular show. This requires the request to be authenticated with the show’s author credentials and the show must have no episodes: if the show you want to delete has any episode, please delete all episodes first.

Example

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

Creating a Show

POST /v2/shows

Authenticated: yes.

The API POST /v2/shows creates a new show and supports all the parameters of the Updating a Show API.

The only required parameters are the title and language: all other parameters are optional and can be edited later.

Example

curl -X POST -H "Authorization: Bearer OAUTH-TOKEN" -F "title=Daily News" -F "language=en" https://api.spreaker.com/v2/shows

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

{
    "response": {
        "show": {
            "show_id": 932,
            "title": "Daily News",
            "site_url": "https://www.spreaker.com/show/daily-news",
            "image_url": null,
            "image_original_url": null,
            "author_id": 1,
            "description": null,
            "category_id": null,
            "language": "en",
            "permalink": "daily-news",
            "cover_image_url": null,
            "cover_offset": null,
            "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"
            },
            "fb_page_id": null,
            "fb_page_name": null,
            "created_at": "2016-05-23 12:32:52",
            "updated_at": "2016-05-23 12:32:52",
            "website_url": null,
            "email": null,
            "facebook_url": null,
            "itunes_url": null,
            "twitter_name": null,
            "skype_name": null,
            "tel_number": null,
            "sms_number": null,
            "listenable_episodes_count": 0,
            "editable_episodes_count": 0,
            "last_episode_at": null
        }
    }
}

Retrieving a User’s Shows

GET /v2/users/USER-ID/shows

This API returns a paginated list of Shows owned by the USER-ID. Each has just a subset of Show properties.

Parameter Type Description
filter String Filters shows by listenable or editable (defaults to listenable). If you specify filter=editable the request must be authenticated with USER-ID credentials.

Example

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

The response body is a paginated list of Shows.

{
  "response": {
    "items": [
      {
        "show_id": 1396918,
        "title": "Spreaker Live from NMX/NAB 2015",
        "site_url": "https://www.spreaker.com/show/spreaker-live-from-nmx-2015-episodes",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/d6b8f52a7f59a493130700e1b0b17d82.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/d6b8f52a7f59a493130700e1b0b17d82.jpg",
        "author_id": 8114541
      },
      {
        "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
      },
      {
        "show_id": 1634369,
        "title": "Spreaker National Radio Ad Spots",
        "site_url": "https://www.spreaker.com/show/spreaker-national-radio-ad-spots",
        "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/ac674e996ce37e7021c947317f246d44.jpg",
        "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/ac674e996ce37e7021c947317f246d44.jpg",
        "author_id": 8114541
      }
    ],
    "next_url": "https://api.spreaker.com/v2/users/8114541/shows?offset=3&limit=3"
  }
}

Adding a Show to Favorites

PUT /v2/users/USER-ID/favorites/SHOW-ID

Authenticated: yes

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

Parameter Type Description
notifications_enabled Boolean Enables or disables mobile push notifications when a new episode is published (defaults to true).

Example

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

The response body is an empty object

{"response":[]}

Removing a Show from Favorites

DELETE /v2/users/USER-ID/favorites/SHOW-ID

Authenticated: yes

This API does not have any additional parameters. You can remove a show from Favorites 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/favorites/456

The response body is an empty object

{"response":[]}

Retrieving Favorited Shows

GET /v2/users/USER-ID/favorites

This API returns a paginated list of Shows favorited by the USER-ID. Each has just a subset of Show properties.

Example

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

The response body is a paginated list of Shows.

{
    "response": {
        "items": [{
            "show_id": 1504423,
            "title": "Deejay Chiama Italia",
            "site_url": "https://www.spreaker.com/show/deejay-chiama-italia_1",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/8d78efe85a3df11a9f43f6b1fefd2257.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/8d78efe85a3df11a9f43f6b1fefd2257.jpg",
            "author_id": 8323188
        }, {
            "show_id": 1570902,
            "title": "War on the Rocks",
            "site_url": "https://www.spreaker.com/show/war-on-the-rocks",
            "image_url": null,
            "image_original_url": null,
            "author_id": 8464333
        }, {
            "show_id": 1557981,
            "title": "QUINTINO presents SupersoniQ Radio",
            "site_url": "https://www.spreaker.com/show/quintino-presents-supersoniq-radio",
            "image_url": "https://d1bm3dmew779uf.cloudfront.net/large/204416d33400d6d94eb30b4b9cbdd9b4.jpg",
            "image_original_url": "https://d3wo5wojvuv7l.cloudfront.net/images.spreaker.com/original/204416d33400d6d94eb30b4b9cbdd9b4.jpg",
            "author_id": 8437749
        }],
        "next_url": "https://api.spreaker.com/v2/users/1/favorites?last_id=1557981&limit=3"
    }
}

Uploading a Show Preroll

POST /v2/shows/SHOW-ID/preroll

Authenticated: yes. Owner: yes

The API POST /v2/shows/SHOW-ID/preroll adds a preroll (or audio intro) to your show. The request should upload the media_file audio file, and must be authenticated with the SHOW-ID’s owner credentials. For more information about the preroll data, please see Retrieving a Show Preroll.

Example

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

The response body is a JSON object containing the uploaded preroll.

{
    "response": {
        "preroll": {
            "media_id": 130,
            "media_url": "http://d1xg9iidblidzv.cloudfront.net/episodes/original/6093",
            "file_name": "my-custom-preroll.mp3",
            "encoding_status": "READY"
        }
    }
}

PRO: The show preroll / intro is a feature available only to users with Pro plans. Please check out the Spreaker Pro plans comparison table for more information.

Retrieving a Show Preroll

GET /v2/shows/SHOW-ID/preroll

Authenticated: yes. Owner: yes

The API returns the information about the current show preroll, or 404 status code if the show currently has no intro set. The request must be authenticated with the SHOW-ID’s owner credentials.

The Preroll object

Property Type Description
media_id Numeric Unique media identifier
media_url String The media download url. This property is valued only if the encoding_status is READY. Until the media processing has not complete, the media_url will be null.
file_name String The media’s original file name.
encoding_status String The media’s status, whether it’s either processing or encoding. The media can be listened to only when the encoding_status is READY.

The encoding_status property can have the following values:

  • PENDING: the media is in queue and waiting to be processed.
  • PROCESSING: the media is currently processing. This operation could take a while, depending on the media’s duration.
  • READY: the media has been successfully processed and is ready to be listened to.
  • ERROR: an error occurred while processing the media.

Example

curl -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/shows/1/preroll

The response body is a JSON object containing the preroll info.

{
    "response": {
        "preroll": {
            "media_id": 130,
            "media_url": "http://d1xg9iidblidzv.cloudfront.net/episodes/original/6093",
            "file_name": "my-custom-preroll.mp3",
            "encoding_status": "READY"
        }
    }
}

Deleting a Show Preroll

DELETE /v2/shows/SHOW-ID/preroll

Authenticated: yes. Owner: yes

Delete a show preroll. This requires the request to be authenticated with the show’s author credentials.

Example

curl -X DELETE  -H "Authorization: Bearer OAUTH-TOKEN" https://api.spreaker.com/v2/shows/1/preroll