API: Shows

In this page

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
category_2_id Numeric Category ID of the show category 2
category_3_id Numeric Category ID of the show category 3
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
owner_name String Owner’s name
author_name String Author’s name
copyright String Copyright

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
category_2_id Numeric See: Categories
category_3_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)
owner_name String Max length: 255
author_name String Max length: 255, used for field
copyright String Max length: 255, used for field

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,
      "category_2_id": null,
      "category_3_id": null,
      "author_name": null,
      "owner_name": null,
      "copyright": null
    }
  }
}

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,
            "category_2_id": null,
            "category_3_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,
            "owner_name": null,
            "author_name": null,
            "copyright": 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.
access_level String Fetches the user shows for USER-ID. Allowed values are: AUTHOR (default), SHOW_COLLABORATOR or USER_COLLABORATOR. AUTHOR fetches all of the shows of the user, SHOW_COLLABORATOR fetches the shows where the user is a collaborator and USER_COLLABORATOR fetches the shows of the network the user is a collaborator. You can pass multiple values separated by a comma, e.g. access_level=AUTHOR,SHOW_COLLABORATOR.

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"
    }
}