Podcast endpoints?

[seahorsepip]

Add endpoints to get, save, remove etc. podcasts.

[hughrawlinson]

Thanks for the feature request @seahorsepip!

[HenrikFricke]

@hughrawlinson Can you give us more insights? Is it on a roadmap? Thanks :)

[hughrawlinson]

Hi @HenrikFricke - we don't have a public roadmap at the moment, but any updates will be posted on developer.spotify.com, and this thread will be updated. Right now, there's no timeline for podcast endpoints.

[HenrikFricke]

@hughrawlinson okay, thanks for the answer :)

[ridhwaans]

+1 asking to bring podcasts to the web api. My pain is I cant fetch metadata for podcasts like this one https://open.spotify.com/episode/5TSsSAR7MHV2aC7jVvpvBw?si=ZMg7hkWOQa6lI383S2QEzQ
I'll have to start looking at other services

[RWOverdijk]

I'd love this as a feature, too. Just adding this due to radio silence

[jamescridland]

+1 from me - I'd like to link to Spotify from podcast pages like this one; as the #2 podcast destination in the world, it would be brilliant to link further to Spotify.

[kapilbahadur]

+1 Need this API to be open. There is no in-app feature to view the podcasts I've seen unless I individually go to a podcast, and filter by progress.

[gilibaus]

+1 from me too

[estysdesu]

+1 here also

[captainbenno]

@hughrawlinson who do we have to bribe to get this functionality available?

[patalanov]

+1 please

[Jakubem]

+1, that would be a great feature

[Worie]

indeed, +1

[emily-morris]

+1

[Grace]

+1. I'm currently writing an app to get recent episodes for a podcast and push the data to a webhook. I thought Spotify would make this easy, but it looks like I'll have to make my own solution.

[suissemaxx]

+1

[rochabianca]

+1

[nathangathright]

Podcasts now appear to be showing up in search on open.spotify.com

[jamescridland]

@nathangathright That's nice to know - but sadly, there's still no sign of them in the web API. Unless we know different!

[jamescridland]

Actually... ah, this is interesting. So, podcasts are appearing under this URL:

https://api.spotify.com/v1/search?type=album%2Cartist%2Cplaylist%2Ctrack%2Cshow_audio%2Cepisode_audio&q=podnews*&decorate_restrictions=false&best_match=true&limit=50&userless=true&market=AU

This works ONLY if you have a valid token. There appears to be an Authorization header sent.

Here's a snippet of what it returns:

"shows" : {
    "href" : "https://api.spotify.com/v1/search?query=podne*&type=show&market=AU&offset=0&limit=50",
    "items" : [ {
      "available_markets" : [ "AD", "AR", "AT", "AU", "BE", "BG", "BO", "BR", "CA", "CH", "CL", "CO", "CR", "CY", "CZ", "DE", "DK", "DO", "EC", "EE", "ES", "FI", "FR", "GB", "GR", "GT", "HK", "HN", "HU", "ID", "IE", "IL", "IS", "IT", "JP", "LI", "LT", "LU", "LV", "MC", "MT", "MX", "MY", "NI", "NL", "NO", "NZ", "PA", "PE", "PH", "PL", "PT", "PY", "RO", "SE", "SG", "SK", "SV", "TH", "TR", "TW", "US", "UY", "VN", "ZA" ],
      "copyrights" : [ ],
      "description" : "Weekly updates for the podcast and on-demand industry, from podnews.net. Sign up for daily news via email at https://podnews.net/  Our daily podcast is available in iTunes and other podcast apps. This podcast is hosted by Omny Studio - https://omnystudio.com/learn",
      "explicit" : false,
      "external_urls" : {
        "spotify" : "https://open.spotify.com/show/6p1jX1AC0O7yiZ5JdyOmfp"
      },
      "href" : "https://api.spotify.com/v1/shows/6p1jX1AC0O7yiZ5JdyOmfp",
      "id" : "6p1jX1AC0O7yiZ5JdyOmfp",
      "images" : [ {
        "height" : 640,
        "url" : "https://i.scdn.co/image/8cb8a92e7d9235172b5159500326d6c5cbfdd92e",
        "width" : 640
      }, {
        "height" : 300,
        "url" : "https://i.scdn.co/image/ed13a822c594f9439660c838fe8a67f63618b896",
        "width" : 300
      }, {
        "height" : 64,
        "url" : "https://i.scdn.co/image/d33567933e11b4a1389e31378e50851d9d72ce02",
        "width" : 64
      } ],
      "languages" : [ "en-GB" ],
      "media_type" : "audio",
      "name" : "Podnews - weekly podcast news",
      "publisher" : "Podnews.net",
      "type" : "show",
      "uri" : "spotify:show:6p1jX1AC0O7yiZ5JdyOmfp"
    }

...so the "type" is the undocumented "show" in this instance.

[panmona]

@jamescridland But that only works if you know what podcast to search for right?

[jamescridland]

@maracuja-juice Yes, I haven't tried any of the other API end points. My suspicion is that they should all behave in the same way - use the undocumented "show". But I've not tried them or tested them.

[drpancake]

@jamescridland I couldn't find a documented API endpoint to do this when I was searching a few weeks ago - not for lack of trying.

The web player exposes a bunch of undocumented APIs for almost anything you might need, including podcast search, but obtaining a valid token in a repeatable automated way is an adventure.

[panmona]

@drpancake The normal token when using the web api doesn't work for these undocumented endpoints then, right?

[jamescridland]

I'm successfully querying this undocumented endpoint using a token from the standard web API. It works just fine (though searching for a podcast called "The Daily" is rather more painful than it needs be).

[drjackson9999]

Yeah, I'm able to use the search, and also the currently-playing end point as entry points into a specific podcast (though the object structure is very different between "tracks" and "episodes") using the normal bearer token. I've then been able to get information on the "show" and the "episode" using hrefs returned in the json by these initial end points.

Samples that worked for me, using just a simple get at these two urls, using the normal bearer token:

https://api.spotify.com/v1/shows/2SuODPath8vx2W3JNHluKA
https://api.spotify.com/v1/episodes/2lqNevhLx08QPmvCLjhS4g

Things that haven't worked for me that I'd like to have working in an ideal world:
recently played (works of course, but podcasts aren't includedin the result set)
add to queue (gives me an invalid uri error)
add to playlist (invalid uri error again, not all that surprising given you can't add a podcast to a playlist in any spotify player)
add to library (same as playlist, so not all that surprising)

I just want to listen to Spotify podcasts offline on my new Samsung Galaxy Watch! It's driving me nuts that I can't. I was hoping the APIs would give me a workaround but I've had no luck so far.

[drjackson9999]

As a quick additional note, you can search using a type of "episode" to find specific podcasts, in addition to type=show

Simple example:

https://api.spotify.com/v1/search?q=dan%20carlin&type=episode

vs

https://api.spotify.com/v1/search?q=dan%20carlin&type=show

or with both:

https://api.spotify.com/v1/search?q=dan%20carlin&type=episode,show

[jscholes]

add to queue (gives me an invalid uri error)

Using which endpoint?

[drjackson9999]

Add to queue probably isn't the right term, sorry. Play now would be better. I'm using this one:

https://api.spotify.com/v1/player/play

Documented here:

https://developer.spotify.com/documentation/web-api/reference/player/start-a-users-playback/

[esl-douglas]

I can't find followed podcasts in any of the endpoints available.

[esl-douglas]

Nevermind, just found.

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

[ngirot]

You have two endpoints :
GET https://api.spotify.com/v1/me/shows
GET https://api.spotify.com/v1/me/shows/{showId}

But there is some missing information with the second ; like "resume_point" for each podcast entries. If i use a token generated thought the web client, everything is fine, but not a token generated with Oauth (Authorization Code) with all scopes available.

Do someone knows if there is a way to get this data ?

[jscholes]

These undocumented endpoints were created for use with Spotify's own Web Player, not for use in third party projects. That's why a regular token, as issued to a user of a third party application, is not sufficient to access them.

[tommienu]

+1

[klayveR]

+1

I assume there's still no way to use episode uris with the https://api.spotify.com/v1/me/player/play endpoint?

[tonyravioli]

+1

[JMdoubleU]

+1

[ragnorc]

+1

[kylepw]

+1

[mikenye]

Furthermore, it would be extremely helpful if we could access podcast statistics (ie: subscriber count, starts, streams, etc) via API, so that we can pull statistics from different podcast platforms together to get a holistic view of one's statistics across all podcast platforms.

[itsme112358]

Apparently the endpoint exists as @jamescridland mentioned, it would be nice if it was documented though.
First I tried to handle podcasts like artists, then playlists before I found this post.
It would still be nice to get a documentation. All I want is to get the total number of episodes released. I got that, but it seems like a bit overkill. Since the limit parameter seems to be ignored, I always get 50 entries. Also I can't filter by fields. This means, I get a ~200KB result, just for one int, that's not very efficient :D

[pauljl1]

Undocumented Spotify Podcasts API

:market represents a Spotify recognised ISO country code.

Show endpoints

:show_id represents a Spotify ID, e.g. '0SUThziJbWNcuVmlmlsvva'

Find single, by ID - shows

https://api.spotify.com/v1/shows/:show_id?market=:market

Example: https://api.spotify.com/v1/shows/0SUThziJbWNcuVmlmlsvva?market=:market

Find multiple, by ID - shows

https://api.spotify.com/v1/shows?ids=:show_id,:show_id&market=:market

Example: https://api.spotify.com/v1/shows?ids=0SUThziJbWNcuVmlmlsvva,3Cct7ZWmxHNAtLgBTqjC5v&market=:market

Retrieving episodes for a show with limits and offset

This doesn't seem to work at the moment.

https://api.spotify.com/v1/shows/:show_id?limit=1&offset=1&market=:market

Example: https://api.spotify.com/v1/shows/0SUThziJbWNcuVmlmlsvva?limit=1&offset=1&market=:market

Search - shows

Find a single show by keywords, following Search API.

:query represents a search query, e.g. 'The Horne Section Podcast'

https://api.spotify.com/v1/search?q=:query&type=show&market=:market

Example: https://api.spotify.com/v1/search?q=horne+section&type=show&market=:market

Note: market is not optional when searching for shows, limit and offset still work as normal.

Expected JSON

If you find one ID, you will be given the episodes. If you're searching for multiple, episodes will be omitted.

• available_markets - array (string)
• copyrights - array (string)
• description - string
• episodes - hash (see episodes)
• explicit - boolean
• external_urls - hash
• href - string
• id - string
• images - array (hash)
• is_externally_hosted - boolean
• languages - array
• media_type - string
• name - string
• publisher - string
• type - string
• uri - string

Episode end points

:episode_id represents a Spotify ID, e.g. '6GO8UvfFR1kQmnNdmdffFG'

Find single, by ID - episodes

https://api.spotify.com/v1/shows/:show_id&market=:market

Example: https://api.spotify.com/v1/episodes/6GO8UvfFR1kQmnNdmdffFG&market=:market

Find multiple, by ID - episodes

https://api.spotify.com/v1/shows?ids=:show_id,:show_id&market=:market

Example: https://api.spotify.com/v1/episodes?ids=6GO8UvfFR1kQmnNdmdffFG,5LJ8pq2x1A7DzBCPJvz7pY&market=:market

Search - episodes

Find a single episode by keywords, following Search API.

:query represents a search query, e.g. 'The Horne Section Podcast'

https://api.spotify.com/v1/search?q=:query&type=episode&market=:market

Example: https://api.spotify.com/v1/search?q=horne+section+al+murry&type=show&market=:market

Note: market is not optional when searching for episodes, limit and offset still work as normal.

Expected JSON

If you find one ID, you will be given the show. If you're using the show for the episodes, show will not be included in the JSON for episodes.

• audio_preview_url - string
• description - string
• duration_ms - integer
• explicit - boolean
• external_urls - hash
• href - string
• id - string
• images - array (hash)
• is_externally_hosted - boolean
• is_playable - boolean
• language - string
• languages - array
• name - string
• release_date - string
• release_date_precision - string
• show - hash (see show, only outputted if using episode API endpoints)
• type - string
• uri - string

Playlist tracks

It's also apparent that the Get a Playlist's Tracks endpoint offers 'type' filtering as an optional query parameter.

For example:

Find playlist tracks

This is the default expected request.

https://api.spotify.com/v1/playlists/:playlist_id/tracks

Find playlist tracks and episodes

This request filers tracks and episodes differently, showing episodes with their correct API endpoint data-type as per the JSON expected above.

https://api.spotify.com/v1/playlists/:playlist_id/tracks?type=episode,track

In short: episodes are listed with thier accompanying show within the response. If you use track, you will still receive episodes, except they are formatted like a track (i.e. album, artist instead of show).

Likewise, if you use 'type' of just 'episode' you will still receive tracks and they will be formatted as they are currently without this filter.

Removing episodes from a playlist

If you have added episodes to a playlist, you can programmatically remove them using their position in the playlist. Send a DELETE request to:

https://api.spotify.com/v1/playlists/:playlist_id/tracks

The payload should be an array of positions, e.g.

{ "positions": [0, 1] }

Note: you must send the snapshot_id along with the request to use this.

This example will remove the first and second track (read: episode) from the playlist.

As of 29-02-2020, you can also pass episode URIs as per the remove tracks endpoint documentation.

The payload should be array of URIs, e.g.

{
  "tracks": [
    { "uri": "spotify:episode:6GO8UvfFR1kQmnNdmdffFG" }
  ]
}

Add episodes to a playlist

You can add episodes to a playlist by passing an episode URI.

This works the same as adding tracks to a playlist with the difference being that you use an episode URI.

For example, send a GET request to:

https://api.spotify.com/v1/playlists/:playlist_id/tracks

Use the query parameter of uri, e.g.

spotify:episode:6GO8UvfFR1kQmnNdmdffFG

Your GET request should look like:

https://api.spotify.com/v1/playlists/:playlist_id/tracks?uris=spotify:episode:6GO8UvfFR1kQmnNdmdffFG

Alternatively, send a POST request to:

https://api.spotify.com/v1/playlists/:playlist_id/tracks

Use a payload of URIs, e.g.

{"uris": ["spotify:episode:6GO8UvfFR1kQmnNdmdffFG"]}

You can mix tracks and episodes in both POST and GET requests too.

Reordering tracks in a playlist

It is possible to reorder tracks using the API, however, episodes that were once added and are no longer available are output as an empty item.

In other words, the 'track' hash of the 'items' array is missing for episodes that are no longer available; the 'added_at', 'added_by', 'is_local' still appear.

Caveats

I've been doing some experimental work with this API and have found the following:

• it's not yet possible to add episodes or remove episodes to a playlist using the API

---

Revision history

• 2020-02-14: Add 'Playlist tracks' section
• 2020-02-15: Add 'Removing episodes from a playlist' section
• 2020-02-29: Add 'Add episodes to a playlist' section, update 'removing episodes from a playlist' section to support episode URIs

[tudi2d]

Official endpoints: Search, browse and follow podcasts using the new Podcast APIs

Web API Reference:

• Episodes
• Shows

[shafiemukhre]

I am trying do stream the audio track from the spotify endpoint, is this possible? One of the use cases that I am thinking is to do analysis with this audio track