Full-text search
GET {{baseUrl}}/search?q=<string>&sort_by_date=0&type=episode&offset=0&len_min=0&len_max=<integer>&episode_count_min=<integer>&episode_count_max=<integer>&update_freq_min=<integer>&update_freq_max=<integer>&genre_ids=<string>&published_before=<integer>&published_after=0&only_in=title,description,author,audio&language=<string>®ion=<string>&ocid=<string>&ncid=<string>&safe_mode=0&unique_podcasts=0&interviews_only=0&sponsored_only=0&page_size=10
Full-text search on episodes, podcasts, or curated lists of podcasts.
Use the offset parameter to paginate through search results.
The FREE plan allows to see up to 30 search results (or offset < 30) per query.
The PRO plan allows to see up to 300 search results (or offset < 300) per query.
The ENTERPRISE plan allows to see up to 10,000 search results (or offset < 10000) per query.
Request Params
| Key | Datatype | Required | Description |
|---|---|---|---|
q | string | (Required) 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. | |
sort_by_date | number | Sort by date or not? If 0, then sort by relevance. If 1, then sort by date. | |
type | string | What type of contents do you want to search for? | |
offset | number | Offset for search results, for pagination. You'll use next_offset from response for this parameter. | |
len_min | number | Minimum audio length in minutes. Applicable only when type parameter is episode or podcast. | |
| If type parameter is episode, it's for audio length of an episode. | |||
| If type parameter is podcast, it's for average audio length of all episodes in a podcast. | |||
len_max | string | Maximum audio length in minutes. Applicable only when type parameter is episode or podcast. | |
| If type parameter is episode, it's for audio length of an episode. | |||
| If type parameter is podcast, it's for average audio length of all episodes in a podcast. | |||
episode_count_min | string | Minimum number of episodes. Applicable only when type parameter is podcast. | |
episode_count_max | string | Maximum number of episodes. Applicable only when type parameter is podcast. | |
update_freq_min | string | Minimum update frequency in hours (how frequently does a podcast release a new episode). For example, if you want to find "weekly" podcasts, then you can set update_freq_min=144 hours (or 6 days) and update_freq_max=192 hours (or 8 days). Applicable only when type parameter is podcast. | |
update_freq_max | string | Maximum update frequency in hours (how frequently does a podcast release a new episode). For example, if you want to find "weekly" podcasts, then you can set update_freq_min=144 hours (or 6 days) and update_freq_max=192 hours (or 8 days). Applicable only when type parameter is podcast. | |
genre_ids | string | A comma-delimited string of a list of genre ids. If not specified, then all genres are included. You can find the id and the name of all genres from GET /genres. It works only when type is episode or podcast. | |
published_before | string | 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. | |
published_after | number | 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. | |
only_in | string | A comma-delimited string to search only in specific fields. Allowed values are title, description, author, and audio. If not specified, then search every fields. | |
language | string | Limit search results to a specific language. If not specified, it'll be any language. You can get a list of supported languages from GET /languages. It works only when type is episode or podcast. | |
region | string | Limit search results to a specific region (e.g., us, gb, in...). If not specified, it'll be any region. You can get the supported country codes from GET /regions. It works only when type is episode or podcast. | |
ocid | string | A comma-delimited string of podcast ids (up to 5 podcasts) - you can get a podcast id from the podcast_id field in response. This parameter is to limit search results from only a few specific podcasts. It works only when type is episode. | |
ncid | string | A comma-delimited string of podcast ids (up to 5 podcasts) - you can get a podcast id from the podcast_id field in response. This parameter is to exclude search results of a few specific podcasts. It works only when type is episode. | |
safe_mode | number | Whether or not to exclude podcasts/episodes with explicit language. 1 is yes and 0 is no. It works only when type is episode or podcast. | |
unique_podcasts | number | Whether or not to keep only one episode per podcast in search results. 1 is yes and 0 is no. It works only when type is episode. | |
interviews_only | number | Whether or not to keep only podcasts that have guest interviews in search results. 1 is yes and 0 is no. It works only when type is podcast. | |
| This parameter is available only in the PRO/ENTERPRISE plan. | |||
sponsored_only | number | Whether or not to keep only podcasts that have sponsors in search results. 1 is yes and 0 is no. It works only when type is podcast. | |
| This parameter is available only in the PRO/ENTERPRISE plan. | |||
page_size | number | The maximum number of search results per page. A valid value should be an integer between 1 and 10 (inclusive). | |
HEADERS
| Key | Datatype | Required | Description |
|---|---|---|---|
X-ListenAPI-Key | string | (Required) Get API Key on listennotes.com/api | |
Accept | string |
RESPONSES
status: OK
{"next_offset":"\u003cinteger\u003e","took":"\u003cnumber\u003e","total":"\u003cinteger\u003e","count":"\u003cinteger\u003e","results":[{"audio":"\u003cstring\u003e","audio_length_sec":"\u003cinteger\u003e","rss":"\u003cstring\u003e","description_highlighted":"\u003cstring\u003e","description_original":"\u003cstring\u003e","title_highlighted":"\u003cstring\u003e","title_original":"\u003cstring\u003e","transcripts_highlighted":["\u003cstring\u003e","\u003cstring\u003e"],"image":"\u003cstring\u003e","thumbnail":"\u003cstring\u003e","itunes_id":"\u003cinteger\u003e","pub_date_ms":"\u003cinteger\u003e","id":"\u003cstring\u003e","listennotes_url":"\u003cstring\u003e","explicit_content":"\u003cboolean\u003e","link":"\u003cstring\u003e","podcast":{"id":"\u003cstring\u003e","genre_ids":["\u003cinteger\u003e","\u003cinteger\u003e"],"listennotes_url":"\u003cstring\u003e","title_highlighted":"\u003cstring\u003e","title_original":"\u003cstring\u003e","publisher_highlighted":"\u003cstring\u003e","publisher_original":"\u003cstring\u003e","image":"\u003cstring\u003e","thumbnail":"\u003cstring\u003e","listen_score":"\u003cinteger\u003e","listen_score_global_rank":"\u003cstring\u003e"}},{"audio":"\u003cstring\u003e","audio_length_sec":"\u003cinteger\u003e","rss":"\u003cstring\u003e","description_highlighted":"\u003cstring\u003e","description_original":"\u003cstring\u003e","title_highlighted":"\u003cstring\u003e","title_original":"\u003cstring\u003e","transcripts_highlighted":["\u003cstring\u003e","\u003cstring\u003e"],"image":"\u003cstring\u003e","thumbnail":"\u003cstring\u003e","itunes_id":"\u003cinteger\u003e","pub_date_ms":"\u003cinteger\u003e","id":"\u003cstring\u003e","listennotes_url":"\u003cstring\u003e","explicit_content":"\u003cboolean\u003e","link":"\u003cstring\u003e","podcast":{"id":"\u003cstring\u003e","genre_ids":["\u003cinteger\u003e","\u003cinteger\u003e"],"listennotes_url":"\u003cstring\u003e","title_highlighted":"\u003cstring\u003e","title_original":"\u003cstring\u003e","publisher_highlighted":"\u003cstring\u003e","publisher_original":"\u003cstring\u003e","image":"\u003cstring\u003e","thumbnail":"\u003cstring\u003e","listen_score":"\u003cinteger\u003e","listen_score_global_rank":"\u003cstring\u003e"}}]}