Josh Brown

Today we are excited to announce the launch of our new Podcast APIs, a set of API features that allow developers to build podcast experiences for Spotify users. You can use the Podcast APIs to search Spotify’s podcast catalog, programmatically follow or unfollow podcasts, and fetch information about episodes and podcast shows. Read on for more information about using the Podcast APIs in your app.

This launch includes nine new Web API endpoints:

• Subscribe to a list of shows:
  PUT https://api.spotify.com/v1/me/shows?ids={ids}
  This endpoint enables you to add a show or a list of shows to a user's library.
• Get a list of the current user's saved shows:
  GET https://api.spotify.com/v1/me/shows
  Use this endpoint to fetch the podcasts that a user has subscribed to.
• Get metadata for a single show:
  GET https://api.spotify.com/v1/shows/{id}
  Show metadata includes a podcast show's description, publisher, and show images (if available). You can also obtain the show's Spotify URI.
• Get metadata for a set of shows:
  GET https://api.spotify.com/v1/shows?ids={ids}
  
• List episodes for a show:
  GET https://api.spotify.com/v1/shows/{id}/episodes
  Use this endpoint to fetch a paginated list of episodes belonging to a podcast show.
• Get information about an episode:
  GET https://api.spotify.com/v1/episodes/{id}
  The episode object includes the episode description, language, duration and release date. If your app has the user-read-playback-position scope then the episode object also includes resume point information for the current user.
• Get information about a set of episodes:
  GET https://api.spotify.com/v1/episodes?ids={ids}
• Are the given shows in the current user's library?
  GET /v1/me/shows/contains?ids={ids}
  This endpoint allows your app to verify whether a set of podcast shows exist in a user's library.
• Unfollow a list of shows:
  DELETE https://api.spotify.com/v1/me/shows?ids={ids}

Three endpoints have been enhanced with new features that support podcasts:

• Fetch the currently playing content:

GET https://api.spotify.com/v1/me/player/currently-playing

• Get information about the user's current playback:

GET https://api.spotify.com/v1/me/player

These endpoints are now able to return information about a playing podcast episode. Set the type query parameter to episode,track if your client would like to receive information about currently playing tracks and episodes.

• Search Spotify's catalog for content:

GET https://api.spotify.com/v1/search
The search API now returns podcast shows and episodes. Set the type parameter to show or episode to query these new types of content.

The new APIs allow apps to retrieve episode resume points. Resume points tell your app about the user's position in podcast episodes that they've listened to. If your app requires access to this data then you'll want to request our new user-read-playback-position OAuth scope when users install your app. See Using Scopes for more information. Other podcast endpoints rely on existing Spotify scopes, or require no scopes at all.

The new podcast API endpoints are in beta. We anticipate that the features available today could be useful for writing apps that import shows to a user's Spotify library, integrations with calendar apps, or social podcasting experiences to help Spotify users share what they're listening to with their friends.

We plan to continue improving our podcasting APIs and we know that you may have suggestions for other APIs you'd like to see. Interested in giving us feedback? Drop us a note at podcasts-api-beta@spotify.com and let us know what Spotify platform features you'd like to see next.