Podcastindex-org / docs-api

Developer documentation for the podcastindex.org api.
https://podcastindex-org.github.io/docs-api/
MIT License
52 stars 29 forks source link

Feature request: trailers API endpoint #115

Open jamescridland opened 6 months ago

jamescridland commented 6 months ago

Trailers

Trailers are super helpful for new listeners to discover a show. Both Apple Podcasts and Spotify are highlighting trailers at the top of the UX. Podnews uses trailers extensively where they exist. They are a good thing, and Apple and Spotify wouldn't have implemented it if the research didn't show it wasn't welcomed by listeners.

The problem

In order to find a trailer for a show, a client needs to request the full episode list of a podcast, and integrate through the episode list, requesting more episodes where necessary, and then to find the correct trailer.

This adds complication, makes it slow to get a trailer episode, and requires a client to download metadata for all the episodes. It represents significant additional bandwidth and calls to the API.

The solution

https://api.podcastindex.org/api/1.0/trailers/bypodcastguid?guid=9b024349-ccf0-5f69-a609-6b82873eab3c

This would return episode details (like the /episodes/ endpoint) for one selected trailer (or for none, where no trailer exists).

Apple Podcasts selects a trailer as follows, and I believe it's the right mechanism for us to copy:

Podnews would use this endpoint as soon as it's available, and it would be a real help if it could be implemented.