Apple Podcasts, fyyd, gpodder.net and the Podcast Index behind one shape. You can search them, look shows up, read their charts and list episodes, and every answer is keyed like a parsed feed.
A request is a map that any HTTP client can send, and a response reads into shows, which are maps with the keys of a parsed feed where the directory has the same information:
Apple, fyyd and gpodder.net need no credentials, and the Podcast Index takes its under the :credentials option.
Apple Podcasts, fyyd, gpodder.net and the Podcast Index behind one shape. You can search them, look shows up, read their charts and list episodes, and every answer is keyed like a parsed feed. A request is a map that any HTTP client can send, and a response reads into shows, which are maps with the keys of a parsed feed where the directory has the same information: - :rss/title, :itunes/author and :itunes/image - the URL of the feed as the :atom/links entry with rel self - :podcast/guid when the directory knows the one that the feed declares. A guid derived from the URL would be a guess, since a feed that moved keeps the guid of its first URL. - keys in the directory namespace for what only the directory knows, such as :directory/source, :directory/id and the record itself as :directory/raw Apple, fyyd and gpodder.net need no credentials, and the Podcast Index takes its under the :credentials option.
The ids of the genres of Apple Podcasts by name, as the genre service of Apple gave them on 29 September 2026. The names are the categories of itunes:category, of both levels.
The entry of Apple in sources holds them as :genres, so you can give another table in an entry of your own.
The ids of the genres of Apple Podcasts by name, as the genre service of Apple gave them on 29 September 2026. The names are the categories of itunes:category, of both levels. The entry of Apple in sources holds them as :genres, so you can give another table in an entry of your own.
(call! source call params)(call! source
call
{:keys [limit] :as params}
{:keys [send] :or {send client/send!} :as opts})Send call with params and opts to source, and read the shows or
the episodes in the answer, in ClojureScript in a promise.
The opts are those of request, and these:
A 404 gives none. Any other status that isn't a success throws with the
:type ::failed, so a refused key doesn't look like an empty answer.
There are at most the :limit of params, since gpodder.net takes no
limit.
Send `call` with `params` and `opts` to `source`, and read the shows or the episodes in the answer, in ClojureScript in a promise. The `opts` are those of request, and these: - :send, the function that sends the request, client/send! by default - :timeout-seconds, the time to wait for an answer. It's 15 by default, so a directory that doesn't answer costs little. - :user-agent, as http/send! takes it A 404 gives none. Any other status that isn't a success throws with the :type ::failed, so a refused key doesn't look like an empty answer. There are at most the :limit of `params`, since gpodder.net takes no limit.
The calls of the sources, with their parameters. Every source answers the first three with shows:
The others give episodes, and the :calls of an entry of sources say which it answers. A source throws for one that it doesn't answer.
The :trending call also takes :category, for the chart of one category. It's a name of the categories of Apple Podcasts, such as Technology or Society & Culture. A map gives each source a category of its own, by the id of the source. Each source reads the category in its own way:
The calls of the sources, with their parameters. Every source answers the first three with shows: - :search takes :q and :limit, with :country for Apple - :lookup takes the :id of the show at the source, which for gpodder.net is the feed URL and for Apple can be several ids at once. The Podcast Index also takes the :url of the feed in its place, and a podcast:guid as the :id. - :trending takes :limit, with :country for Apple and :language for fyyd and the Podcast Index. A source that can take neither of those that are given throws, since its chart would be of the wrong shows. The others give episodes, and the :calls of an entry of sources say which it answers. A source throws for one that it doesn't answer. - :episodes takes the :id of the show, or the :url of its feed at the Podcast Index, and :limit, for its newest episodes - :by-person takes :q, a name, and :limit, for the episodes that name the person as a podcast:person or in their text - :recent takes :limit, for the newest episodes of any show - :live takes :limit, for the live items that are on air The :trending call also takes :category, for the chart of one category. It's a name of the categories of Apple Podcasts, such as Technology or Society & Culture. A map gives each source a category of its own, by the id of the source. Each source reads the category in its own way: - Apple takes a name or an id of the :genres of its entry. - The Podcast Index takes a name or an id of its categories, or several. It has the top categories of Apple, and words of its own for the rest. - The category is a tag of gpodder.net, in lower case. - The chart of fyyd has no categories, so asking for one throws.
(category-names body)(category-names body {:keys [source] :or {source :apple} :as opts})The localised names of the categories of Apple Podcasts in body, the
JSON that the genre service answered, with opts. It's a map from the
English name that itunes:category uses to the localised one, e.g.
{"Society & Culture" "Samfund og kultur"}.
The English names are the :genres of Apple's entry in sources, or of the
:source of opts. A category missing from either is left out, so show
its English name instead.
The localised names of the categories of Apple Podcasts in `body`, the
JSON that the genre service answered, with `opts`. It's a map from the
English name that itunes:category uses to the localised one, e.g.
{"Society & Culture" "Samfund og kultur"}.
The English names are the :genres of Apple's entry in sources, or of the
:source of `opts`. A category missing from either is left out, so show
its English name instead.(category-names-request country language)(category-names-request country
language
{:keys [source] :or {source :apple} :as opts})The request to Apple's genre service for the names of the categories of
Apple Podcasts in language, as the store of country has them, with
opts. Both are two letters, e.g. "da" and "dk".
The service is at the :genre-names of Apple's entry in sources, or of
the :source of opts. Apple doesn't document it.
The request to Apple's genre service for the names of the categories of Apple Podcasts in `language`, as the store of `country` has them, with `opts`. Both are two letters, e.g. "da" and "dk". The service is at the :genre-names of Apple's entry in sources, or of the :source of `opts`. Apple doesn't document it.
(combine results)One entry per show across results from several sources, in the order
they were first found.
An entry is the record of the first source, with the fields it lacked filled from the later ones. Its :directory/sources names every source that had the show, by its id there. A chart entry names no feed. It gains one when it meets its lookup by the id they share, or the same show from elsewhere by its title and author.
One entry per show across `results` from several sources, in the order they were first found. An entry is the record of the first source, with the fields it lacked filled from the later ones. Its :directory/sources names every source that had the show, by its id there. A chart entry names no feed. It gains one when it meets its lookup by the id they share, or the same show from elsewhere by its title and author.
(fetch-category-names! country language)(fetch-category-names!
country
language
{:keys [send source] :or {send client/send! source :apple} :as opts})Fetch the localised names of the categories of Apple Podcasts in
language, as the store of country has them, with opts. It returns
a map with the :names that category-names returns, in ClojureScript as a
promise. Keep the names, since they rarely change.
The opts are those of category-names-request and call!. Nothing that
the network or Apple does throws. When the names don't arrive, the
result has the diagnostic :directory/source-failed under :error.
Fetch the localised names of the categories of Apple Podcasts in `language`, as the store of `country` has them, with `opts`. It returns a map with the :names that category-names returns, in ClojureScript as a promise. Keep the names, since they rarely change. The `opts` are those of category-names-request and call!. Nothing that the network or Apple does throws. When the names don't arrive, the result has the diagnostic :directory/source-failed under :error.
(fetch-chart!)(fetch-chart! opts)Fetch the charts of the directories with opts, and combine them into
one entry for each show. The shows are in the order that the sources
list them.
The opts are those of search!, and these:
A source that has no chart of the category, the :country or the :language is in the :report, with the reason.
Fetch the charts of the directories with `opts`, and combine them into one entry for each show. The shows are in the order that the sources list them. The `opts` are those of search!, and these: - :language, the language of the shows in the charts of fyyd and the Podcast Index, e.g. "da" - :category, for the charts of one category, as calls tells A source that has no chart of the category, the :country or the :language is in the :report, with the reason.
(identify! feed url)(identify! feed url {:keys [credentials country] :as opts})Ask the directories for the ids of the show of feed at url, with
opts, as a map of the :ids by source, e.g. {:podcastindex 920666
:apple "1584274529"}, in ClojureScript as a promise.
The Podcast Index is asked when the opts have its :credentials, by the
podcast:guid of the feed or else by url, and its answer often has the
Apple id too. Otherwise Apple is asked by the title of the show, and its
answer counts only for a show at url, since shows share titles. A
source that fails is in the :report, and its id is left out. The opts
are those of call!, and :country for Apple.
Ask the directories for the ids of the show of `feed` at `url`, with
`opts`, as a map of the :ids by source, e.g. {:podcastindex 920666
:apple "1584274529"}, in ClojureScript as a promise.
The Podcast Index is asked when the `opts` have its :credentials, by the
podcast:guid of the feed or else by `url`, and its answer often has the
Apple id too. Otherwise Apple is asked by the title of the show, and its
answer counts only for a show at `url`, since shows share titles. A
source that fails is in the :report, and its id is left out. The `opts`
are those of call!, and :country for Apple.(request source call params)(request source call params {:keys [credentials] :as opts})The request map for call at source with params and opts, a
map of :method, :url and :headers. See calls for each call and
its parameters.
The source is a name in sources, or an entry of the shape of its
entries. The opts are for the Podcast Index:
The request map for `call` at `source` with `params` and `opts`, a map of :method, :url and :headers. See calls for each call and its parameters. The `source` is a name in sources, or an entry of the shape of its entries. The `opts` are for the Podcast Index: - :credentials, a map of :key and :secret - :auth-date, the time in Unix seconds that signs a request
(response source call body)The shows in the JSON body that source answered for call, or the
episodes for a call of episode-calls, as a vector. It throws only when
the body isn't JSON.
A lookup gives one show. The shows of trending are in the order of the
chart, each with its :directory/rank. The vector is empty when the body
tells of a failure. The source is a name in sources or an entry, and
each show names it as :directory/source.
An episode has the keys of a parsed item, its :directory/id and :directory/source, and the show that it's an episode of as :directory/show, as much as the source tells of the show.
The shows in the JSON `body` that `source` answered for `call`, or the episodes for a call of episode-calls, as a vector. It throws only when the body isn't JSON. A lookup gives one show. The shows of trending are in the order of the chart, each with its :directory/rank. The vector is empty when the body tells of a failure. The `source` is a name in sources or an entry, and each show names it as :directory/source. An episode has the keys of a parsed item, its :directory/id and :directory/source, and the show that it's an episode of as :directory/show, as much as the source tells of the show.
(search! q)(search! q opts)Search the directories for the shows that match the words q, with
opts. It gives a map of the :results and, when a source failed, the
:report, in ClojureScript in a promise.
The results have one entry for each show, and the shows that the most
sources have come first. The report has a :directory/source-failed
diagnostic for each source that failed, with its :source and the
:reason. The opts are these:
Search the directories for the shows that match the words `q`, with `opts`. It gives a map of the :results and, when a source failed, the :report, in ClojureScript in a promise. The results have one entry for each show, and the shows that the most sources have come first. The report has a :directory/source-failed diagnostic for each source that failed, with its :source and the :reason. The `opts` are these: - :sources, each a name in sources or an entry. By default, they're the sources without credentials, and the Podcast Index with :credentials. - :limit, the number of shows from each source - :country, the store of Apple, e.g. "dk" - :credentials, the :key and :secret of the Podcast Index - :timeout-seconds, the time to wait for each source - :send, the function that sends each request, client/send! by default
The directories that podcast-clj knows, by name. An entry has the :api that the directory speaks, its :name for a listener, whether it needs credentials, the :calls that it answers, and the URLs of the service.
A source is given by its name here, or as an entry of this shape. So you can reach another service with the same API:
(assoc (:fyyd sources)
:id :mirror :root "https://fyyd.example.org/0.2/")
The :id of such an entry names the source in the results. Without an :id, the name of its API does.
The directories that podcast-clj knows, by name. An entry has the :api
that the directory speaks, its :name for a listener, whether it needs
credentials, the :calls that it answers, and the URLs of the service.
A source is given by its name here, or as an entry of this shape. So
you can reach another service with the same API:
(assoc (:fyyd sources)
:id :mirror :root "https://fyyd.example.org/0.2/")
The :id of such an entry names the source in the results. Without an
:id, the name of its API does.cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |