openapi-directory/api/listennotes.com.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.1.0","servers":[{"description":"API Production Server","url":"https://listen-api.listennotes.com/api/v2"}],"info":{"contact":{"email":"hello@listennotes.com","name":"Listen Notes","url":"https://www.listennotes.com/api/","x-twitter":"listennotes"},"description":"Simple & no-nonsense podcast search & directory API. Search all podcasts and episodes by people, places, or topics.\n","termsOfService":"https://www.listennotes.com/api/terms/","title":"Listen API: Podcast Search, Directory, and Insights API","version":"2.0","x-apisguru-categories":["entertainment"],"x-logo":{"url":"https://twitter.com/listennotes/profile_image?size=original"},"x-origin":[{"converter":{"url":"https://github.com/mermade/oas-kit","version":"7.0.4"},"format":"openapi","url":"https://listen-api.listennotes.com/api/v2/openapi.yaml","version":"3.1"}],"x-providerName":"listennotes.com"},"tags":[{"description":"Endpoints to search podcasts","name":"Search API"},{"description":"Endpoints to fetch podcasts data","name":"Directory API"},{"description":"Endpoints to fetch Listen Later playlists data","name":"Playlist API"},{"description":"Endpoints to improve the podcast database","name":"Podcaster API"},{"description":"Endpoints to get insights of podcasts, e.g., audience demographics","name":"Insights API"}],"paths":{"/best_podcasts":{"get":{"description":"Get a list of curated best podcasts by genre,\nwhich are curated by Listen Notes staffs based on various signals from the Internet, e.g.,\ntop charts on other podcast platforms, recommendations from mainstream media,\nuser activities on listennotes.com...\nYou can get the genre ids from `GET /genres` endpoint.\nThis endpoint returns same data as https://www.listennotes.com/best-podcasts/\n","operationId":"getBestPodcasts","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"$ref":"#/components/parameters/genreIdParam"},{"description":"Page number of those podcasts in this genre.","in":"query","name":"page","required":false,"schema":{"examples":[2],"type":"integer"}},{"description":"Filter best podcasts by country/region.\nPlease note that podcasts that are \"best\" in a country/region may not be produced in that country/region.\nFor example, a podcast from the US may be very popular in Canada.\nYou can get the supported country codes (e.g., us, jp, gb...) from `GET /regions`.\nIf not specified, you'll get \"best podcasts\" in United States.\n","in":"query","name":"region","required":false,"schema":{"default":"us","examples":["us"],"type":"string"}},{"description":"Filter best podcasts by the publisher's country/region.\nThis is to narrow down the results to include \"best podcasts\" produced in a specific country/region.\nYou can get the supported country codes (e.g., us, jp, gb...) from `GET /regions`.\nIf not specified, you'll get \"best podcasts\" produced in any country/region.\nIf you want to get a country/region's \"best podcasts\" that are also produced in that country/region,\nthen you need to specify both **region** and **publisher_region**,\ne.g., `region=jp` and `publisher_region=jp`.\n","in":"query","name":"publisher_region","required":false,"schema":{"type":"string"}},{"description":"Filter best podcasts by language.\nYou can get a list of supported languages (e.g., English, Chinese, Japanese...) from `GET /languages`.\nIf not specified, you'll get \"best podcasts\" in any language.\n","in":"query","name":"language","required":false,"schema":{"type":"string"}},{"description":"How do you want to sort these podcasts?\nIf you'd like to sort by popularity, please use **listen_score**.\n","example":"listen_score","explode":true,"in":"query","name":"sort","required":false,"schema":{"default":"recent_added_first","enum":["recent_added_first","oldest_added_first","recent_published_first","oldest_published_first","listen_score"],"type":"string"},"style":"form"},{"$ref":"#/components/parameters/safeModeParam"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BestPodcastsResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}},"links":{"paginate":{"description":"Pagination through podcasts.","operationId":"getBestPodcasts","parameters":{"page":"$response.body#/next_page_number"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch a list of best podcasts by genre","tags":["Directory API"]}},"/curated_podcasts":{"get":{"description":"A bunch of curated lists from online media. For each list, you'll get basic info of up to 5 podcasts. To get detailed meta data of all podcasts in a specific list, you need to use `GET /curated_podcasts/{id}`. We add new curated lists to the database on a daily basis.\n","operationId":"getCuratedPodcasts","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Page number of curated lists.","example":2,"explode":true,"in":"query","name":"page","required":false,"schema":{"default":1,"type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetCuratedPodcastsResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}},"links":{"paginate":{"description":"Pagination through curated lists.","operationId":"getCuratedPodcasts","parameters":{"page":"$response.body#/next_page_number"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch curated lists of podcasts","tags":["Directory API"]}},"/curated_podcasts/{id}":{"get":{"description":"Get detailed meta data of all podcasts in a specific curated list.\nThis endpoint returns same data as https://www.listennotes.com/curated-podcasts/\n","operationId":"getCuratedPodcastById","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"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`.\n","explode":false,"in":"path","name":"id","required":true,"schema":{"examples":["SDFKduyJ47r"],"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CuratedListFull"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch a curated list of podcasts by id","tags":["Directory API"]}},"/episodes":{"post":{"description":"Batch fetch basic meta data for up to 10 episodes. This endpoint could be used to implement custom playlists for individual episodes. For detailed meta data of an individual episode, you need to use `GET /episodes/{id}`. This endpoint is available only in the PRO/ENTERPRISE plan.\n","operationId":"getEpisodesInBatch","parameters":[{"$ref":"#/components/parameters/apiKeyParam"}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/GetEpisodesInBatchForm"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetEpisodesInBatchResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Batch fetch basic meta data for episodes","tags":["Directory API"]}},"/episodes/{id}":{"get":{"description":"Fetch detailed meta data for a specific episode.","operationId":"getEpisodeById","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"id for a specific episode. You can get episode id from using other endpoints, e.g., `GET /search`...","explode":false,"in":"path","name":"id","required":true,"schema":{"examples":["6b6d65930c5a4f71b254465871fed370"],"type":"string"},"style":"simple"},{"description":"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.","explode":false,"in":"query","name":"show_transcript","required":false,"schema":{"default":0,"examples":[1],"type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeFull"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch detailed meta data for an episode by id","tags":["Directory API"]}},"/episodes/{id}/recommendations":{"get":{"description":"Fetch up to 8 episode recommendations based on the given episode id.","operationId":"getEpisodeRecommendations","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Episode id.","example":"254444fa6cf64a43a95292a70eb6869b","explode":false,"in":"path","name":"id","required":true,"schema":{"type":"string"},"style":"simple"},{"$ref":"#/components/parameters/safeModeParam"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetEpisodeRecommendationsResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch recommendations for an episode","tags":["Directory API"]}},"/genres":{"get":{"description":"Get a list of podcast genres that are supported in Listen Notes.\nThe genre id can be passed to other endpoints as a parameter to get podcasts in a specific genre,\ne.g., `GET /best_podcasts`, `GET /search`...\nYou may want to cache the list of genres on the client side.\n","operationId":"getGenres","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Just show top level genres? If 1, yes, just show top level genres. If 0, no, show all genres.\n","explode":true,"in":"query","name":"top_level_only","required":false,"schema":{"default":0,"enum":[0,1],"examples":[1],"type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetGenresResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch a list of podcast genres","tags":["Directory API"]}},"/just_listen":{"get":{"description":"Recently published episodes are more likely to be fetched. Good luck!","operationId":"justListen","parameters":[{"$ref":"#/components/parameters/apiKeyParam"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EpisodeSimple"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch a random podcast episode","tags":["Directory API"]}},"/languages":{"get":{"description":"Get a list of languages that are supported in Listen Notes database. You can use the language string as query parameter in `GET /search`.\n","operationId":"getLanguages","parameters":[{"$ref":"#/components/parameters/apiKeyParam"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetLanguagesResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch a list of supported languages for podcasts","tags":["Directory API"]}},"/playlists":{"get":{"description":"This endpoint returns same data as listennotes.com/listen under your account.\nYou can use the **page** parameter to do pagination and fetch more playlists.\n","operationId":"getPlaylists","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"How do you want to sort playlists?\n","in":"query","name":"sort","required":false,"schema":{"default":"recent_added_first","enum":["recent_added_first","oldest_added_first","name_a_to_z","name_z_to_a"],"examples":["recent_added_first"],"type":"string"}},{"description":"Page number of playlists.\n","in":"query","name":"page","required":false,"schema":{"default":1,"examples":[1],"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistsResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}},"links":{"paginate":{"description":"Pagination through playlists.","operationId":"getPlaylists","parameters":{"page":"$response.body#/page"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch a list of your playlists.","tags":["Playlist API"]}},"/playlists/{id}":{"get":{"description":"A playlist can be an episode list (i.e., all items are episodes) or a podcast list (i.e., all items are podcasts),\nwhich is essentially the same as those created via listennotes.com/listen/.\nThis endpoint fetches a list of items (i.e., episodes or podcasts) in the playlist.\nYou can use the **last_pub_date_ms** parameter to do pagination and fetch more items.\nA playlist can be **public** (discoverable on ListenNotes.com),\n**unlisted** (accessible to anyone who knows the playlist id),\nor **private** (accessible to its owner).\nYou can fetch all playlists created by you, and **public** / **unlisted** playlists created by others.\n","operationId":"getPlaylistById","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Playlist id (always 11 characters, e.g., m1pe7z60bsw).\nYou can get the podcast id from the url of a playlist, e.g.,\nm1pe7z60bsw is the playlist id of listennotes.com/listen/podcasts-about-podcasting-m1pe7z60bsw\n","example":"m1pe7z60bsw","explode":false,"in":"path","name":"id","required":true,"schema":{"type":"string"},"style":"simple"},{"description":"The type of this playlist, which should be either **episode_list** or **podcast_list**.\n","in":"query","name":"type","required":false,"schema":{"default":"episode_list","enum":["episode_list","podcast_list"],"examples":["episode_list"],"type":"string"}},{"description":"For playlist items pagination.\nIt's the value of **last_timestamp_ms** from the response of last request.\nIf it's 0 or not specified, just return the latest or the oldest 20 items,\ndepending on the value of the **sort** parameter.\n","in":"query","name":"last_timestamp_ms","required":false,"schema":{"default":0,"examples":[0],"type":"integer"}},{"description":"How do you want to sort playlist items?\n","in":"query","name":"sort","required":false,"schema":{"default":"recent_added_first","enum":["recent_added_first","oldest_added_first","recent_published_first","oldest_published_first"],"examples":["recent_added_first"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlaylistResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}},"links":{"paginate":{"description":"Pagination through playlist items.","operationId":"getPlaylistById","parameters":{"last_timestamp_ms":"$response.body#/last_timestamp_ms"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch a playlist's info and items (i.e., episodes or podcasts).","tags":["Playlist API"]}},"/podcasts":{"post":{"description":"Batch fetch basic meta data for up to 10 podcasts.\nThis endpoint could be used to build something like OPML import,\nallowing users to import a bunch of podcasts via rss urls.\nFor detailed meta data (including episodes) of an individual podcast, you need to use `GET /podcasts/{id}`. This endpoint is available only in the PRO/ENTERPRISE plan.\n","operationId":"getPodcastsInBatch","parameters":[{"$ref":"#/components/parameters/apiKeyParam"}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/GetPodcastsInBatchForm"}}},"required":false},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPodcastsInBatchResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}},"links":{"paginate":{"description":"Pagination through latest episodes.","operationId":"getPodcastsInBatch","parameters":{"next_episode_pub_date":"$response.body#/next_episode_pub_date"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Batch fetch basic meta data for podcasts","tags":["Directory API"]}},"/podcasts/domains/{domain_name}":{"get":{"description":"Fetch podcasts by a publisher's domain name, e.g., nytimes.com, wondery.com, npr.org...\nEach request will return up to 10 podcasts. You can use the `page` parameter to paginate.\n","operationId":"getPodcastsByDomainName","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"A publisher's domain name, e.g., nytimes.com, wondery.com, npr.org...","example":"nytimes.com","explode":false,"in":"path","name":"domain_name","required":true,"schema":{"type":"string"},"style":"simple"},{"description":"Page number of the podcasts from this domain name","in":"query","name":"page","required":false,"schema":{"default":1,"examples":[1],"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastDomainResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}},"links":{"paginate":{"description":"Pagination through podcasts.","operationId":"getPodcastsByDomainName","parameters":{"page":"$response.body#/next_page_number"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch podcasts by a publisher's domain name","tags":["Insights API"]}},"/podcasts/submit":{"post":{"description":"Podcast hosting services can use this endpoint to help your users directly submit a new podcast to Listen Notes database. If the podcast doesn't exist in the database, \"status\" in the response will be \"in review\", and we'll review it within 12 hours. If the podcast exists, \"status\" in the response will be \"found\". If this submission is rejected, \"status\" in the response will be \"rejected\". You can use `POST /podcasts` to check if multiple podcasts exist in the database. If you want to get a notification once the podcast is accepted, you can either specify the \"email\" parameter or configure a webhook url in the dashboard: listennotes.com/api/dashboard/#webhooks\n","operationId":"submitPodcast","parameters":[{"$ref":"#/components/parameters/apiKeyParam"}],"requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/SubmitPodcastForm"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmitPodcastResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Submit a podcast to Listen Notes database","tags":["Podcaster API"]}},"/podcasts/{id}":{"delete":{"description":"Podcast hosting services can use this endpoint to streamline the process of podcast deletion on behave of their users (podcasters). We will review the deletion request within 12 hours. If the podcast is already deleted, the \"status\" field in the response will be \"deleted\". Otherwise, the status field will be \"in review\". If you want to get a notification once the podcast is deleted, you can configure a webhook url in the dashboard: listennotes.com/api/dashboard/#webhooks\n","operationId":"deletePodcastById","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Podcast id. You can get podcast id from using other endpoints, e.g., `GET /search`, `GET /best_podcasts`...","example":"4d3fe717742d4963a85562e9f84d8c79","explode":false,"in":"path","name":"id","required":true,"schema":{"type":"string"},"style":"simple"},{"description":"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.","example":"the podcaster wants to delete it","explode":true,"in":"query","name":"reason","required":false,"schema":{"type":"string"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeletePodcastResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Request to delete a podcast","tags":["Podcaster API"]},"get":{"description":"Fetch detailed meta data and episodes for a specific podcast (up to 10 episodes each time).\nYou can use the **next_episode_pub_date** parameter to do pagination and fetch more episodes.\n","operationId":"getPodcastById","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Podcast id. You can get podcast id from using other endpoints, e.g., `GET /search`, `GET /best_podcasts`...","example":"4d3fe717742d4963a85562e9f84d8c79","explode":false,"in":"path","name":"id","required":true,"schema":{"type":"string"},"style":"simple"},{"description":"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.\n","example":1479154463000,"explode":true,"in":"query","name":"next_episode_pub_date","required":false,"schema":{"type":"integer"},"style":"form"},{"description":"How do you want to sort the episodes of this podcast?\n","example":"recent_first","explode":true,"in":"query","name":"sort","required":false,"schema":{"default":"recent_first","enum":["recent_first","oldest_first"],"type":"string"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastFull"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}},"links":{"paginate":{"description":"Pagination through episodes.","operationId":"getPodcastById","parameters":{"next_episode_pub_date":"$response.body#/next_episode_pub_date"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch detailed meta data and episodes for a podcast by id","tags":["Directory API"]}},"/podcasts/{id}/audience":{"get":{"description":"Fetch audience demographics for a podcast - 1) directly measured on the Listen Notes platform; 2) only supports audience breakdown by regions for now; 3) not every podcast has data.","operationId":"getPodcastAudience","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Podcast id.","example":"25212ac3c53240a880dd5032e547047b","explode":false,"in":"path","name":"id","required":true,"schema":{"type":"string"},"style":"simple"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PodcastAudienceResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch audience demographics for a podcast","tags":["Insights API"]}},"/podcasts/{id}/recommendations":{"get":{"description":"Fetch up to 8 podcast recommendations based on the given podcast id.","operationId":"getPodcastRecommendations","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Podcast id.","example":"25212ac3c53240a880dd5032e547047b","explode":false,"in":"path","name":"id","required":true,"schema":{"type":"string"},"style":"simple"},{"$ref":"#/components/parameters/safeModeParam"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetPodcastRecommendationsResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch recommendations for a podcast","tags":["Directory API"]}},"/regions":{"get":{"description":"It returns a dictionary of country codes (e.g., us, gb...) & country names (United States, United Kingdom...). The country code is used in the query parameter **region** of `GET /best_podcasts`.\n","operationId":"getRegions","parameters":[{"$ref":"#/components/parameters/apiKeyParam"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetRegionsResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch a list of supported countries/regions for best podcasts","tags":["Directory API"]}},"/related_searches":{"get":{"description":"Suggest related search terms. The results are more comprehensive than from `GET /typeahead`. This endpoint is available only in the PRO/ENTERPRISE plan.","operationId":"getRelatedSearches","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Search term, e.g., person, place, topic...\n","explode":true,"in":"query","name":"q","required":true,"schema":{"examples":["evergrande"],"type":"string"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatedSearchesResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch related search terms","tags":["Search API"]}},"/search":{"get":{"description":"Full-text search on episodes, podcasts, or curated lists of podcasts.\nUse the `offset` parameter to paginate through search results.\nThe FREE plan allows to see up to 30 search results (or `offset` < 30) per query.\nThe PRO plan allows to see up to 300 search results (or `offset` < 300) per query.\nThe ENTERPRISE plan allows to see up to 10,000 search results (or `offset` < 10000) per query.\n","operationId":"search","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"$ref":"#/components/parameters/queryParam"},{"description":"Sort by date or not? If 0, then sort by relevance. If 1, then sort by date.\n","explode":true,"in":"query","name":"sort_by_date","required":false,"schema":{"default":0,"enum":[0,1],"examples":[0],"type":"integer"},"style":"form"},{"description":"What type of contents do you want to search for? \n","explode":true,"in":"query","name":"type","required":false,"schema":{"default":"episode","enum":["episode","podcast","curated"],"examples":["episode"],"type":"string"},"style":"form"},{"description":"Offset for search results, for pagination. You'll use **next_offset** from response for this parameter.\n","explode":true,"in":"query","name":"offset","required":false,"schema":{"default":0,"examples":[0],"type":"integer"},"style":"form"},{"description":"Minimum audio length in minutes. Applicable only when **type** parameter is **episode** or **podcast**.\nIf **type** parameter is **episode**, it's for audio length of an episode.\nIf **type** parameter is **podcast**, it's for average audio length of all episodes in a podcast.\n","explode":true,"in":"query","name":"len_min","required":false,"schema":{"default":0,"examples":[10],"type":"integer"},"style":"form"},{"description":"Maximum audio length in minutes. Applicable only when **type** parameter is **episode** or **podcast**.\nIf **type** parameter is **episode**, it's for audio length of an episode.\nIf **type** parameter is **podcast**, it's for average audio length of all episodes in a podcast.\n","explode":true,"in":"query","name":"len_max","required":false,"schema":{"examples":[30],"type":"integer"},"style":"form"},{"description":"Minimum number of episodes. Applicable only when type parameter is **podcast**.\n","explode":true,"in":"query","name":"episode_count_min","required":false,"schema":{"type":"integer"},"style":"form"},{"description":"Maximum number of episodes. Applicable only when type parameter is **podcast**.\n","explode":true,"in":"query","name":"episode_count_max","required":false,"schema":{"type":"integer"},"style":"form"},{"description":"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**.\n","explode":true,"in":"query","name":"update_freq_min","required":false,"schema":{"type":"integer"},"style":"form"},{"description":"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**.\n","explode":true,"in":"query","name":"update_freq_max","required":false,"schema":{"type":"integer"},"style":"form"},{"description":"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*.\n","explode":true,"in":"query","name":"genre_ids","required":false,"schema":{"examples":["68,82"],"type":"string"},"style":"form"},{"description":"Only show episodes/podcasts/curated lists published before this timestamp (in milliseconds). If **published_before** & **published_after** are used at the same time, **published_before** should be bigger than **published_after**.\n","explode":true,"in":"query","name":"published_before","required":false,"schema":{"examples":[1580172454000],"type":"integer"},"style":"form"},{"description":"Only show episodes/podcasts/curated lists published after this timestamp (in milliseconds). If **published_before** & **published_after** are used at the same time, **published_before** should be bigger than **published_after**.\n","explode":true,"in":"query","name":"published_after","required":false,"schema":{"default":0,"examples":[0],"type":"integer"},"style":"form"},{"description":"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.\n","explode":true,"in":"query","name":"only_in","required":false,"schema":{"default":"title,description,author,audio","examples":["title,description"],"type":"string"},"style":"form"},{"description":"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*.\n","explode":true,"in":"query","name":"language","required":false,"schema":{"examples":["English"],"type":"string"},"style":"form"},{"description":"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*.\n","in":"query","name":"region","required":false,"schema":{"examples":[""],"type":"string"}},{"description":"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*.\n","explode":true,"in":"query","name":"ocid","required":false,"schema":{"type":"string"},"style":"form"},{"description":"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*.\n","explode":true,"in":"query","name":"ncid","required":false,"schema":{"type":"string"},"style":"form"},{"description":"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*.\n","explode":true,"in":"query","name":"safe_mode","required":false,"schema":{"default":0,"enum":[0,1],"examples":[0],"type":"integer"},"style":"form"},{"description":"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*.\n","explode":true,"in":"query","name":"unique_podcasts","required":false,"schema":{"default":0,"enum":[0,1],"examples":[0],"type":"integer"},"style":"form"},{"description":"The maximum number of search results per page. A valid value should be an integer between 1 and 10 (inclusive).\n","explode":true,"in":"query","name":"page_size","required":false,"schema":{"default":10,"examples":[10],"type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}},"links":{"paginate":{"description":"Pagination through search results.","operationId":"search","parameters":{"offset":"$response.body#/next_offset"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Full-text search","tags":["Search API"]}},"/spellcheck":{"get":{"description":"Suggest a list of words that correct the spelling errors of a search term. This endpoint is available only in the PRO/ENTERPRISE plan.","operationId":"spellcheck","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"description":"Search term, e.g., person, place, topic...\n","explode":true,"in":"query","name":"q","required":true,"schema":{"examples":["evergrand stok"],"type":"string"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SpellCheckResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Spell check on a search term","tags":["Search API"]}},"/trending_searches":{"get":{"description":"Fetch up to 10 most recent trending search terms on the Listen Notes platform.","operationId":"getTrendingSearches","parameters":[{"$ref":"#/components/parameters/apiKeyParam"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrendingSearchesResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Fetch trending search terms","tags":["Search API"]}},"/typeahead":{"get":{"description":"Suggest search terms, podcast genres, and podcasts.","operationId":"typeahead","parameters":[{"$ref":"#/components/parameters/apiKeyParam"},{"$ref":"#/components/parameters/queryParam"},{"description":"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.\n","explode":true,"in":"query","name":"show_podcasts","required":false,"schema":{"default":0,"enum":[0,1],"examples":[1],"type":"integer"},"style":"form"},{"description":"Whether or not to autosuggest genres. 1 is yes, 0 is no.\n","explode":true,"in":"query","name":"show_genres","required":false,"schema":{"default":0,"enum":[0,1],"examples":[1],"type":"integer"},"style":"form"},{"description":"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*.\n","explode":true,"in":"query","name":"safe_mode","required":false,"schema":{"default":0,"enum":[0,1],"examples":[0],"type":"integer"},"style":"form"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TypeaheadResponse"}}},"description":"OK","headers":{"X-ListenAPI-FreeQuota":{"$ref":"#/components/headers/X-ListenAPI-FreeQuota"},"X-ListenAPI-NextBillingDate":{"$ref":"#/components/headers/X-ListenAPI-NextBillingDate"},"X-ListenAPI-Usage":{"$ref":"#/components/headers/X-ListenAPI-Usage"},"X-listenAPI-Latency-Seconds":{"$ref":"#/components/headers/X-listenAPI-Latency-Seconds"}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"5XX":{"$ref":"#/components/responses/ServerError"}},"summary":"Typeahead search","tags":["Search API"]}}},"components":{"headers":{"X-ListenAPI-FreeQuota":{"description":"Free quotas of API requests included in your api plan.","explode":false,"schema":{"examples":[25000],"type":"integer"},"style":"simple"},"X-ListenAPI-NextBillingDate":{"description":"The timestamp for the start of next billing cycle. In ISO 8601 format.","schema":{"examples":["2025-04-15T13:50:50.133Z"],"format":"date-time","type":"string"},"style":"simple"},"X-ListenAPI-Usage":{"description":"The number of API requests that you've used in current billing cycle.","explode":false,"schema":{"examples":[19231],"type":"integer"},"style":"simple"},"X-listenAPI-Latency-Seconds":{"description":"Latency for this api call, in seconds.","explode":false,"schema":{"examples":[0.056],"type":"number"},"style":"simple"}},"parameters":{"apiKeyParam":{"description":"Get API Key on listennotes.com/api","explode":false,"in":"header","name":"X-ListenAPI-Key","required":true,"schema":{"type":"string"},"style":"simple"},"genreIdParam":{"description":"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.","in":"query","name":"genre_id","required":false,"schema":{"examples":[93],"type":"string"}},"queryParam":{"description":"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.\n","explode":true,"in":"query","name":"q","required":true,"schema":{"examples":["star wars"],"type":"string"},"style":"form"},"safeModeParam":{"description":"Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.","in":"query","name":"safe_mode","required":false,"schema":{"default":0,"enum":[0,1],"examples":[0],"type":"integer"}}},"responses":{"BadRequest":{"description":"Something wrong on your end (Client side errors), e.g., missing required parameters."},"NotFound":{"description":"Endpoint not exist, or podcast / episode not exist."},"ServerError":{"description":"Something wrong on our end (Unexpected server errors)."},"TooManyRequests":{"description":"For FREE plan, exceeding the quota limit; or for all plans, sending too many requests too fast and exceeding the rate limit."},"Unauthorized":{"description":"Wrong api key, or your account is suspended."}},"schemas":{"AudioField":{"description":"Audio url of this episode, which can be played directly.","examples":["https://www.listennotes.com/e/p/11b34041e804491b9704d11f283c74de/"],"type":"string"},"AudioLengthSecField":{"description":"Audio length of this episode. In seconds.","examples":[567],"type":"integer"},"AvgAudioLengthSecField":{"description":"Average audio length of all episodes of this podcast. In seconds.","examples":[1291],"type":"integer"},"BestPodcastsLNUrlField":{"description":"Url of the list of best podcasts on [ListenNotes.com](https://www.ListenNotes.com).","examples":["https://www.listennotes.com/best-business-news-podcasts-95/"],"type":"string"},"BestPodcastsResponse":{"properties":{"has_next":{"examples":[true],"type":"boolean"},"has_previous":{"examples":[true],"type":"boolean"},"id":{"description":"The id of this genre","examples":[95],"type":"integer"},"listennotes_url":{"$ref":"#/components/schemas/BestPodcastsLNUrlField"},"name":{"description":"This genre's name.","examples":["Business News"],"type":"string"},"next_page_number":{"examples":[3],"type":"integer"},"page_number":{"examples":[2],"type":"integer"},"parent_id":{"description":"The id of parent genre.","examples":[93],"type":"integer"},"podcasts":{"items":{"$ref":"#/components/schemas/PodcastSimple"},"type":"array"},"previous_page_number":{"examples":[1],"type":"integer"},"total":{"examples":[325],"type":"integer"}},"required":["has_next","has_previous","id","listennotes_url","name","next_page_number","page_number","parent_id","podcasts","previous_page_number","total"],"type":"object"},"CountryField":{"description":"The country where this podc