{ "openapi": "3.0.1", "info": { "title": "Listen API: Podcast Search & Directory API", "description": "This is a generated connector for [Listen Notes API v2.0](https://www.listennotes.com/) OpenAPI specification. \nSimple & no-nonsense podcast search & directory API. Search all podcasts and episodes by people, places, or topics.", "x-ballerina-display": { "label": "Listen Notes", "iconPath": "icon.png" }, "x-ballerina-init-description": "The connector initialization requires setting the API credentials.\nCreate a [Listen Notes account](https://www.listennotes.com/) and obtain tokens by following [this guide](https://help.listennotes.com/en/articles/3416436-how-to-get-an-api-token-of-listen-notes-api).", "termsOfService": "https://www.listennotes.com/api/terms/", "contact": { "name": "Listen Notes", "url": "https://www.listennotes.com/api/", "email": "hello@listennotes.com" }, "version": "2.0" }, "servers": [ { "url": "https://listen-api.listennotes.com/api/v2", "description": "API Production Server" } ], "tags": [ { "name": "Search API", "description": "Endpoints to search podcasts" }, { "name": "Directory API", "description": "Endpoints to fetch podcasts data" }, { "name": "Podcaster API", "description": "Endpoints to improve the podcast database" } ], "paths": { "/search": { "get": { "tags": [ "Search API" ], "summary": "Full-text search", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "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", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "star wars" } }, { "name": "sort_by_date", "in": "query", "description": "Sort by date or not? If 0, then sort by relevance. If 1, then sort by date.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0, "enum": [ 0, 1 ] } }, { "name": "type", "in": "query", "description": "What type of contents do you want to search for? \n", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "episode", "default": "episode", "enum": [ "episode", "podcast", "curated" ] } }, { "name": "offset", "in": "query", "description": "Offset for search results, for pagination. You'll use **next_offset** from response for this parameter.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0 } }, { "name": "len_min", "in": "query", "description": "Minimum audio length in minutes. Applicable only when type parameter is **episode**.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 10, "default": 0 } }, { "name": "len_max", "in": "query", "description": "Maximum audio length in minutes. Applicable only when type parameter is **episode**.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 30 } }, { "name": "episode_count_min", "in": "query", "description": "Minimum number of episodes. Applicable only when type parameter is **podcast**.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer" } }, { "name": "episode_count_max", "in": "query", "description": "Maximum number of episodes. Applicable only when type parameter is **podcast**.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer" } }, { "name": "genre_ids", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "68,82" } }, { "name": "published_before", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 1580172454000 } }, { "name": "published_after", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0 } }, { "name": "only_in", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "title,description", "default": "title,description,author,audio" } }, { "name": "language", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "English" } }, { "name": "region", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "" } }, { "name": "ocid", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "ncid", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "safe_mode", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0, "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } }, "links": { "paginate": { "operationId": "search", "parameters": { "offset": "$response.body#/next_offset" }, "description": "Pagination through search results." } } }, "400": { "description": "Something wrong on your end (Client side errors), e.g., missing required parameters." }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/typeahead": { "get": { "tags": [ "Search API" ], "summary": "Typeahead search", "description": "Suggest search terms, podcast genres, and podcasts.", "operationId": "typeahead", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "q", "in": "query", "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", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "star wars" } }, { "name": "show_podcasts", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 1, "default": 0, "enum": [ 0, 1 ] } }, { "name": "show_genres", "in": "query", "description": "Whether or not to autosuggest genres. 1 is yes, 0 is no.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 1, "default": 0, "enum": [ 0, 1 ] } }, { "name": "safe_mode", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0, "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TypeaheadResponse" } } } }, "400": { "description": "Something wrong on your end (Client side errors), e.g., missing required parameters." }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/best_podcasts": { "get": { "tags": [ "Directory API" ], "summary": "Fetch a list of best podcasts by genre", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "genre_id", "in": "query", "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.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "93" } }, { "name": "page", "in": "query", "description": "Page number of those podcasts in this genre.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 2 } }, { "name": "region", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "us", "default": "us" } }, { "name": "publisher_region", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "language", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "string" } }, { "name": "safe_mode", "in": "query", "description": "Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0, "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BestPodcastsResponse" } } }, "links": { "paginate": { "operationId": "getBestPodcasts", "parameters": { "page": "$response.body#/next_page_number" }, "description": "Pagination through podcasts." } } }, "401": { "description": "Wrong api key or your account is suspended." }, "404": { "description": "Endpoint not exist, or podcast / episode not exist." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/podcasts/{id}": { "get": { "tags": [ "Directory API" ], "summary": "Fetch detailed meta data and episodes for a podcast by id", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Podcast id. You can get podcast id from using other endpoints, e.g., `GET /search`, `GET /best_podcasts`...", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "4d3fe717742d4963a85562e9f84d8c79" }, { "name": "next_episode_pub_date", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "integer" }, "example": 1479154463000 }, { "name": "sort", "in": "query", "description": "How do you want to sort the episodes of this podcast?\n", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "default": "recent_first", "enum": [ "recent_first", "oldest_first" ] }, "example": "recent_first" } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PodcastFull" } } }, "links": { "paginate": { "operationId": "getPodcastById", "parameters": { "next_episode_pub_date": "$response.body#/next_episode_pub_date" }, "description": "Pagination through episodes." } } }, "401": { "description": "Wrong api key or your account is suspended." }, "404": { "description": "Endpoint not exist, or podcast / episode not exist." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } }, "delete": { "tags": [ "Podcaster API" ], "summary": "Request to delete a podcast", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Podcast id. You can get podcast id from using other endpoints, e.g., `GET /search`, `GET /best_podcasts`...", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "4d3fe717742d4963a85562e9f84d8c79" }, { "name": "reason", "in": "query", "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.", "required": false, "style": "form", "explode": true, "schema": { "type": "string" }, "example": "the podcaster wants to delete it" } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePodcastResponse" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "404": { "description": "Endpoint not exist, or podcast / episode not exist." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/episodes/{id}": { "get": { "tags": [ "Directory API" ], "summary": "Fetch detailed meta data for an episode by id", "description": "Fetch detailed meta data for a specific episode.", "operationId": "getEpisodeById", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "id for a specific episode. You can get episode id from using other endpoints, e.g., `GET /search`...", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "example": "6b6d65930c5a4f71b254465871fed370" } }, { "name": "show_transcript", "in": "query", "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.", "required": false, "style": "form", "explode": false, "schema": { "type": "integer", "example": 1, "default": 0 } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeFull" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "404": { "description": "Endpoint not exist, or podcast / episode not exist." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/episodes": { "post": { "tags": [ "Directory API" ], "summary": "Batch fetch basic meta data for episodes", "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", "security": [ { "ApiKey": [] } ], "requestBody": { "description": "Get episodes batch payload", "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/GetEpisodesInBatchForm" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEpisodesInBatchResponse" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/podcasts": { "post": { "tags": [ "Directory API" ], "summary": "Batch fetch basic meta data for podcasts", "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", "security": [ { "ApiKey": [] } ], "requestBody": { "description": "Get podcasts batch payload", "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/GetPodcastsInBatchForm" } } }, "required": false }, "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPodcastsInBatchResponse" } } }, "links": { "paginate": { "operationId": "getPodcastsInBatch", "parameters": { "next_episode_pub_date": "$response.body#/next_episode_pub_date" }, "description": "Pagination through latest episodes." } } }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/curated_podcasts/{id}": { "get": { "tags": [ "Directory API" ], "summary": "Fetch a curated list of podcasts by id", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "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", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "example": "SDFKduyJ47r" } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CuratedListFull" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "404": { "description": "Endpoint not exist, or podcast / episode not exist." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/genres": { "get": { "tags": [ "Directory API" ], "summary": "Fetch a list of podcast genres", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "top_level_only", "in": "query", "description": "Just show top level genres? If 1, yes, just show top level genres. If 0, no, show all genres.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 1, "default": 0, "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetGenresResponse" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/regions": { "get": { "tags": [ "Directory API" ], "summary": "Fetch a list of supported countries/regions for best podcasts", "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", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRegionsResponse" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/languages": { "get": { "tags": [ "Directory API" ], "summary": "Fetch a list of supported languages for podcasts", "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", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLanguagesResponse" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/just_listen": { "get": { "tags": [ "Directory API" ], "summary": "Fetch a random podcast episode", "description": "Recently published episodes are more likely to be fetched. Good luck!", "operationId": "justListen", "security": [ { "ApiKey": [] } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EpisodeSimple" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/curated_podcasts": { "get": { "tags": [ "Directory API" ], "summary": "Fetch curated lists of podcasts", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "page", "in": "query", "description": "Page number of curated lists.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "default": 1 }, "example": 2 } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetCuratedPodcastsResponse" } } }, "links": { "paginate": { "operationId": "getCuratedPodcasts", "parameters": { "page": "$response.body#/next_page_number" }, "description": "Pagination through curated lists." } } }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/podcasts/{id}/recommendations": { "get": { "tags": [ "Directory API" ], "summary": "Fetch recommendations for a podcast", "description": "Fetch up to 8 podcast recommendations based on the given podcast id.", "operationId": "getPodcastRecommendations", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Podcast id.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "25212ac3c53240a880dd5032e547047b" }, { "name": "safe_mode", "in": "query", "description": "Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0, "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPodcastRecommendationsResponse" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "404": { "description": "Endpoint not exist, or podcast / episode not exist." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/episodes/{id}/recommendations": { "get": { "tags": [ "Directory API" ], "summary": "Fetch recommendations for an episode", "description": "Fetch up to 8 episode recommendations based on the given episode id.", "operationId": "getEpisodeRecommendations", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "description": "Episode id.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "254444fa6cf64a43a95292a70eb6869b" }, { "name": "safe_mode", "in": "query", "description": "Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0, "enum": [ 0, 1 ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetEpisodeRecommendationsResponse" } } } }, "401": { "description": "Wrong api key or your account is suspended." }, "404": { "description": "Endpoint not exist, or podcast / episode not exist." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/podcasts/submit": { "post": { "tags": [ "Podcaster API" ], "summary": "Submit a podcast to Listen Notes database", "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\". 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", "security": [ { "ApiKey": [] } ], "requestBody": { "description": "Submit podcast payload", "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/SubmitPodcastForm" } } }, "required": true }, "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitPodcastResponse" } } } }, "400": { "description": "Something wrong on your end (Client side errors), e.g., missing required parameters." }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/playlists/{id}": { "get": { "tags": [ "Playlist API" ], "summary": "Fetch a playlist's info and items (i.e., episodes or podcasts).", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "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", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" }, "example": "m1pe7z60bsw" }, { "name": "type", "in": "query", "description": "The type of this playlist, which should be either **episode_list** or **podcast_list**.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "episode_list", "default": "episode_list", "enum": [ "episode_list", "podcast_list" ] } }, { "name": "last_timestamp_ms", "in": "query", "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", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0 } }, { "name": "sort", "in": "query", "description": "How do you want to sort playlist items?\n", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "recent_added_first", "default": "recent_added_first", "enum": [ "recent_added_first", "oldest_added_first", "recent_published_first", "oldest_published_first" ] } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistResponse" } } }, "links": { "paginate": { "operationId": "getPlaylistById", "parameters": { "last_timestamp_ms": "$response.body#/last_timestamp_ms" }, "description": "Pagination through playlist items." } } }, "401": { "description": "Wrong api key or your account is suspended." }, "404": { "description": "Endpoint not exist, or podcast / episode not exist." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } }, "/playlists": { "get": { "tags": [ "Playlist API" ], "summary": "Fetch a list of your playlists.", "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", "security": [ { "ApiKey": [] } ], "parameters": [ { "name": "sort", "in": "query", "description": "How do you want to sort playlists?\n", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "recent_added_first", "default": "recent_added_first", "enum": [ "recent_added_first", "oldest_added_first", "name_a_to_z", "name_z_to_a" ] } }, { "name": "page", "in": "query", "description": "Page number of playlists.\n", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 1, "default": 1 } } ], "responses": { "200": { "description": "OK", "headers": { "X-ListenAPI-FreeQuota": { "$ref": "#/components/headers/X-ListenAPI-FreeQuota" }, "X-ListenAPI-Usage": { "$ref": "#/components/headers/X-ListenAPI-Usage" }, "X-listenAPI-Latency-Seconds": { "$ref": "#/components/headers/X-listenAPI-Latency-Seconds" }, "X-ListenAPI-NextBillingDate": { "$ref": "#/components/headers/X-ListenAPI-NextBillingDate" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaylistsResponse" } } }, "links": { "paginate": { "operationId": "getPlaylists", "parameters": { "page": "$response.body#/page" }, "description": "Pagination through playlists." } } }, "401": { "description": "Wrong api key or your account is suspended." }, "429": { "description": "You are using FREE plan and you exceed the quota limit." }, "5XX": { "description": "Something wrong on our end (Unexpected server errors)." } } } } }, "components": { "securitySchemes": { "ApiKey": { "type": "apiKey", "in": "header", "name": "X-ListenAPI-Key", "description": "Represents API Key `X-ListenAPI-Key`" } }, "schemas": { "EpisodeSearchResult": { "type": "object", "properties": { "audio": { "$ref": "#/components/schemas/AudioField" }, "audio_length_sec": { "$ref": "#/components/schemas/AudioLengthSecField" }, "rss": { "$ref": "#/components/schemas/RssField" }, "description_highlighted": { "type": "string", "description": "Highlighted segment of this episode's description", "example": "...Go to http://Patreon.com/sw7x7 to donate to the Star Wars 7x7 podcast, and you'll get some fabulous rewards for your pledge.*** Check out SW7x7.com for full Star Wars 7x7 show notes and links, and to\n" }, "description_original": { "type": "string", "description": "Plain text of this episode's description", "example": "Yeah, Star Wars Celebration Orlando is 32 days away, but what's the scoop on Celebration 2018? Plus, Rebels Day is Saturday, and much more in our update. Punch it! ***We're listener supported! Go to http://Patreon.com/sw7x7 to donate to the Star Wars 7x7 podcast, and you’ll get some fabulous rewards for your pledge.*** Check out SW7x7.com for full Star Wars 7x7 show notes and links, and to comment on any of the content of this episode! If you like what you've heard, please leave us a rating or review on iTunes or Stitcher, which will also help more people discover this Star Wars podcast. Don't forget to join the Star Wars 7x7 fun on Facebook at Facebook.com/SW7x7, and follow the breaking news Twitter feed at Twitter.com/SW7x7Podcast. We're also on Pinterest and Instagram as \"SW7x7\" too, and we'd love to connect with you there!\n" }, "title_highlighted": { "type": "string", "description": "Highlighted segment of this episode's title", "example": "815: Star Wars 2020 Movie and Beyond!" }, "title_original": { "type": "string", "description": "Plain text of this episode' title", "example": "815: Star Wars 2020 Movie and Beyond!" }, "transcripts_highlighted": { "type": "array", "description": "Up to 2 highlighted segments of the audio transcript of this episode.", "items": { "type": "string", "example": "00:21:27 when Disney bought the Star Wars franchise from George Lucas they had a plan lots of Star Wars movies new Star Wars movies every month another one was just released while I was talking\n" } }, "image": { "$ref": "#/components/schemas/EpisodeImageField" }, "thumbnail": { "$ref": "#/components/schemas/EpisodeThumbnailField" }, "itunes_id": { "$ref": "#/components/schemas/iTunesIdField" }, "pub_date_ms": { "$ref": "#/components/schemas/EpisodePubDateMsField" }, "id": { "$ref": "#/components/schemas/EpisodeIdField" }, "listennotes_url": { "$ref": "#/components/schemas/EpisodeLNUrlField" }, "explicit_content": { "$ref": "#/components/schemas/ExplicitField" }, "link": { "$ref": "#/components/schemas/LinkField" }, "podcast": { "$ref": "#/components/schemas/EpisodeSearchResult_podcast" } }, "description": "When **type** is *episode*." }, "PodcastSearchResult": { "type": "object", "properties": { "rss": { "$ref": "#/components/schemas/RssField" }, "description_highlighted": { "type": "string", "description": "Highlighted segment of podcast description", "example": "...Join host Allen Voivod for Star Wars news, history, interviews, trivia, and deep dives into the Star Wars story as told in movies, books, comics, games, cartoons, and more.\n" }, "description_original": { "type": "string", "description": "Plain text of podcast description", "example": "The Star Wars 7x7 Podcast is Rebel-rousing fun for everyday Jedi, between 7 and 14 minutes a day, 7 days a week. Join host Allen Voivod for Star Wars news, history, interviews, trivia, and deep dives into the Star Wars story as told in movies, books, comics, games, cartoons, and more. Subscribe now for your daily dose of Star Wars joy. It's destiny unleashed! #SW7x7\n" }, "title_highlighted": { "$ref": "#/components/schemas/PodcastTitleHighlightedField" }, "title_original": { "$ref": "#/components/schemas/PodcastTitleOriginalField" }, "publisher_highlighted": { "$ref": "#/components/schemas/PublisherHighlightedField" }, "publisher_original": { "$ref": "#/components/schemas/PublisherOriginalField" }, "image": { "$ref": "#/components/schemas/ImageField" }, "thumbnail": { "$ref": "#/components/schemas/ThumbnailField" }, "itunes_id": { "$ref": "#/components/schemas/iTunesIdField" }, "latest_pub_date_ms": { "$ref": "#/components/schemas/LatestPubDateMsField" }, "earliest_pub_date_ms": { "$ref": "#/components/schemas/EarliestPubDateMsField" }, "id": { "$ref": "#/components/schemas/PodcastIdField" }, "genre_ids": { "$ref": "#/components/schemas/GenreIdsField" }, "listennotes_url": { "$ref": "#/components/schemas/PodcastLNUrlField" }, "total_episodes": { "$ref": "#/components/schemas/TotalEpisodesField" }, "email": { "$ref": "#/components/schemas/EmailField" }, "explicit_content": { "$ref": "#/components/schemas/ExplicitField" }, "website": { "$ref": "#/components/schemas/WebsiteField" }, "listen_score": { "$ref": "#/components/schemas/ListenScoreField" }, "listen_score_global_rank": { "$ref": "#/components/schemas/ListenScoreGlobalRankField" } }, "description": "When **type** is *podcast*." }, "CuratedListSearchResult": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/CuratedIdField" }, "pub_date_ms": { "$ref": "#/components/schemas/CuratedPubDateMsField" }, "description_highlighted": { "type": "string", "description": "Highlighted segment of this curated list's description", "example": "...Star Wars fans in Reddit shared their favorite podcasts." }, "description_original": { "type": "string", "description": "Plain text of this curated list's description", "example": "Star Wars fans in Reddit shared their favorite podcasts." }, "title_highlighted": { "type": "string", "description": "Highlighted segment of this curated list's title", "example": "What are some good Star Wars Podcast to listen to?\n" }, "title_original": { "type": "string", "description": "Plain text of this curated list's title", "example": "What are some good Star Wars Podcast to listen to?" }, "listennotes_url": { "$ref": "#/components/schemas/CuratedLNUrlField" }, "source_url": { "$ref": "#/components/schemas/CuratedSourceUrlField" }, "source_domain": { "$ref": "#/components/schemas/CuratedSourceDomainField" }, "total": { "$ref": "#/components/schemas/CuratedTotalPodcastsField" }, "podcasts": { "type": "array", "description": "Up to 5 podcasts in this curated list.", "items": { "$ref": "#/components/schemas/PodcastMinimum" } } }, "description": "When **type** is *curated*." }, "Genre": { "type": "object", "properties": { "id": { "type": "integer", "description": "Genre id", "example": 93 }, "name": { "type": "string", "description": "Genre name.", "example": "Business" }, "parent_id": { "type": "integer", "description": "Parent genre id.", "example": 95 } }, "example": { "id": 140, "parent_id": 127, "name": "Web Design" } }, "PodcastTypeaheadResult": { "type": "object", "properties": { "publisher_highlighted": { "$ref": "#/components/schemas/PublisherHighlightedField" }, "publisher_original": { "$ref": "#/components/schemas/PublisherOriginalField" }, "explicit_content": { "$ref": "#/components/schemas/ExplicitField" }, "image": { "$ref": "#/components/schemas/ImageField" }, "thumbnail": { "$ref": "#/components/schemas/ThumbnailField" }, "title_highlighted": { "$ref": "#/components/schemas/PodcastTitleHighlightedField" }, "title_original": { "$ref": "#/components/schemas/PodcastTitleOriginalField" }, "id": { "$ref": "#/components/schemas/PodcastIdField" } } }, "PodcastMinimum": { "type": "object", "properties": { "image": { "$ref": "#/components/schemas/ImageField" }, "thumbnail": { "$ref": "#/components/schemas/ThumbnailField" }, "title": { "$ref": "#/components/schemas/PodcastNameField" }, "listennotes_url": { "$ref": "#/components/schemas/PodcastLNUrlField" }, "id": { "$ref": "#/components/schemas/PodcastIdField" }, "publisher": { "$ref": "#/components/schemas/PublisherField" }, "listen_score": { "$ref": "#/components/schemas/ListenScoreField" }, "listen_score_global_rank": { "$ref": "#/components/schemas/ListenScoreGlobalRankField" } } }, "PodcastSimple": { "type": "object", "properties": { "is_claimed": { "$ref": "#/components/schemas/IsClaimedField" }, "type": { "$ref": "#/components/schemas/PodcastTypeField" }, "explicit_content": { "$ref": "#/components/schemas/ExplicitField" }, "website": { "$ref": "#/components/schemas/WebsiteField" }, "total_episodes": { "$ref": "#/components/schemas/TotalEpisodesField" }, "earliest_pub_date_ms": { "$ref": "#/components/schemas/EarliestPubDateMsField" }, "rss": { "$ref": "#/components/schemas/RssField" }, "latest_pub_date_ms": { "$ref": "#/components/schemas/LatestPubDateMsField" }, "title": { "$ref": "#/components/schemas/PodcastNameField" }, "language": { "$ref": "#/components/schemas/LanguageField" }, "description": { "$ref": "#/components/schemas/PodcastDescriptionField" }, "email": { "$ref": "#/components/schemas/EmailField" }, "image": { "$ref": "#/components/schemas/ImageField" }, "thumbnail": { "$ref": "#/components/schemas/ThumbnailField" }, "listennotes_url": { "$ref": "#/components/schemas/PodcastLNUrlField" }, "id": { "$ref": "#/components/schemas/PodcastIdField" }, "country": { "$ref": "#/components/schemas/CountryField" }, "publisher": { "$ref": "#/components/schemas/PublisherField" }, "itunes_id": { "$ref": "#/components/schemas/iTunesIdField" }, "looking_for": { "$ref": "#/components/schemas/PodcastLookingForField" }, "extra": { "$ref": "#/components/schemas/PodcastExtraField" }, "genre_ids": { "$ref": "#/components/schemas/GenreIdsField" }, "listen_score": { "$ref": "#/components/schemas/ListenScoreField" }, "listen_score_global_rank": { "$ref": "#/components/schemas/ListenScoreGlobalRankField" } } }, "PodcastFull": { "type": "object", "properties": { "episodes": { "type": "array", "items": { "$ref": "#/components/schemas/EpisodeMinimum" } }, "is_claimed": { "$ref": "#/components/schemas/IsClaimedField" }, "type": { "$ref": "#/components/schemas/PodcastTypeField" }, "explicit_content": { "$ref": "#/components/schemas/ExplicitField" }, "website": { "$ref": "#/components/schemas/WebsiteField" }, "total_episodes": { "$ref": "#/components/schemas/TotalEpisodesField" }, "earliest_pub_date_ms": { "$ref": "#/components/schemas/EarliestPubDateMsField" }, "rss": { "$ref": "#/components/schemas/RssField" }, "latest_pub_date_ms": { "$ref": "#/components/schemas/LatestPubDateMsField" }, "title": { "$ref": "#/components/schemas/PodcastNameField" }, "language": { "$ref": "#/components/schemas/LanguageField" }, "description": { "$ref": "#/components/schemas/PodcastDescriptionField" }, "email": { "$ref": "#/components/schemas/EmailField" }, "image": { "$ref": "#/components/schemas/ImageField" }, "thumbnail": { "$ref": "#/components/schemas/ThumbnailField" }, "listennotes_url": { "$ref": "#/components/schemas/PodcastLNUrlField" }, "id": { "$ref": "#/components/schemas/PodcastIdField" }, "country": { "$ref": "#/components/schemas/CountryField" }, "publisher": { "$ref": "#/components/schemas/PublisherField" }, "itunes_id": { "$ref": "#/components/schemas/iTunesIdField" }, "looking_for": { "$ref": "#/components/schemas/PodcastLookingForField" }, "extra": { "$ref": "#/components/schemas/PodcastExtraField" }, "genre_ids": { "$ref": "#/components/schemas/GenreIdsField" }, "next_episode_pub_date": { "$ref": "#/components/schemas/NextEpisodePubDateField" }, "listen_score": { "$ref": "#/components/schemas/ListenScoreField" }, "listen_score_global_rank": { "$ref": "#/components/schemas/ListenScoreGlobalRankField" } } }, "EpisodeMinimum": { "type": "object", "properties": { "maybe_audio_invalid": { "$ref": "#/components/schemas/MaybeAudioInvalidField" }, "pub_date_ms": { "$ref": "#/components/schemas/EpisodePubDateMsField" }, "audio": { "$ref": "#/components/schemas/AudioField" }, "listennotes_edit_url": { "$ref": "#/components/schemas/EpisodeLNEditUrlField" }, "image": { "$ref": "#/components/schemas/ImageField" }, "thumbnail": { "$ref": "#/components/schemas/ThumbnailField" }, "description": { "$ref": "#/components/schemas/EpisodeDescriptionField" }, "title": { "$ref": "#/components/schemas/EpisodeNameField" }, "explicit_content": { "$ref": "#/components/schemas/ExplicitField" }, "listennotes_url": { "$ref": "#/components/schemas/EpisodeLNUrlField" }, "audio_length_sec": { "$ref": "#/components/schemas/AudioLengthSecField" }, "id": { "$ref": "#/components/schemas/EpisodeIdField" }, "link": { "$ref": "#/components/schemas/LinkField" } } }, "EpisodeSimple": { "type": "object", "properties": { "maybe_audio_invalid": { "$ref": "#/components/schemas/MaybeAudioInvalidField" }, "pub_date_ms": { "$ref": "#/components/schemas/EpisodePubDateMsField" }, "audio": { "$ref": "#/components/schemas/AudioField" }, "listennotes_edit_url": { "$ref": "#/components/schemas/EpisodeLNEditUrlField" }, "image": { "$ref": "#/components/schemas/EpisodeImageField" }, "thumbnail": { "$ref": "#/components/schemas/EpisodeThumbnailField" }, "description": { "$ref": "#/components/schemas/EpisodeDescriptionField" }, "title": { "$ref": "#/components/schemas/EpisodeNameField" }, "explicit_content": { "$ref": "#/components/schemas/ExplicitField" }, "listennotes_url": { "$ref": "#/components/schemas/EpisodeLNUrlField" }, "audio_length_sec": { "$ref": "#/components/schemas/AudioLengthSecField" }, "id": { "$ref": "#/components/schemas/EpisodeIdField" }, "link": { "$ref": "#/components/schemas/LinkField" }, "podcast": { "$ref": "#/components/schemas/PodcastMinimum" } } }, "EpisodeFull": { "type": "object", "properties": { "maybe_audio_invalid": { "$ref": "#/components/schemas/MaybeAudioInvalidField" }, "pub_date_ms": { "$ref": "#/components/schemas/EpisodePubDateMsField" }, "audio": { "$ref": "#/components/schemas/AudioField" }, "listennotes_edit_url": { "$ref": "#/components/schemas/EpisodeLNEditUrlField" }, "image": { "$ref": "#/components/schemas/EpisodeImageField" }, "thumbnail": { "$ref": "#/components/schemas/EpisodeThumbnailField" }, "description": { "$ref": "#/components/schemas/EpisodeDescriptionField" }, "title": { "$ref": "#/components/schemas/EpisodeNameField" }, "explicit_content": { "$ref": "#/components/schemas/ExplicitField" }, "listennotes_url": { "$ref": "#/components/schemas/EpisodeLNUrlField" }, "audio_length_sec": { "$ref": "#/components/schemas/AudioLengthSecField" }, "id": { "$ref": "#/components/schemas/EpisodeIdField" }, "podcast": { "$ref": "#/components/schemas/PodcastSimple" }, "link": { "$ref": "#/components/schemas/LinkField" }, "transcript": { "$ref": "#/components/schemas/TranscriptField" } } }, "CuratedListFull": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/CuratedIdField" }, "description": { "$ref": "#/components/schemas/CuratedDescriptionField" }, "source_url": { "$ref": "#/components/schemas/CuratedSourceUrlField" }, "source_domain": { "$ref": "#/components/schemas/CuratedSourceDomainField" }, "pub_date_ms": { "$ref": "#/components/schemas/CuratedPubDateMsField" }, "listennotes_url": { "$ref": "#/components/schemas/CuratedLNUrlField" }, "title": { "$ref": "#/components/schemas/CuratedNameField" }, "total": { "$ref": "#/components/schemas/CuratedTotalPodcastsField" }, "podcasts": { "type": "array", "description": "Complete meta data of all podcasts in this curated list.", "items": { "$ref": "#/components/schemas/PodcastSimple" } } } }, "CuratedListSimple": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/CuratedIdField" }, "description": { "$ref": "#/components/schemas/CuratedDescriptionField" }, "source_url": { "$ref": "#/components/schemas/CuratedSourceUrlField" }, "source_domain": { "$ref": "#/components/schemas/CuratedSourceDomainField" }, "pub_date_ms": { "$ref": "#/components/schemas/CuratedPubDateMsField" }, "listennotes_url": { "$ref": "#/components/schemas/CuratedLNUrlField" }, "title": { "$ref": "#/components/schemas/CuratedNameField" }, "total": { "$ref": "#/components/schemas/CuratedTotalPodcastsField" }, "podcasts": { "type": "array", "description": "Minimum meta data of up to 5 podcasts in this curated list.", "items": { "$ref": "#/components/schemas/PodcastMinimum" } } } }, "CustomAudio": { "type": "object", "properties": { "title": { "type": "string", "description": "Custom audio title.", "example": "An awesome audio to listen." }, "audio": { "type": "string", "description": "Audio url, which can be played directly.", "example": "https://example.com/audio.mp3" }, "audio_length_sec": { "type": "integer", "description": "Audio length in seconds.", "example": 253 }, "image": { "type": "string", "description": "High resolution image url of this custom audio.", "example": "https://cdn-images-1.listennotes.com/playlist/image/6907e8ff6b6c45df94cc059753f369cc.JPEG" }, "thumbnail": { "type": "string", "description": "Low resolution image url of this custom audio.", "example": "https://d3sv2eduhewoas.cloudfront.net/playlist/image/48477deae02649d7ab9d3f1b3966af38.JPEG" }, "pub_date_ms": { "type": "integer", "description": "Published date (in milliseconds) of this custom audio.\nFor now, it's the same as **added_at_ms** of this playlist item.\n", "example": 1595567028133 } }, "description": "A custom audio in a playlist, which is a type of playlist item." }, "DeletedItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Episode id or podcast id.", "example": "96fc400171364e32897b25d84a8ed8ec" }, "title": { "type": "string", "description": "Episode title or podcast title.", "example": "This is a test episode" }, "status": { "type": "string", "description": "The status of this episode or podcast. For now, the only possible value is **deleted**.", "example": "deleted" }, "error": { "type": "string", "description": "Why this episode or podcast is deleted?", "example": "This episode is deleted from the podcast database, because..." } }, "description": "A deleted episode or podcast.\nAn episode or a podcast could be deleted from our podcast database.\nPossible reasons: 1) Podcast producers sometimes delete their old episodes. 2) Copyright issues.\n" }, "PlaylistItem": { "type": "object", "properties": { "id": { "type": "integer", "description": "Playlist item id.", "example": 23 }, "type": { "type": "string", "description": "The type of this playlist item.\nIf a playlist is **episode_list**, then an item could be either **episode** or **custom_audio**.\nIf it's **podcast_list**, then an item can only be **podcast**.\n", "example": "episode", "enum": [ "episode", "custom_audio", "podcast" ] }, "notes": { "type": "string", "description": "Notes for this item.", "example": "This is a good episode." }, "added_at_ms": { "type": "integer", "description": "Timestamp (in milliseconds) when this item is added.", "example": 1595567004958 }, "data": { "description": "Playlist item data", "oneOf": [ { "$ref": "#/components/schemas/EpisodeSimple" }, { "$ref": "#/components/schemas/PodcastSimple" }, { "$ref": "#/components/schemas/CustomAudio" }, { "$ref": "#/components/schemas/DeletedItem" } ] } }, "description": "An item in a playlist" }, "SearchResponse": { "type": "object", "properties": { "next_offset": { "type": "integer", "description": "Pass this value to the **offset** parameter to do pagination of search results.", "example": 10 }, "took": { "type": "number", "description": "The time it took to fetch these search results. In seconds.", "example": 0.093 }, "total": { "type": "integer", "description": "The total number of search results.", "example": 1989 }, "count": { "type": "integer", "description": "The number of search results in this page.", "example": 10 }, "results": { "type": "array", "description": "A list of search results.", "items": { "oneOf": [ { "$ref": "#/components/schemas/EpisodeSearchResult" }, { "$ref": "#/components/schemas/PodcastSearchResult" }, { "$ref": "#/components/schemas/CuratedListSearchResult" } ] } } } }, "TypeaheadResponse": { "required": [ "terms" ], "type": "object", "properties": { "terms": { "type": "array", "description": "Search term suggestions.", "example": [ "startup sales", "startup", "startups", "star wars" ], "items": { "type": "string" } }, "genres": { "type": "array", "description": "Genre suggestions. It'll show up when the **show_genres** parameter is *1*.", "items": { "$ref": "#/components/schemas/Genre" } }, "podcasts": { "type": "array", "description": "Podcast suggestions. It'll show up when the **show_podcasts** parameter is 1.", "items": { "$ref": "#/components/schemas/PodcastTypeaheadResult" } } } }, "BestPodcastsResponse": { "required": [ "has_next", "has_previous", "id", "listennotes_url", "name", "next_page_number", "page_number", "parent_id", "podcasts", "previous_page_number", "total" ], "type": "object", "properties": { "has_previous": { "type": "boolean" }, "name": { "type": "string", "description": "This genre's name.", "example": "Business News" }, "listennotes_url": { "$ref": "#/components/schemas/BestPodcastsLNUrlField" }, "previous_page_number": { "type": "integer", "example": 1 }, "page_number": { "type": "integer", "example": 2 }, "has_next": { "type": "boolean", "example": true }, "next_page_number": { "type": "integer", "example": 3 }, "parent_id": { "type": "integer", "description": "The id of parent genre.", "example": 93 }, "id": { "type": "integer", "description": "The id of this genre", "example": 95 }, "total": { "type": "integer", "example": 325 }, "podcasts": { "type": "array", "items": { "$ref": "#/components/schemas/PodcastSimple" } } } }, "GetEpisodesInBatchForm": { "required": [ "ids" ], "type": "object", "properties": { "ids": { "type": "string", "description": "Comma-separated list of episode ids.", "example": "c577d55b2b2b483c969fae3ceb58e362,0f34a9099579490993eec9e8c8cebb82" } } }, "GetEpisodesInBatchResponse": { "required": [ "episodes" ], "type": "object", "properties": { "episodes": { "type": "array", "items": { "$ref": "#/components/schemas/EpisodeSimple" } } } }, "GetPodcastsInBatchForm": { "type": "object", "properties": { "ids": { "type": "string", "description": "Comma-separated list of podcast ids.", "example": "3302bc71139541baa46ecb27dbf6071a,68faf62be97149c280ebcc25178aa731,37589a3e121e40debe4cef3d9638932a,9cf19c590ff0484d97b18b329fed0c6a" }, "rsses": { "type": "string", "description": "Comma-separated rss urls.", "example": "https://rss.art19.com/recode-decode,https://rss.art19.com/the-daily,https://www.npr.org/rss/podcast.php?id=510331,https://www.npr.org/rss/podcast.php?id=510331" }, "itunes_ids": { "type": "string", "description": "Comma-separated itunes ids.", "example": "1457514703,1386234384,659155419" }, "show_latest_episodes": { "type": "integer", "description": "Whether or not to fetch up to 10 latest episodes from these podcasts, sorted by pub_date. 1 is yes, and 0 is no.\n", "example": 1, "default": 0, "enum": [ 0, 1 ] }, "next_episode_pub_date": { "type": "integer", "description": "For latest 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.\n", "example": 1557394247000 } } }, "GetPodcastsInBatchResponse": { "required": [ "podcasts" ], "type": "object", "properties": { "podcasts": { "type": "array", "items": { "$ref": "#/components/schemas/PodcastSimple" } }, "latest_episodes": { "type": "array", "description": "Up to 10 latest episodes from these podcasts, sorted by **pub_date**. This field shows up only when **show_latest_episodes** is 1.\n", "items": { "$ref": "#/components/schemas/EpisodeSimple" } } } }, "GetGenresResponse": { "required": [ "genres" ], "type": "object", "properties": { "genres": { "type": "array", "items": { "$ref": "#/components/schemas/Genre" } } } }, "GetRegionsResponse": { "required": [ "regions" ], "type": "object", "properties": { "regions": { "type": "object", "example": { "de": "Germany", "us": "United States", "au": "Australia", "ua": "Ukraine" } } } }, "GetLanguagesResponse": { "required": [ "languages" ], "type": "object", "properties": { "languages": { "type": "array", "example": [ "Any language", "Afar", "Abkhazian", "Afrikaans", "Akan", "Albanian", "Arabic", "Azerbaijani", "Bambara", "Bashkir", "Basque", "Belarusian", "Bulgarian", "Catalan", "Chamorro", "Chinese", "Croatian", "Czech", "Danish", "Dutch", "English", "Estonian", "Faeroese", "Finnish", "French", "Gaelic", "Galician", "German", "Greek" ], "items": { "type": "string" } } } }, "GetCuratedPodcastsResponse": { "required": [ "curated_lists", "has_next", "has_previous", "next_page_number", "page_number", "previous_page_number", "total" ], "type": "object", "properties": { "has_previous": { "type": "boolean", "example": true }, "previous_page_number": { "type": "integer", "example": 1 }, "page_number": { "type": "integer", "example": 2 }, "next_page_number": { "type": "integer", "example": 3 }, "has_next": { "type": "boolean", "example": true }, "total": { "type": "integer", "example": 25 }, "curated_lists": { "type": "array", "items": { "$ref": "#/components/schemas/CuratedListSimple" } } } }, "GetPodcastRecommendationsResponse": { "required": [ "recommendations" ], "type": "object", "properties": { "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/PodcastSimple" } } } }, "GetEpisodeRecommendationsResponse": { "required": [ "recommendations" ], "type": "object", "properties": { "recommendations": { "type": "array", "items": { "$ref": "#/components/schemas/EpisodeSimple" } } } }, "SubmitPodcastForm": { "required": [ "rss" ], "type": "object", "properties": { "rss": { "type": "string", "description": "A valid podcast rss url.", "example": "https://feeds.megaphone.fm/committed" }, "email": { "type": "string", "description": "A valid email address. If **email** is specified, then we'll notify this email address once the podcast is accepted.", "example": "hello@example.com" } } }, "DeletePodcastResponse": { "required": [ "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "The status of this podcast deletion request.", "example": "deleted", "enum": [ "deleted", "in review" ] } } }, "SubmitPodcastResponse": { "required": [ "podcast", "status" ], "type": "object", "properties": { "status": { "type": "string", "description": "The status of this submission.", "example": "found", "enum": [ "found", "in review" ] }, "podcast": { "$ref": "#/components/schemas/PodcastMinimum" } } }, "PlaylistResponse": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/PlaylistIdField" }, "name": { "$ref": "#/components/schemas/PlaylistNameField" }, "description": { "$ref": "#/components/schemas/PlaylistDescriptionField" }, "image": { "$ref": "#/components/schemas/PlaylistImageField" }, "thumbnail": { "$ref": "#/components/schemas/PlaylistThumbnailField" }, "listennotes_url": { "$ref": "#/components/schemas/PlaylistListennotesUrlField" }, "visibility": { "$ref": "#/components/schemas/PlaylistVisibilityField" }, "last_timestamp_ms": { "$ref": "#/components/schemas/PlaylistLastTimestampMsField" }, "total": { "type": "integer", "description": "Total number of items in this playlist.", "example": 325 }, "type": { "type": "string", "description": "The type of this playlist, which should be either **episode_list** or **podcast_list**.\n", "example": "episode_list", "enum": [ "episode_list", "podcast_list" ] }, "items": { "type": "array", "description": "A list of playlist items.", "items": { "$ref": "#/components/schemas/PlaylistItem" } } } }, "PlaylistsResponse": { "type": "object", "properties": { "previous_page_number": { "type": "integer", "example": 1 }, "page_number": { "type": "integer", "example": 2 }, "has_next": { "type": "boolean", "example": true }, "has_previous": { "type": "boolean", "example": true }, "next_page_number": { "type": "integer", "example": 3 }, "total": { "type": "integer", "example": 325 }, "playlists": { "type": "array", "items": { "$ref": "#/components/schemas/PlaylistsResponse_playlists" } } } }, "PodcastLookingForField": { "type": "object", "properties": { "cohosts": { "type": "boolean", "description": "Whether this podcast is looking for cohosts.", "example": true }, "cross_promotion": { "type": "boolean", "description": "Whether this podcast is looking for cross promotion opportunities with other podcasts.", "example": true }, "sponsors": { "type": "boolean", "description": "Whether this podcast is looking for sponsors.", "example": true }, "guests": { "type": "boolean", "description": "Whether this podcast is looking for guests.", "example": true } } }, "PodcastExtraField": { "type": "object", "properties": { "youtube_url": { "type": "string", "description": "YouTube url affiliated with this podcast", "example": "https://www.youtube.com/sw7x7" }, "facebook_handle": { "type": "string", "description": "Facebook username affiliated with this podcast", "example": "sw7x7" }, "instagram_handle": { "type": "string", "description": "Instagram username affiliated with this podcast", "example": "sw7x7" }, "twitter_handle": { "type": "string", "description": "Twitter username affiliated with this podcast", "example": "SW7x7podcast" }, "wechat_handle": { "type": "string", "description": "WeChat username affiliated with this podcast" }, "patreon_handle": { "type": "string", "description": "Patreon username affiliated with this podcast", "example": "sw7x7" }, "google_url": { "type": "string", "description": "Google Podcasts url for this podcast", "example": "https://play.google.com/music/listen?u=0#/ps/I7gdcrqcmvhfnhh2cyqkcg32tkq" }, "linkedin_url": { "type": "string", "description": "LinkedIn url affiliated with this podcast" }, "spotify_url": { "type": "string", "description": "Spotify url for this podcast", "example": "https://open.spotify.com/show/2rQJUP9Y3HxemiW3JHt9WV" }, "url1": { "type": "string", "description": "Url affiliated with this podcast" }, "url2": { "type": "string", "description": "Url affiliated with this podcast" }, "url3": { "type": "string", "description": "Url affiliated with this podcast" } } }, "AudioField": { "type": "string", "description": "Audio url of this episode, which can be played directly.", "example": "https://www.listennotes.com/e/p/11b34041e804491b9704d11f283c74de/" }, "LinkField": { "type": "string", "description": "Web link of this episode.", "example": "https://www.npr.org/2020/01/22/798532179/soleimanis-iran" }, "TranscriptField": { "type": "string", "description": "The transcript of this episode, in plain text (with the newline character \\n). If there's not transcript, it is null. This field is available only in the PRO/ENTERPRISE plan.", "example": "00:00:07 Welcome to this podcast...\n" }, "WebsiteField": { "type": "string", "description": "Website url of this podcast.", "example": "http://sw7x7.com/" }, "IsClaimedField": { "type": "boolean", "description": "Whether this podcast is claimed by its producer on [ListenNotes.com](https://www.ListenNotes.com).", "example": true }, "PodcastTypeField": { "type": "string", "description": "The type of this podcast - episodic or serial.", "example": "episodic", "enum": [ "episodic", "serial" ] }, "LanguageField": { "type": "string", "description": "The language of this podcast. You can get all supported languages from `GET /languages`.", "example": "English" }, "CountryField": { "type": "string", "description": "The country where this podcast is produced.", "example": "United States" }, "PublisherField": { "type": "string", "description": "Podcast publisher name.", "example": "Planet Broadcasting" }, "MaybeAudioInvalidField": { "type": "boolean", "description": "Whether or not this episode's audio is invalid. Podcasters may delete the original audio.", "example": false }, "AudioLengthSecField": { "type": "integer", "description": "Audio length of this episode. In seconds.", "example": 567 }, "TotalEpisodesField": { "type": "integer", "description": "Total number of episodes in this podcast.", "example": 324 }, "ImageField": { "type": "string", "description": "Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's\na high resolution image (1400x1400). If you are using FREE plan, then it's the same as **thumbnail**,\nlow resolution image (300x300).\n", "example": "https://cdn-images-1.listennotes.com/podcasts/exponent-ben-thompson-james-allworth-OaJSjb4xQv3.1400x1400.jpg" }, "ThumbnailField": { "type": "string", "description": "Thumbnail image url for this podcast's artwork (300x300).", "example": "https://cdn-images-1.listennotes.com/podcasts/exponent-ben-thompson-james-allworth-OaJSjb4xQv3.300x300.jpg" }, "EpisodeImageField": { "type": "string", "description": "Image url for this episode.\nIf an episode doesn't have its own image, then this field would be the url of the podcast artwork image.\nIf you are using PRO/ENTERPRISE plan, then it's\na high resolution image (1400x1400). If you are using FREE plan, then it's the same as **thumbnail**,\nlow resolution image (300x300).\n", "example": "https://cdn-images-1.listennotes.com/podcasts/exponent-ben-thompson-james-allworth-OaJSjb4xQv3.1400x1400.jpg" }, "EpisodeThumbnailField": { "type": "string", "description": "Thumbnail image (300x300) url for this episode.\nIf an episode doesn't have its own image, then this field would be the url of the podcast artwork thumbnail image.\n", "example": "https://cdn-images-1.listennotes.com/podcasts/exponent-ben-thompson-james-allworth-OaJSjb4xQv3.300x300.jpg" }, "RssField": { "type": "string", "description": "RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan.", "example": "https://sw7x7.libsyn.com/rss" }, "EmailField": { "type": "string", "description": "The email of this podcast's producer. This field is available only in the PRO/ENTERPRISE plan.", "example": "hello@example.com" }, "iTunesIdField": { "type": "integer", "description": "iTunes id for this podcast.", "example": 896354638 }, "EpisodePubDateMsField": { "type": "integer", "description": "Published date for this episode. In millisecond.", "example": 1474873200000 }, "CuratedPubDateMsField": { "type": "integer", "description": "Published date of this curated list. In milliseconds.", "example": 1556843484301 }, "LatestPubDateMsField": { "type": "integer", "description": "The published date of the latest episode of this podcast. In milliseconds", "example": 1557499770000 }, "EarliestPubDateMsField": { "type": "integer", "description": "The published date of the oldest episode of this podcast. In milliseconds", "example": 1470667902000 }, "NextEpisodePubDateField": { "type": "integer", "description": "Passed to the **next_episode_pub_date** parameter of `GET /podcasts/{id}` to paginate through episodes of that podcast.", "example": 1470667902000 }, "PodcastNameField": { "type": "string", "description": "Podcast name.", "example": "Star Wars 7x7 | Star Wars News, Interviews, and More!" }, "EpisodeNameField": { "type": "string", "description": "Episode name.", "example": "Celebration Recap, Jason Fry and Christian Blauvelt Interviews – SWBW #101" }, "CuratedNameField": { "type": "string", "description": "Curated list name.", "example": "7 Bookish Podcasts for Avid Readers On the Go" }, "EpisodeIdField": { "type": "string", "description": "Episode id.", "example": "4d82e50314174754a3b603912448e812" }, "PodcastIdField": { "type": "string", "description": "Podcast id.", "example": "4d3fe717742d4963a85562e9f84d8c79" }, "CuratedIdField": { "type": "string", "description": "Curated list id.", "example": "Vb017Sx3l8F" }, "ExplicitField": { "type": "boolean", "description": "Whether this podcast contains explicit language.", "example": false }, "GenreIdsField": { "type": "array", "description": "Array of genre ids.", "example": [ 138, 86, 160, 68, 82, 100, 101 ], "items": { "type": "integer", "description": "Genre ids." } }, "EpisodeLNUrlField": { "type": "string", "description": "The url of this episode on [ListenNotes.com](https://www.ListenNotes.com).", "example": "https://www.listennotes.com/e/4d82e50314174754a3b603912448e812/" }, "EpisodeLNEditUrlField": { "type": "string", "description": "Edit url of this episode where you can update the audio url if you find the audio is broken.", "example": "https://www.listennotes.com/e/11b34041e804491b9704d11f283c74de/#edit" }, "PodcastLNUrlField": { "type": "string", "description": "The url of this podcast on [ListenNotes.com](https://www.ListenNotes.com).", "example": "https://www.listennotes.com/c/4d3fe717742d4963a85562e9f84d8c79/" }, "CuratedLNUrlField": { "type": "string", "description": "The url of this curated list on [ListenNotes.com](https://www.ListenNotes.com).", "example": "https://www.listennotes.com/curated-podcasts/7-bookish-podcasts-for-avid-readers-on-H2r-TCWai8K/" }, "BestPodcastsLNUrlField": { "type": "string", "description": "Url of the list of best podcasts on [ListenNotes.com](https://www.ListenNotes.com).", "example": "https://www.listennotes.com/best-business-news-podcasts-95/" }, "PublisherHighlightedField": { "type": "string", "description": "Highlighted segment of this podcast's publisher name.", "example": "Star Wars Daily, by Allen Voivod" }, "PublisherOriginalField": { "type": "string", "description": "Plain text of this podcast's publisher name.", "example": "Star Wars Daily, by Allen Voivod" }, "PodcastTitleHighlightedField": { "type": "string", "description": "Highlighted segment of podcast name.", "example": "Star Wars 7x7 | Star Wars News, Interviews, and More!" }, "PodcastTitleOriginalField": { "type": "string", "description": "Plain text of podcast name.", "example": "Star Wars 7x7 | Star Wars News, Interviews, and More!" }, "EpisodeDescriptionField": { "type": "string", "description": "Html of this episode's full description", "example": "

Disney chief Bob Iger shared news about Star Wars movies in 2020 and beyond, but some media outlets gave conflicting reports about it. Here's the real scoop. Punch it!

***We’re listener supported! Go to http://Patreon.com/sw7x7 to donate to the Star Wars 7x7 podcast, and you’ll get some fabulous rewards for your pledge.*** 

Check out SW7x7.com for full Star Wars 7x7 show notes and links, and to comment on any of the content of this episode! If you like what you've heard, please leave us a rating or review on iTunes or Stitcher, which will also help more people discover this Star Wars podcast.

Don't forget to join the Star Wars 7x7 fun on Facebook at Facebook.com/SW7x7, and follow the breaking news Twitter feed at Twitter.com/SW7x7Podcast. We're also on Pinterest and Instagram as \"SW7x7\" too, and we'd love to connect with you there!

\n" }, "PodcastDescriptionField": { "type": "string", "description": "Html of this episode's full description", "example": "

The Star Wars 7x7 Podcast is Rebel-rousing fun for everyday Jedi, between 7 and 14 minutes a day, 7 days a week. Join host Allen Voivod for Star Wars news, history, interviews, trivia, and deep dives into the Star Wars story as told in movies, books, comics, games, cartoons, and more. Subscribe now for your daily dose of Star Wars joy. It's destiny unleashed!

" }, "CuratedDescriptionField": { "type": "string", "description": "This curated list's description.", "example": "Commuting to work is always better when you have a great new podcast to listen to, and this year, we have discovered some of our favorite podcasts yet for readers and book-lovers. These podcasts for readers entertain us and provide no shortage of new book recommendations too." }, "CuratedSourceUrlField": { "type": "string", "description": "Url of the source of this curated list.", "example": "https://parade.com/718913/ashley_johnson/7-bookish-podcasts-for-avid-readers-on-the-go/" }, "CuratedSourceDomainField": { "type": "string", "description": "The domain name of the source of this curated list.", "example": "parade.com" }, "CuratedTotalPodcastsField": { "type": "integer", "description": "The total number of podcasts in this curated list.", "example": 25 }, "PlaylistIdField": { "type": "string", "description": "A 11-character playlist id.", "example": "m1pe7z60bsw" }, "PlaylistNameField": { "type": "string", "description": "Playlist name.", "example": "My podcast playlist" }, "PlaylistDescriptionField": { "type": "string", "description": "Playlist description.", "example": "A curated playlist of podcasts about podcasting." }, "PlaylistImageField": { "type": "string", "description": "High resolution image url of the playlist.", "example": "https://cdn-images-1.listennotes.com/playlist/image/6907e8ff6b6c45df94cc059753f369cc.JPEG" }, "PlaylistThumbnailField": { "type": "string", "description": "Low resolution image url of the playlist.", "example": "https://d3sv2eduhewoas.cloudfront.net/playlist/image/48477deae02649d7ab9d3f1b3966af38.JPEG" }, "PlaylistListennotesUrlField": { "type": "string", "description": "The url of this playlist on ListenNotes.com.", "example": "https://www.listennotes.com/listen/podcasts-about-podcasting-m1pe7z60bsw/?display=episode" }, "PlaylistVisibilityField": { "type": "string", "description": "Visibility of this playlist.", "example": "public", "enum": [ "public", "unlisted", "private" ] }, "PlaylistLastTimestampMsField": { "type": "integer", "description": "Passed to the **last_timestamp_ms** parameter of `GET /playlists/{id}` to paginate through items of that playlist.\n", "example": 1595641092907 }, "ListenScoreField": { "type": "integer", "description": "The estimated popularity score of a podcast compared to all other rss-based public podcasts in the world on a scale from 0 to 100.\nIf the score is not available, it'll be null. Learn more at listennotes.com/listen-score\n", "example": 81 }, "ListenScoreGlobalRankField": { "type": "string", "description": "The estimated popularity ranking of a podcast compared to all other rss-based public podcasts in the world.\nFor example, if the value is 0.5%, then this podcast is one of the top 0.5% most popular shows out of all podcasts globally, ranked by Listen Score.\nIf the ranking is not available, it'll be null. Learn more at listennotes.com/listen-score\n", "example": "0.5%" }, "EpisodeSearchResult_podcast": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/PodcastIdField" }, "genre_ids": { "$ref": "#/components/schemas/GenreIdsField" }, "listennotes_url": { "$ref": "#/components/schemas/PodcastLNUrlField" }, "title_highlighted": { "$ref": "#/components/schemas/PodcastTitleHighlightedField" }, "title_original": { "$ref": "#/components/schemas/PodcastTitleOriginalField" }, "publisher_highlighted": { "$ref": "#/components/schemas/PublisherHighlightedField" }, "publisher_original": { "$ref": "#/components/schemas/PublisherOriginalField" }, "image": { "$ref": "#/components/schemas/ImageField" }, "thumbnail": { "$ref": "#/components/schemas/ThumbnailField" }, "listen_score": { "$ref": "#/components/schemas/ListenScoreField" }, "listen_score_global_rank": { "$ref": "#/components/schemas/ListenScoreGlobalRankField" } }, "description": "The podcast that this episode belongs to." }, "PlaylistsResponse_playlists": { "type": "object", "properties": { "episode_count": { "type": "integer", "description": "The number of episodes (including custom audio) in this playlist.", "example": 23 }, "podcast_count": { "type": "integer", "description": "The number of podcasts in this playlist.", "example": 10 }, "id": { "$ref": "#/components/schemas/PlaylistIdField" }, "name": { "$ref": "#/components/schemas/PlaylistNameField" }, "description": { "$ref": "#/components/schemas/PlaylistDescriptionField" }, "image": { "$ref": "#/components/schemas/PlaylistImageField" }, "thumbnail": { "$ref": "#/components/schemas/PlaylistThumbnailField" }, "listennotes_url": { "$ref": "#/components/schemas/PlaylistListennotesUrlField" }, "visibility": { "$ref": "#/components/schemas/PlaylistVisibilityField" }, "last_timestamp_ms": { "$ref": "#/components/schemas/PlaylistLastTimestampMsField" } }, "description": "A playlist" } }, "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." }, "Unauthorized": { "description": "Wrong api key or your account is suspended." }, "TooManyRequests": { "description": "You are using FREE plan and you exceed the quota limit." }, "ServerError": { "description": "Something wrong on our end (Unexpected server errors)." } }, "parameters": { "queryParam": { "name": "q", "in": "query", "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", "required": true, "style": "form", "explode": true, "schema": { "type": "string", "example": "star wars" } }, "apiKeyParam": { "name": "X-ListenAPI-Key", "in": "header", "description": "Get API Key on listennotes.com/api", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, "safeModeParam": { "name": "safe_mode", "in": "query", "description": "Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.", "required": false, "style": "form", "explode": true, "schema": { "type": "integer", "example": 0, "default": 0, "enum": [ 0, 1 ] } }, "genreIdParam": { "name": "genre_id", "in": "query", "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.", "required": false, "style": "form", "explode": true, "schema": { "type": "string", "example": "93" } } }, "headers": { "X-ListenAPI-FreeQuota": { "description": "Free quotas of API requests included in your api plan.", "style": "simple", "explode": false, "schema": { "type": "integer", "example": 25000 } }, "X-ListenAPI-Usage": { "description": "The number of API requests that you've used in current billing cycle.", "style": "simple", "explode": false, "schema": { "type": "integer", "example": 19231 } }, "X-listenAPI-Latency-Seconds": { "description": "Latency for this api call, in seconds.", "style": "simple", "explode": false, "schema": { "type": "number", "example": 0.056 } }, "X-ListenAPI-NextBillingDate": { "description": "The timestamp for the start of next billing cycle. In ISO 8601 format.", "style": "simple", "explode": false, "schema": { "type": "string", "format": "date-time", "example": "2020-04-26T17:27:33.110Z" } } } } }