@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Listen API: Podcast Search, Directory, and Insights API
@base https://listen-api.listennotes.com/api/v2
@version 2.0
@auth ApiKey X-ListenAPI-Key in header
@common_fields {X-ListenAPI-Key: str # Get API Key on listennotes.com/api}
@endpoints 26
@hint download_for_search
@toc search(1), typeahead(1), search_episode_titles(1), trending_searches(1), related_searches(1), spellcheck(1), best_podcasts(1), podcasts(8), episodes(3), curated_podcasts(2), genres(1), regions(1), languages(1), just_listen(1), playlists(2)

@group search
@endpoint GET /search
@desc Full-text search
@required {q: str # Search term, e.g., person, place, topic... You can use double quotes to do verbatim match, e.g., "game of thrones". Otherwise, it's fuzzy search.}
@optional {sort_by_date: int(0/1)=0 # Sort by date or not? If 0, then sort by relevance. If 1, then sort by date., type: str(episode/podcast/curated)=episode # What type of contents do you want to search for?, offset: int=0 # Offset for search results, for pagination. You'll use **next_offset** from response for this parameter., len_min: int=0 # Minimum audio length in minutes. Applicable only when **type** parameter is **episode** or **podcast**. If **type** parameter is **episode**, it's for audio length of an episode. If **type** parameter is **podcast**, it's for average audio length of all episodes in a podcast., len_max: int # Maximum audio length in minutes. Applicable only when **type** parameter is **episode** or **podcast**. If **type** parameter is **episode**, it's for audio length of an episode. If **type** parameter is **podcast**, it's for average audio length of all episodes in a podcast., episode_count_min: int # Minimum number of episodes. Applicable only when type parameter is **podcast**., episode_count_max: int # Maximum number of episodes. Applicable only when type parameter is **podcast**., update_freq_min: int # Minimum update frequency in hours (how frequently does a podcast release a new episode). For example, if you want to find "weekly" podcasts, then you can set **update_freq_min**=144 hours (or 6 days) and **update_freq_max**=192 hours (or 8 days). Applicable only when type parameter is **podcast**., update_freq_max: int # Maximum update frequency in hours (how frequently does a podcast release a new episode). For example, if you want to find "weekly" podcasts, then you can set **update_freq_min**=144 hours (or 6 days) and **update_freq_max**=192 hours (or 8 days). Applicable only when type parameter is **podcast**., genre_ids: str # A comma-delimited string of a list of genre ids. If not specified, then all genres are included. You can find the id and the name of all genres from `GET /genres`. It works only when **type** is *episode* or *podcast*., published_before: int # Only show episodes/podcasts/curated lists published before this Epoch Unix timestamp (in milliseconds).  If **published_before** & **published_after** are used at the same time, **published_before** should be bigger than **published_after**., published_after: int=0 # Only show episodes/podcasts/curated lists published after this Epoch Unix timestamp (in milliseconds).  If **published_before** & **published_after** are used at the same time, **published_before** should be bigger than **published_after**., only_in: str=title,description,author,audio # A comma-delimited string to search only in specific fields. Allowed values are title, description, author, and audio. If not specified, then search every fields., language: str # Limit search results to a specific language. If not specified, it'll be any language. You can get a list of supported languages from `GET /languages`. It works only when **type** is *episode* or *podcast*., region: str # Limit search results to a specific region (e.g., us, gb, in...). If not specified, it'll be any region. You can get the supported country codes from `GET /regions`. It works only when **type** is *episode* or *podcast*., ocid: str # A comma-delimited string of podcast ids (up to 5 podcasts) - you can get a podcast id from the **podcast_id** field in response. This parameter is to limit search results from only a few specific podcasts. It works only when **type** is *episode*., ncid: str # A comma-delimited string of podcast ids (up to 5 podcasts) - you can get a podcast id from the **podcast_id** field in response. This parameter is to exclude search results of a few specific podcasts. It works only when **type** is *episode*., safe_mode: int(0/1)=0 # Whether or not to exclude podcasts/episodes with explicit language. 1 is yes and 0 is no. It works only when **type** is *episode* or *podcast*., unique_podcasts: int(0/1)=0 # Whether or not to keep only one episode per podcast in search results. 1 is yes and 0 is no. It works only when **type** is *episode*., interviews_only: int(0/1)=0 # Whether or not to keep only podcasts that have guest interviews in search results. 1 is yes and 0 is no. It works only when **type** is *podcast*.  This parameter is available only in the PRO/ENTERPRISE plan., sponsored_only: int(0/1)=0 # Whether or not to keep only podcasts that have sponsors in search results. 1 is yes and 0 is no. It works only when **type** is *podcast*. This parameter is available only in the PRO/ENTERPRISE plan., page_size: int=10 # The maximum number of search results per page. A valid value should be an integer between 1 and 10 (inclusive).}
@returns(200) {next_offset: int, took: num, total: int, count: int, results: [any]} # OK
@errors {400: Something wrong on your end (Client side errors), e.g., missing required parameters., 401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group typeahead
@endpoint GET /typeahead
@desc Typeahead search
@required {q: str # Search term, e.g., person, place, topic... You can use double quotes to do verbatim match, e.g., "game of thrones". Otherwise, it's fuzzy search.}
@optional {show_podcasts: int(0/1)=0 # Autosuggest podcasts. This only searches podcast title and publisher and returns very limited info of 5 podcasts. 1 is yes, 0 is no. It's a bit slow to autosuggest podcasts, so we turn it off by default. If show_podcasts=1, you can also pass iTunes id (e.g., 474722933) to the q parameter to fetch podcast meta data., show_genres: int(0/1)=0 # Whether or not to autosuggest genres. 1 is yes, 0 is no., safe_mode: int(0/1)=0 # Whether or not to exclude podcasts/episodes with explicit language. 1 is yes and 0 is no. It works only when **show_podcasts** is *1*.}
@returns(200) {terms: [str], genres: [map], podcasts: [map]} # OK
@errors {400: Something wrong on your end (Client side errors), e.g., missing required parameters., 401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group search_episode_titles
@endpoint GET /search_episode_titles
@desc Find individual episodes by searching for their titles
@required {q: str # An episode's title, e.g., Jerusalem Demsas on The Dispossessed. You can use double quotes to do verbatim match, e.g., "Jerusalem Demsas on The Dispossessed". Otherwise, it's fuzzy search.}
@optional {podcast_id: str # Refine search results by specifying a podcast through its unique ID. The format of the podcast ID is governed by the podcast_id_type parameter.  For listennotes_id, the podcast ID will look like 'cda18f20f1be4ac7b3cce7d0eb168fff'.  For itunes_id, it will be a numerical value like '983795625'.  For spotify_id, expect a format like '0Z1234tGXD2hVhjFrrhJ7g'.  For rss, the podcast ID will be the RSS URL, e.g., 'https://cowenconvos.libsyn.com/rss'., podcast_id_type: str(listennotes_id/itunes_id/spotify_id/rss)=listennotes_id # The type of podcast id. Valid values are **listennotes_id**, **itunes_id**, **spotify_id**, and **rss**. Note: **itunes_id** is for Apple Podcasts.}
@returns(200) {next_offset: int, took: num, total: int, count: int, results: [map]} # OK
@errors {400: Something wrong on your end (Client side errors), e.g., missing required parameters., 401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group trending_searches
@endpoint GET /trending_searches
@desc Fetch trending search terms
@returns(200) {terms: [str]} # OK
@errors {400: Something wrong on your end (Client side errors), e.g., missing required parameters., 401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group related_searches
@endpoint GET /related_searches
@desc Fetch related search terms
@required {q: str # Search term, e.g., person, place, topic...}
@returns(200) {terms: [str]} # OK
@errors {400: Something wrong on your end (Client side errors), e.g., missing required parameters., 401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group spellcheck
@endpoint GET /spellcheck
@desc Spell check on a search term
@required {q: str # Search term, e.g., person, place, topic...}
@returns(200) {tokens: [map], corrected_text_html: str} # OK
@errors {400: Something wrong on your end (Client side errors), e.g., missing required parameters., 401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group best_podcasts
@endpoint GET /best_podcasts
@desc Fetch a list of best podcasts by genre
@optional {genre_id: str # You can get the id from `GET /genres`. If not specified, it'll be the overall best podcasts, which can be considered as a special genre., page: int # Page number of those podcasts in this genre., region: str=us # Filter best podcasts by country/region. Please note that podcasts that are "best" in a country/region may not be produced in that country/region. For example, a podcast from the US may be very popular in Canada. You can get the supported country codes (e.g., us, jp, gb...) from `GET /regions`. If not specified, you'll get "best podcasts" in United States., publisher_region: str # Filter best podcasts by the publisher's country/region. This is to narrow down the results to include "best podcasts" produced in a specific country/region. You can get the supported country codes (e.g., us, jp, gb...) from `GET /regions`. If not specified, you'll get "best podcasts" produced in any country/region. If you want to get a country/region's "best podcasts" that are also produced in that country/region, then you need to specify both **region** and **publisher_region**, e.g., `region=jp` and `publisher_region=jp`., language: str # Filter best podcasts by language. You can get a list of supported languages (e.g., English, Chinese, Japanese...) from `GET /languages`. If not specified, you'll get "best podcasts" in any language., sort: str(recent_added_first/oldest_added_first/recent_published_first/oldest_published_first/listen_score)=recent_added_first # How do you want to sort these podcasts? If you'd like to sort by popularity, please use **listen_score**., safe_mode: int(0/1)=0 # Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.}
@returns(200) {has_previous: bool, name: str, listennotes_url: str, previous_page_number: int, page_number: int, has_next: bool, next_page_number: int, parent_id: int, id: int, total: int, podcasts: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group podcasts
@endpoint GET /podcasts/{id}
@desc Fetch detailed meta data and episodes for a podcast by id
@required {id: str # Podcast id. You can get podcast id from using other endpoints, e.g., `GET /search`, `GET /best_podcasts`...}
@optional {next_episode_pub_date: int # For episodes pagination. It's the value of **next_episode_pub_date** from the response of last request. If not specified, just return latest 10 episodes or oldest 10 episodes, depending on the value of the **sort** parameter. It is an Epoch Unix timestamp in milliseconds. During pagination with **next_episode_pub_date**, an empty **episodes** array in the response signals that no more episodes are available., sort: str(recent_first/oldest_first)=recent_first # How do you want to sort the episodes of this podcast?}
@returns(200) {episodes: [map], is_claimed: bool, type: str, explicit_content: bool, website: str, total_episodes: int, audio_length_sec: int, update_frequency_hours: int, earliest_pub_date_ms: int, rss: str, latest_episode_id: str, latest_pub_date_ms: int, title: str, language: str, description: str, email: str, image: str, thumbnail: str, listennotes_url: str, id: str, country: str, publisher: str, itunes_id: int, looking_for: map{cohosts: bool, cross_promotion: bool, sponsors: bool, guests: bool}, extra: map{youtube_url: str, facebook_handle: str, instagram_handle: str, twitter_handle: str, wechat_handle: str, patreon_handle: str, amazon_music_url: str, linkedin_url: str, spotify_url: str, url1: str, url2: str, url3: str}, genre_ids: [int], next_episode_pub_date: int, listen_score: int, listen_score_global_rank: str, has_guest_interviews: bool, has_sponsors: bool} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endpoint DELETE /podcasts/{id}
@desc Request to delete a podcast
@required {id: str # Podcast id. You can get podcast id from using other endpoints, e.g., `GET /search`, `GET /best_podcasts`...}
@optional {reason: str # The reason why this podcast should be deleted, e.g., copyright violation, the podcaster wants to delete it... You can put "testing" here to indicate that you are testing this endpoint, so we will not actually delete the podcast.}
@returns(200) {status: str} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group episodes
@endpoint GET /episodes/{id}
@desc Fetch detailed meta data for an episode by id
@required {id: str # id for a specific episode. You can get episode id from using other endpoints, e.g., `GET /search`...}
@optional {show_transcript: int=0 # To include the transcript of this episode or not? If it is 1, then include the transcript in the **transcript** field. The default value is 0 - we don't include transcript by default, because 1) it would make the response data very big, thus slow response time; 2) less than 1% of episodes have transcripts. The transcript field is available only in the PRO/ENTERPRISE plan.}
@returns(200) {maybe_audio_invalid: bool, pub_date_ms: int, audio: str, listennotes_edit_url: str, image: str, thumbnail: str, description: str, title: str, explicit_content: bool, listennotes_url: str, audio_length_sec: int, id: str, podcast: map{is_claimed: bool, type: str, explicit_content: bool, website: str, total_episodes: int, audio_length_sec: int, update_frequency_hours: int, earliest_pub_date_ms: int, rss: str, latest_episode_id: str, latest_pub_date_ms: int, title: str, language: str, description: str, email: str, image: str, thumbnail: str, listennotes_url: str, id: str, country: str, publisher: str, itunes_id: int, looking_for: map{cohosts: bool, cross_promotion: bool, sponsors: bool, guests: bool}, extra: map{youtube_url: str, facebook_handle: str, instagram_handle: str, twitter_handle: str, wechat_handle: str, patreon_handle: str, amazon_music_url: str, linkedin_url: str, spotify_url: str, url1: str, url2: str, url3: str}, genre_ids: [int], listen_score: int, listen_score_global_rank: str, has_guest_interviews: bool, has_sponsors: bool}, link: str, transcript: str} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endpoint POST /episodes
@desc Batch fetch basic meta data for episodes
@returns(200) {episodes: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group podcasts
@endpoint POST /podcasts
@desc Batch fetch basic meta data for podcasts
@returns(200) {podcasts: [map], latest_episodes: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group curated_podcasts
@endpoint GET /curated_podcasts/{id}
@desc Fetch a curated list of podcasts by id
@required {id: str # id for a specific curated list of podcasts. You can get the id from the response of `GET /search?type=curated` or `GET /curated_podcasts`.}
@returns(200) {id: str, description: str, source_url: str, source_domain: str, pub_date_ms: int, listennotes_url: str, title: str, total: int, podcasts: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group genres
@endpoint GET /genres
@desc Fetch a list of podcast genres
@optional {top_level_only: int(0/1)=0 # Just show top level genres? If 1, yes, just show top level genres. If 0, no, show all genres.}
@returns(200) {genres: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group regions
@endpoint GET /regions
@desc Fetch a list of supported countries/regions for best podcasts
@returns(200) {regions: map} # OK
@errors {401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group languages
@endpoint GET /languages
@desc Fetch a list of supported languages for podcasts
@returns(200) {languages: [str]} # OK
@errors {401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group just_listen
@endpoint GET /just_listen
@desc Fetch a random podcast episode
@returns(200) {maybe_audio_invalid: bool, pub_date_ms: int, audio: str, listennotes_edit_url: str, image: str, thumbnail: str, description: str, title: str, explicit_content: bool, listennotes_url: str, audio_length_sec: int, id: str, link: str, podcast: map{image: str, thumbnail: str, title: str, listennotes_url: str, id: str, publisher: str, listen_score: int, listen_score_global_rank: str}} # OK
@errors {401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group curated_podcasts
@endpoint GET /curated_podcasts
@desc Fetch curated lists of podcasts
@optional {page: int=1 # Page number of curated lists.}
@returns(200) {has_previous: bool, previous_page_number: int, page_number: int, next_page_number: int, has_next: bool, total: int, curated_lists: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group podcasts
@endpoint GET /podcasts/{id}/recommendations
@desc Fetch recommendations for a podcast
@required {id: str # Podcast id.}
@optional {safe_mode: int(0/1)=0 # Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.}
@returns(200) {recommendations: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group episodes
@endpoint GET /episodes/{id}/recommendations
@desc Fetch recommendations for an episode
@required {id: str # Episode id.}
@optional {safe_mode: int(0/1)=0 # Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.}
@returns(200) {recommendations: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group podcasts
@endpoint POST /podcasts/submit
@desc Submit a podcast to Listen Notes database
@returns(200) {status: str, podcast: map{image: str, thumbnail: str, title: str, listennotes_url: str, id: str, publisher: str, listen_score: int, listen_score_global_rank: str}} # OK
@errors {400: Something wrong on your end (Client side errors), e.g., missing required parameters., 401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endpoint POST /podcasts/{id}/rss
@desc Refresh RSS feed of a podcast
@required {id: str # Podcast id. You can get podcast id from using other endpoints, e.g., `GET /search`, `GET /best_podcasts`...}
@returns(200) {status: str, last_refreshed_at_ms: int} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group playlists
@endpoint GET /playlists/{id}
@desc Fetch a playlist's info and items (i.e., episodes or podcasts).
@required {id: str # Playlist id (always 11 characters, e.g., m1pe7z60bsw). You can get the podcast id from the url of a playlist, e.g., m1pe7z60bsw is the playlist id of listennotes.com/listen/podcasts-about-podcasting-m1pe7z60bsw}
@optional {type: str(episode_list/podcast_list)=episode_list # The type of this playlist, which should be either **episode_list** or **podcast_list**., last_timestamp_ms: int=0 # For playlist items pagination. It's the value of **last_timestamp_ms** from the response of last request. If it's 0 or not specified, just return the latest or the oldest 20 items, depending on the value of the **sort** parameter. It is an Epoch Unix timestamp in milliseconds., sort: str(recent_added_first/oldest_added_first/recent_published_first/oldest_published_first)=recent_added_first # How do you want to sort playlist items?}
@returns(200) {id: str, name: str, description: str, image: str, thumbnail: str, listennotes_url: str, visibility: str, last_timestamp_ms: int, total: int, total_audio_length_sec: int, type: str, items: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endpoint GET /playlists
@desc Fetch a list of your playlists.
@optional {sort: str(recent_added_first/oldest_added_first/name_a_to_z/name_z_to_a)=recent_added_first # How do you want to sort playlists?, page: int=1 # Page number of playlists.}
@returns(200) {previous_page_number: int, page_number: int, has_next: bool, has_previous: bool, next_page_number: int, total: int, playlists: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@group podcasts
@endpoint GET /podcasts/{id}/audience
@desc Fetch audience demographics for a podcast
@required {id: str # Podcast id.}
@returns(200) {by_regions: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endpoint GET /podcasts/domains/{domain_name}
@desc Fetch podcasts by a publisher's domain name
@required {domain_name: str # A publisher's domain name, e.g., nytimes.com, wondery.com, npr.org...}
@optional {page: int=1 # Page number of the podcasts from this domain name}
@returns(200) {page_number: int, has_next: bool, next_page_number: int, has_previous: bool, previous_page_number: int, podcasts: [map]} # OK
@errors {401: Wrong api key, or your account is suspended., 404: Endpoint not exist, or podcast / episode not exist., 429: For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit., 5XX: Something wrong on our end (Unexpected server errors).}

@endgroup

@end