listennotes
Module listennotes
API
Definitions
ballerinax/listennotes Ballerina library
Overview
The Listen Notes connector lets Ballerina applications search and explore podcasts and episodes, and manage playlists, through the Listen API. It supports version 2.0 of the API.
Key features
- Search podcasts, episodes and curated lists, with typeahead suggestions, trending searches and related terms
- Browse the podcast directory by genre, region and language, and fetch curated lists of podcasts
- Retrieve detailed metadata for podcasts and episodes, individually or in batches
- Get podcast and episode recommendations and look up audience demographics
- Create and manage playlists of episodes and podcasts, and submit new podcasts to the database
Setup guide
To use the connector, you need a Listen API key.
-
Create an account at Listen Notes and sign in.
-
Open the API dashboard and choose a plan. A free plan is available for trying out the API.
-
Copy your API key from the dashboard. Team keys act as the API admin.
Quickstart
To use the Listen Notes connector in your Ballerina application, update the .bal file as follows:
Step 1: Import the module
import ballerinax/listennotes;
Step 2: Create a Config.toml file
apiKey = "<Listen API key>"
Step 3: Create a client
configurable string apiKey = ?; final listennotes:Client listenNotes = check new ({xListenAPIKey: apiKey});
Step 4: Invoke an operation
public function main() returns error? { listennotes:TrendingSearchesResponse _ = check listenNotes->getTrendingSearches(); }
Examples
The Listen Notes connector provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:
- Genre podcast report - Finds the best podcasts in a genre and lists the most recent episodes of each.
- Podcast playlist builder - Searches for episodes on a topic, collects them in a new playlist and reads the playlist back.
Clients
listennotes: Client
Simple & no-nonsense podcast search & directory API. Search all podcasts and episodes by people, places, or topics.
Constructor
Gets invoked to initialize the connector.
init (ApiKeysConfig apiKeyConfig, ConnectionConfig config, string serviceUrl)- apiKeyConfig ApiKeysConfig - API keys for authorization
- config ConnectionConfig {} - The configurations to be used when initializing the
connector
- serviceUrl string "https://listen-api.listennotes.com/api/v2" - URL of the target service
search
function search(map<string|string[]> headers, *SearchQueries queries) returns SearchResponse|errorFull-text search
Parameters
- queries *SearchQueries - Queries to be sent with the request
Return Type
- SearchResponse|error - OK
typeahead
function typeahead(map<string|string[]> headers, *TypeaheadQueries queries) returns TypeaheadResponse|errorTypeahead search
Parameters
- queries *TypeaheadQueries - Queries to be sent with the request
Return Type
- TypeaheadResponse|error - OK
searchEpisodeTitles
function searchEpisodeTitles(map<string|string[]> headers, *SearchEpisodeTitlesQueries queries) returns SearchEpisodeTitlesResponse|errorFind individual episodes by searching for their titles
Parameters
- queries *SearchEpisodeTitlesQueries - Queries to be sent with the request
Return Type
getTrendingSearches
function getTrendingSearches(map<string|string[]> headers) returns TrendingSearchesResponse|errorFetch trending search terms
Return Type
getRelatedSearches
function getRelatedSearches(map<string|string[]> headers, *GetRelatedSearchesQueries queries) returns RelatedSearchesResponse|errorFetch related search terms
Parameters
- queries *GetRelatedSearchesQueries - Queries to be sent with the request
Return Type
spellcheck
function spellcheck(map<string|string[]> headers, *SpellcheckQueries queries) returns SpellCheckResponse|errorSpell check on a search term
Parameters
- queries *SpellcheckQueries - Queries to be sent with the request
Return Type
- SpellCheckResponse|error - OK
getBestPodcasts
function getBestPodcasts(map<string|string[]> headers, *GetBestPodcastsQueries queries) returns BestPodcastsResponse|errorFetch a list of best podcasts by genre
Parameters
- queries *GetBestPodcastsQueries - Queries to be sent with the request
Return Type
getPodcastById
function getPodcastById(string id, map<string|string[]> headers, *GetPodcastByIdQueries queries) returns PodcastFull|errorFetch detailed meta data and episodes for a podcast by id
Parameters
- id string - Podcast id. You can get podcast id from using other endpoints, e.g.,
GET /search,GET /best_podcasts..
- queries *GetPodcastByIdQueries - Queries to be sent with the request
Return Type
- PodcastFull|error - OK
deletePodcastById
function deletePodcastById(string id, map<string|string[]> headers, *DeletePodcastByIdQueries queries) returns DeletePodcastResponse|errorRequest to delete a podcast
Parameters
- id string - Podcast id. You can get podcast id from using other endpoints, e.g.,
GET /search,GET /best_podcasts..
- queries *DeletePodcastByIdQueries - Queries to be sent with the request
Return Type
getEpisodeById
function getEpisodeById(string id, map<string|string[]> headers, *GetEpisodeByIdQueries queries) returns EpisodeFull|errorFetch detailed meta data for an episode by id
Parameters
- id string - id for a specific episode. You can get episode id from using other endpoints, e.g.,
GET /search..
- queries *GetEpisodeByIdQueries - Queries to be sent with the request
Return Type
- EpisodeFull|error - OK
getEpisodesInBatch
function getEpisodesInBatch(GetEpisodesInBatchForm payload, map<string|string[]> headers) returns GetEpisodesInBatchResponse|errorBatch fetch basic meta data for episodes
Parameters
- payload GetEpisodesInBatchForm - Episode IDs to fetch in a batch, with optional ranking and show notes options
Return Type
getPodcastsInBatch
function getPodcastsInBatch(GetPodcastsInBatchForm payload, map<string|string[]> headers) returns GetPodcastsInBatchResponse|errorBatch fetch basic meta data for podcasts
Parameters
- payload GetPodcastsInBatchForm - Podcast IDs or RSS feeds to fetch in a batch, with optional episode options
Return Type
getCuratedPodcastById
function getCuratedPodcastById(string id, map<string|string[]> headers) returns CuratedListFull|errorFetch a curated list of podcasts by id
Parameters
- id string - id for a specific curated list of podcasts. You can get the id from the response of
GET /search?type=curatedorGET /curated_podcasts
Return Type
- CuratedListFull|error - OK
getGenres
function getGenres(map<string|string[]> headers, *GetGenresQueries queries) returns GetGenresResponse|errorFetch a list of podcast genres
Parameters
- queries *GetGenresQueries - Queries to be sent with the request
Return Type
- GetGenresResponse|error - OK
getRegions
function getRegions(map<string|string[]> headers) returns GetRegionsResponse|errorFetch a list of supported countries/regions for best podcasts
Return Type
- GetRegionsResponse|error - OK
getLanguages
function getLanguages(map<string|string[]> headers) returns GetLanguagesResponse|errorFetch a list of supported languages for podcasts
Return Type
justListen
function justListen(map<string|string[]> headers) returns EpisodeSimple|errorFetch a random podcast episode
Return Type
- EpisodeSimple|error - OK
getCuratedPodcasts
function getCuratedPodcasts(map<string|string[]> headers, *GetCuratedPodcastsQueries queries) returns GetCuratedPodcastsResponse|errorFetch curated lists of podcasts
Parameters
- queries *GetCuratedPodcastsQueries - Queries to be sent with the request
Return Type
getPodcastRecommendations
function getPodcastRecommendations(string id, map<string|string[]> headers, *GetPodcastRecommendationsQueries queries) returns GetPodcastRecommendationsResponse|errorFetch recommendations for a podcast
Parameters
- id string - Podcast id
- queries *GetPodcastRecommendationsQueries - Queries to be sent with the request
Return Type
getEpisodeRecommendations
function getEpisodeRecommendations(string id, map<string|string[]> headers, *GetEpisodeRecommendationsQueries queries) returns GetEpisodeRecommendationsResponse|errorFetch recommendations for an episode
Parameters
- id string - Episode id
- queries *GetEpisodeRecommendationsQueries - Queries to be sent with the request
Return Type
submitPodcast
function submitPodcast(SubmitPodcastForm payload, map<string|string[]> headers) returns SubmitPodcastResponse|errorSubmit a podcast to Listen Notes database
Parameters
- payload SubmitPodcastForm - RSS feed URL and optional email of the podcast to submit
Return Type
refreshRss
Refresh RSS feed of a podcast
Parameters
- id string - Podcast id. You can get podcast id from using other endpoints, e.g.,
GET /search,GET /best_podcasts..
Return Type
- RefreshRssResponse|error - OK
getPlaylistById
function getPlaylistById(string id, map<string|string[]> headers, *GetPlaylistByIdQueries queries) returns PlaylistResponse|errorFetch a playlist's info and items (i.e., episodes or podcasts).
Parameters
- id string - Playlist id (always 11 characters, e.g., m1pe7z60bsw). You can get the podcast id from the url of a playlist, e.g., m1pe7z60bsw is the playlist id of listennotes.com/listen/podcasts-about-podcasting-m1pe7z60bsw
- queries *GetPlaylistByIdQueries - Queries to be sent with the request
Return Type
- PlaylistResponse|error - OK
updatePlaylist
function updatePlaylist(string id, UpdatePlaylistRequest payload, map<string|string[]> headers) returns PlaylistSummary|errorUpdate playlist metadata.
Parameters
- id string - 11-character playlist ID returned by the playlist endpoints
- payload UpdatePlaylistRequest - Updated playlist title, description, visibility and notes settings
Return Type
- PlaylistSummary|error - OK
deletePlaylist
function deletePlaylist(string id, map<string|string[]> headers) returns DeletePlaylistResponse|errorDelete a playlist.
Parameters
- id string - 11-character playlist ID returned by the playlist endpoints
Return Type
- DeletePlaylistResponse|error - The playlist and its saved items and notes have been deleted
getPlaylists
function getPlaylists(map<string|string[]> headers, *GetPlaylistsQueries queries) returns PlaylistsResponse|errorFetch a list of your playlists.
Parameters
- queries *GetPlaylistsQueries - Queries to be sent with the request
Return Type
- PlaylistsResponse|error - OK
createPlaylist
function createPlaylist(CreatePlaylistRequest payload, map<string|string[]> headers) returns PlaylistSummary|errorCreate a playlist.
Parameters
- payload CreatePlaylistRequest - Playlist details: title, type, visibility and description
Return Type
- PlaylistSummary|error - Created
addPlaylistItem
function addPlaylistItem(string id, AddPlaylistItemRequest payload, map<string|string[]> headers) returns PlaylistItem|errorAdd an episode or podcast to a playlist.
Parameters
- id string - 11-character playlist ID returned by the playlist endpoints
- payload AddPlaylistItemRequest - Episode or podcast to add to the playlist, with optional notes
Return Type
- PlaylistItem|error - Already present
updatePlaylistItemNotes
function updatePlaylistItemNotes(string id, int itemId, UpdatePlaylistItemNotesRequest payload, map<string|string[]> headers) returns PlaylistItem|errorUpdate notes for a playlist item.
Parameters
- id string - 11-character playlist ID returned by the playlist endpoints
- itemId int - Integer playlist-item ID returned by GET /playlists/{id} or the add-item endpoint, not a podcast or episode UUID
- payload UpdatePlaylistItemNotesRequest - Updated notes for the playlist item
Return Type
- PlaylistItem|error - OK
deletePlaylistItem
function deletePlaylistItem(string id, int itemId, map<string|string[]> headers) returns DeletePlaylistItemResponse|errorRemove an item from a playlist.
Parameters
- id string - 11-character playlist ID returned by the playlist endpoints
- itemId int - Integer playlist-item ID returned by GET /playlists/{id} or the add-item endpoint, not a podcast or episode UUID
Return Type
getPodcastAudience
function getPodcastAudience(string id, map<string|string[]> headers) returns PodcastAudienceResponse|errorFetch audience demographics for a podcast
Parameters
- id string - Podcast id
Return Type
getPodcastsByDomainName
function getPodcastsByDomainName(string domainName, map<string|string[]> headers, *GetPodcastsByDomainNameQueries queries) returns PodcastDomainResponse|errorFetch podcasts by a publisher's domain name
Parameters
- domainName string - A publisher's domain name, e.g., nytimes.com, wondery.com, npr.org..
- queries *GetPodcastsByDomainNameQueries - Queries to be sent with the request
Return Type
Records
listennotes: AddPlaylistItemRequest
Fields
- episodeId? string - Episode UUID. Supply this or podcast_id. An empty unused field is ignored
- notes? string - Plain-text notes. An empty string clears existing notes
- podcastId? string - Podcast UUID. Supply this or episode_id. An empty unused field is ignored
listennotes: ApiKeysConfig
Provides API key configurations needed when communicating with a remote HTTP endpoint.
Fields
- xListenAPIKey string - Get your API key at https://www.listennotes.com/api/dashboard/. Team keys act as the API admin.
listennotes: BestPodcastsResponse
Fields
- total int -
- pageNumber int -
- podcasts PodcastSimple[] -
- hasPrevious boolean -
- parentId int - The id of parent genre
- nextPageNumber int -
- name string - This genre's name
- hasNext boolean -
- id int - The id of this genre
- listennotesUrl BestPodcastsLNUrlField -
- previousPageNumber int -
listennotes: ConnectionConfig
Provides a set of configurations for controlling the behaviours when communicating with a remote HTTP endpoint.
Fields
- httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client
- http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol
- http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol
- timeout decimal(default 30) - The maximum time to wait (in seconds) for a response before closing the connection
- forwarded string(default "disable") - The choice of setting
forwarded/x-forwardedheader
- followRedirects? FollowRedirects - Configurations associated with Redirection
- poolConfig? PoolConfiguration - Configurations associated with request pooling
- cache CacheConfig(default {}) - HTTP caching related configurations
- compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (
accept-encoding) header
- circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker
- retryConfig? RetryConfig - Configurations associated with retrying
- cookieConfig? CookieConfig - Configurations associated with cookies
- responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits
- secureSocket? ClientSecureSocket - SSL/TLS-related options
- proxy? ProxyConfig - Proxy server related options
- socketConfig ClientSocketConfig(default {}) - Provides settings related to client socket configuration
- validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default
- laxDataBinding boolean(default true) - Enables relaxed data binding on the client side. When enabled,
nilvalues are treated as optional, and absent fields are handled asnilabletypes. Enabled by default.
listennotes: CreatePlaylistRequest
Fields
- visibility? "public"|"unlisted"|"private" - Who can view the playlist. Creation defaults to public
- name string - Nonblank playlist name. Leading/trailing whitespace is trimmed; rss is reserved (case insensitive)
- description? string - Playlist description. An empty string clears it
- 'type "episode_list"|"podcast_list" (default "episode_list") - The saved default view. Changing it preserves all episodes and podcasts in the playlist
listennotes: CuratedListFull
Fields
- total? CuratedTotalPodcastsField - The total number of podcasts in this curated list
- podcasts? PodcastSimple[] - Complete meta data of all podcasts in this curated list
- sourceDomain? CuratedSourceDomainField -
- description? CuratedDescriptionField - This curated list's description
- id? CuratedIdField - Curated list id, which can be used to further fetch detailed curated list metadata via
GET /curated_podcasts/{id}
- title? CuratedNameField - Curated list name
- pubDateMs? CuratedPubDateMsField -
- sourceUrl? CuratedSourceUrlField -
- listennotesUrl? CuratedLNUrlField -
listennotes: CuratedListSearchResult
When type is curated
Fields
- titleHighlighted? string - Highlighted segment of this curated list's title
- titleOriginal? string - Plain text of this curated list's title
- total? CuratedTotalPodcastsField - The total number of podcasts in this curated list
- podcasts? PodcastMinimum[] - Up to 5 podcasts in this curated list
- descriptionOriginal? string - Plain text of this curated list's description
- descriptionHighlighted? string - Highlighted segment of this curated list's description
- sourceDomain? CuratedSourceDomainField - The domain name of the source of this curated list
- id? CuratedIdField - Curated list id, which can be used to further fetch detailed curated list metadata via
GET /curated_podcasts/{id}
- pubDateMs? CuratedPubDateMsField - Published date of this curated list, as an Epoch Unix timestamp in milliseconds
- listennotesUrl? CuratedLNUrlField - The url of this curated list on ListenNotes.com
- sourceUrl? CuratedSourceUrlField - Url of the source of this curated list
listennotes: CuratedListSimple
Fields
- total? CuratedTotalPodcastsField - The total number of podcasts in this curated list
- podcasts? PodcastMinimum[] - Minimum meta data of up to 5 podcasts in this curated list
- sourceDomain? CuratedSourceDomainField -
- description? CuratedDescriptionField - This curated list's description
- id? CuratedIdField - Curated list id, which can be used to further fetch detailed curated list metadata via
GET /curated_podcasts/{id}
- title? CuratedNameField - Curated list name
- pubDateMs? CuratedPubDateMsField -
- sourceUrl? CuratedSourceUrlField -
- listennotesUrl? CuratedLNUrlField -
listennotes: CustomAudio
A custom audio in a playlist, which is a type of playlist item
Fields
- image? string - High resolution image url of this custom audio
- thumbnail? string - Low resolution image url of this custom audio
- audioLengthSec? int - Audio length in seconds
- audio? string - Audio url, which can be played directly
- title? string - Custom audio title
- pubDateMs? int - Published date of this custom audio. For now, it's the same as added_at_ms of this playlist item. It is an Epoch Unix timestamp in milliseconds
listennotes: DeletedItem
A deleted episode or podcast. An episode or a podcast could be deleted from our podcast database. Possible reasons: 1) Podcast producers sometimes delete their old episodes. 2) Copyright issues
Fields
- id? string - Episode id or podcast id
- title? string - Episode title or podcast title
- 'error? string - Why this episode or podcast is deleted?
- status? string - The status of this episode or podcast. For now, the only possible value is deleted
listennotes: DeletePlaylistItemResponse
Fields
- deleted boolean -
- id int -
listennotes: DeletePlaylistResponse
Fields
- deleted true -
- id string -
listennotes: DeletePodcastByIdQueries
Represents the Queries record for the operation: deletePodcastById
Fields
- reason? string - 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
listennotes: DeletePodcastResponse
Fields
- status "deleted"|"in review" - The status of this podcast deletion request
listennotes: EpisodeFull
Fields
- image? EpisodeImageField - Image url for this episode. If an episode doesn't have its own image, then this field would be the url of the podcast artwork image. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- thumbnail? EpisodeThumbnailField - Thumbnail image (300x300) url for this episode. If an episode doesn't have its own image, then this field would be the url of the podcast artwork thumbnail image
- explicitContent? ExplicitField -
- listennotesEditUrl? EpisodeLNEditUrlField -
- audioLengthSec? AudioLengthSecField -
- link? LinkField - Web link of this episode
- description? EpisodeDescriptionField - Html of this episode's full description
- title? EpisodeNameField - Episode name
- listennotesUrl? EpisodeLNUrlField -
- transcript? TranscriptField - 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
- podcast? PodcastSimple -
- audio? AudioField - Audio url of this episode, which can be played directly
- id? EpisodeIdField - Episode id, which can be used to further fetch detailed episode metadata via
GET /episodes/{id}
- pubDateMs? EpisodePubDateMsField -
- maybeAudioInvalid? MaybeAudioInvalidField -
listennotes: EpisodeMinimum
Fields
- image? ImageField - Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- thumbnail? ThumbnailField - Thumbnail image url for this podcast's artwork (300x300)
- explicitContent? ExplicitField -
- listennotesEditUrl? EpisodeLNEditUrlField -
- audioLengthSec? AudioLengthSecField -
- link? LinkField - Web link of this episode
- description? EpisodeDescriptionField - Html of this episode's full description
- title? EpisodeNameField - Episode name
- listennotesUrl? EpisodeLNUrlField -
- audio? AudioField - Audio url of this episode, which can be played directly
- id? EpisodeIdField - Episode id, which can be used to further fetch detailed episode metadata via
GET /episodes/{id}
- pubDateMs? EpisodePubDateMsField -
- maybeAudioInvalid? MaybeAudioInvalidField -
listennotes: EpisodeSearchResult
When type is episode
Fields
- image? EpisodeImageField - Image url for this episode. If an episode doesn't have its own image, then this field would be the url of the podcast artwork image. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- thumbnail? EpisodeThumbnailField - Thumbnail image (300x300) url for this episode. If an episode doesn't have its own image, then this field would be the url of the podcast artwork thumbnail image
- descriptionOriginal? string - Plain text of this episode's description
- itunesId? ITunesIdField - iTunes id for this podcast
- explicitContent? ExplicitField - Whether this podcast contains explicit language
- audioLengthSec? AudioLengthSecField - Audio length of this episode, in seconds
- link? LinkField - Web link of this episode
- listennotesUrl? EpisodeLNUrlField - The url of this episode on ListenNotes.com
- titleHighlighted? string - Highlighted segment of this episode's title
- titleOriginal? string - Plain text of this episode' title
- rss? RssField - RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan
- descriptionHighlighted? string - Highlighted segment of this episode's description
- podcast? EpisodeSearchResultPodcast - The podcast that this episode belongs to
- audio? AudioField - Audio url of this episode, which can be played directly
- id? EpisodeIdField - Episode id, which can be used to further fetch detailed episode metadata via
GET /episodes/{id}
- pubDateMs? EpisodePubDateMsField - Published date for this episode, as an Epoch Unix timestamp in milliseconds
- transcriptsHighlighted? string[] - Up to 2 highlighted segments of the audio transcript of this episode
listennotes: EpisodeSearchResultPodcast
The podcast that this episode belongs to
Fields
- titleHighlighted? PodcastTitleHighlightedField - Highlighted segment of podcast name
- titleOriginal? PodcastTitleOriginalField - Plain text of podcast name
- image? ImageField - Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- thumbnail? ThumbnailField - Thumbnail image url for this podcast's artwork (300x300)
- listenScoreGlobalRank? ListenScoreGlobalRankField - The estimated popularity ranking of this podcast compared to all other rss-based public podcasts in the world, such as 0.5%
- publisherOriginal? PublisherOriginalField - Plain text of this podcast's publisher name
- publisherHighlighted? PublisherHighlightedField - Highlighted segment of this podcast's publisher name
- listenScore? ListenScoreField - The estimated popularity score of this podcast compared to all other rss-based public podcasts in the world, on a scale from 0 to 100
- id? PodcastIdField - Podcast id, which can be used to further fetch detailed podcast metadata via
GET /podcasts/{id}
- genreIds? GenreIdsField - Ids of the genres this podcast belongs to
- listennotesUrl? PodcastLNUrlField - The url of this podcast on ListenNotes.com
listennotes: EpisodeSimple
Fields
- image? EpisodeImageField - Image url for this episode. If an episode doesn't have its own image, then this field would be the url of the podcast artwork image. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- thumbnail? EpisodeThumbnailField - Thumbnail image (300x300) url for this episode. If an episode doesn't have its own image, then this field would be the url of the podcast artwork thumbnail image
- explicitContent? ExplicitField -
- listennotesEditUrl? EpisodeLNEditUrlField -
- audioLengthSec? AudioLengthSecField -
- link? LinkField - Web link of this episode
- description? EpisodeDescriptionField - Html of this episode's full description
- title? EpisodeNameField - Episode name
- listennotesUrl? EpisodeLNUrlField -
- podcast? PodcastMinimum -
- audio? AudioField - Audio url of this episode, which can be played directly
- id? EpisodeIdField - Episode id, which can be used to further fetch detailed episode metadata via
GET /episodes/{id}
- pubDateMs? EpisodePubDateMsField -
- maybeAudioInvalid? MaybeAudioInvalidField -
listennotes: Genre
Fields
- parentId? int - Parent genre id
- name? string - Genre name
- id? int - Genre id
listennotes: GetBestPodcastsQueries
Represents the Queries record for the operation: getBestPodcasts
Fields
- publisherRegion? string - Filter best podcasts by the publisher's country/region.
This is to narrow down the results to include "best podcasts" produced in a specific country/region.
You can get the supported country codes (e.g., us, jp, gb...) from
GET /regions. If not specified, you'll get "best podcasts" produced in any country/region. If you want to get a country/region's "best podcasts" that are also produced in that country/region, then you need to specify both region and publisher_region, e.g.,region=jpandpublisher_region=jp
- safeMode 0|1 (default 0) - Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no
- language? string - Filter best podcasts by language.
You can get a list of supported languages (e.g., English, Chinese, Japanese...) from
GET /languages. If not specified, you'll get "best podcasts" in any language
- page? int - Page number of those podcasts in this genre
- sort "recent_added_first"|"oldest_added_first"|"recent_published_first"|"oldest_published_first"|"listen_score" (default "recent_added_first") - How do you want to sort these podcasts? If you'd like to sort by popularity, please use listen_score
- region string(default "us") - Filter best podcasts by country/region.
Please note that podcasts that are "best" in a country/region may not be produced in that country/region.
For example, a podcast from the US may be very popular in Canada.
You can get the supported country codes (e.g., us, jp, gb...) from
GET /regions. If not specified, you'll get "best podcasts" in United States
- genreId? string - 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
listennotes: GetCuratedPodcastsQueries
Represents the Queries record for the operation: getCuratedPodcasts
Fields
- page int(default 1) - Page number of curated lists
listennotes: GetCuratedPodcastsResponse
Fields
- total int -
- pageNumber int -
- hasPrevious boolean -
- nextPageNumber int -
- curatedLists CuratedListSimple[] -
- hasNext boolean -
- previousPageNumber int -
listennotes: GetEpisodeByIdQueries
Represents the Queries record for the operation: getEpisodeById
Fields
- showTranscript int(default 0) - To include the transcript of this episode or not? If it is 1, then include the transcript in the transcript field. The default value is 0 - we don't include transcript by default, because 1) it would make the response data very big, thus slow response time; 2) less than 1% of episodes have transcripts. The transcript field is available only in the PRO/ENTERPRISE plan
listennotes: GetEpisodeRecommendationsQueries
Represents the Queries record for the operation: getEpisodeRecommendations
Fields
- safeMode 0|1 (default 0) - Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no
listennotes: GetEpisodeRecommendationsResponse
Fields
- recommendations EpisodeSimple[] -
listennotes: GetEpisodesInBatchForm
Fields
- ids string - Comma-separated list of episode ids
listennotes: GetEpisodesInBatchResponse
Fields
- episodes EpisodeSimple[] -
listennotes: GetGenresQueries
Represents the Queries record for the operation: getGenres
Fields
- topLevelOnly 0|1 (default 0) - Just show top level genres? If 1, yes, just show top level genres. If 0, no, show all genres
listennotes: GetGenresResponse
Fields
- genres Genre[] -
listennotes: GetLanguagesResponse
Fields
- languages string[] -
listennotes: GetPlaylistByIdQueries
Represents the Queries record for the operation: getPlaylistById
Fields
- lastTimestampMs int(default 0) - For playlist items pagination. It's the value of last_timestamp_ms from the response of last request. If it's 0 or not specified, just return the latest or the oldest 20 items, depending on the value of the sort parameter. It is an Epoch Unix timestamp in milliseconds
- sort "recent_added_first"|"oldest_added_first"|"recent_published_first"|"oldest_published_first" (default "recent_added_first") - How do you want to sort playlist items?
- 'type? "episode_list"|"podcast_list" - Select episode_list or podcast_list to fetch that view. If omitted, use the playlist's saved default type. This query parameter does not change the saved default
listennotes: GetPlaylistsQueries
Represents the Queries record for the operation: getPlaylists
Fields
- sort "recent_added_first"|"oldest_added_first"|"name_a_to_z"|"name_z_to_a" (default "recent_added_first") - How do you want to sort playlists?
- page int(default 1) - Page number of playlists
listennotes: GetPodcastByIdQueries
Represents the Queries record for the operation: getPodcastById
Fields
- nextEpisodePubDate? int - For episodes pagination. It's the value of next_episode_pub_date from the response of last request. If not specified, just return latest 10 episodes or oldest 10 episodes, depending on the value of the sort parameter. It is an Epoch Unix timestamp in milliseconds. During pagination with next_episode_pub_date, an empty episodes array in the response signals that no more episodes are available
- sort "recent_first"|"oldest_first" (default "recent_first") - How do you want to sort the episodes of this podcast?
listennotes: GetPodcastRecommendationsQueries
Represents the Queries record for the operation: getPodcastRecommendations
Fields
- safeMode 0|1 (default 0) - Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no
listennotes: GetPodcastRecommendationsResponse
Fields
- recommendations PodcastSimple[] -
listennotes: GetPodcastsByDomainNameQueries
Represents the Queries record for the operation: getPodcastsByDomainName
Fields
- page int(default 1) - Page number of the podcasts from this domain name
listennotes: GetPodcastsInBatchForm
Fields
- nextEpisodePubDate? int - 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 15 episodes. It is an Epoch Unix timestamp in milliseconds
- spotifyIds? string - Comma-separated Spotify ids, e.g., 3DDfEsKDIDrTlnPOiG4ZF4
- itunesIds? string - Comma-separated Apple Podcasts (iTunes) ids, e.g., 659155419
- ids? string - Comma-separated list of podcast ids
- rsses? string - Comma-separated rss urls
- showLatestEpisodes 0|1 (default 0) - Whether or not to fetch up to 15 latest episodes from these podcasts, sorted by pub_date. 1 is yes, and 0 is no
listennotes: GetPodcastsInBatchResponse
Fields
- podcasts PodcastSimple[] -
- latestEpisodes? EpisodeSimple[] - Up to 10 latest episodes from these podcasts, sorted by pub_date. This field shows up only when show_latest_episodes is 1
listennotes: GetRegionsResponse
Fields
- regions record {} -
listennotes: GetRelatedSearchesQueries
Represents the Queries record for the operation: getRelatedSearches
Fields
- q string - Search term, e.g., person, place, topic..
listennotes: PlaylistCustomAudioData
A custom audio item in a playlist. It always carries its audio URL
Fields
- Fields Included from *CustomAudio
- audio string - Audio url, which can be played directly
listennotes: PlaylistDeletedItemData
A deleted item in a playlist. It always carries its status
Fields
- Fields Included from *DeletedItem
- status string - The status of this episode or podcast. For now, the only possible value is deleted
listennotes: PlaylistEpisodeData
An episode in a playlist. It always carries its podcast
Fields
- Fields Included from *EpisodeSimple
- image EpisodeImageField
- thumbnail EpisodeThumbnailField
- explicitContent ExplicitField
- listennotesEditUrl EpisodeLNEditUrlField
- audioLengthSec AudioLengthSecField
- link LinkField
- description EpisodeDescriptionField
- title EpisodeNameField
- listennotesUrl EpisodeLNUrlField
- podcast PodcastMinimum
- audio AudioField
- id EpisodeIdField
- pubDateMs EpisodePubDateMsField
- maybeAudioInvalid MaybeAudioInvalidField
- anydata...
- podcast PodcastMinimum - The podcast that this episode belongs to
listennotes: PlaylistItem
An item in a playlist
Fields
- addedAtMs? int - Timestamp when this item is added. It is an Epoch Unix timestamp in milliseconds
- notes? string - Notes for this item
- data? PlaylistEpisodeData|PlaylistPodcastData|PlaylistCustomAudioData|PlaylistDeletedItemData - The episode, podcast or custom audio that this item holds, or a placeholder when it has been deleted
- id? int - Playlist item id
- 'type? "episode"|"custom_audio"|"podcast" - The type of this playlist item. If a playlist is episode_list, then an item could be either episode or custom_audio. If it's podcast_list, then an item can only be podcast
listennotes: PlaylistPodcastData
A podcast in a playlist. It always carries its publisher
Fields
- Fields Included from *PodcastSimple
- country CountryField
- updateFrequencyHours UpdateFrequencyHoursField
- listenScoreGlobalRank ListenScoreGlobalRankField
- explicitContent ExplicitField
- itunesId ITunesIdField
- audioLengthSec AvgAudioLengthSecField
- description PodcastDescriptionField
- language LanguageField
- type PodcastTypeField
- title PodcastNameField
- isClaimed IsClaimedField
- rss RssField
- extra PodcastExtraField
- hasSponsors HasSponsorsField
- id PodcastIdField
- email EmailField
- image ImageField
- website WebsiteField
- thumbnail ThumbnailField
- earliestPubDateMs EarliestPubDateMsField
- genreIds GenreIdsField
- listennotesUrl PodcastLNUrlField
- totalEpisodes TotalEpisodesField
- hasGuestInterviews HasGuestInterviewsField
- lookingFor PodcastLookingForField
- latestEpisodeId LatestEpisodeIdField
- listenScore ListenScoreField
- publisher PublisherField
- latestPubDateMs LatestPubDateMsField
- anydata...
- publisher PublisherField - Podcast publisher name
listennotes: PlaylistResponse
Fields
- image? PlaylistImageField - High resolution image url of the playlist
- totalAudioLengthSec? int - Total audio length of all episodes in this playlist, in seconds. It will have a valid value only when type is episode_list. In other words, it will be 0 if type is podcast_list
- thumbnail? PlaylistThumbnailField - Low resolution image url of the playlist
- total? int - Total number of items in this playlist
- visibility? PlaylistVisibilityField - Visibility of this playlist
- name? PlaylistNameField - Playlist name
- description? PlaylistDescriptionField - Playlist description
- id? PlaylistIdField - A 11-character playlist id, which can be used to further fetch detailed playlist metadata via
GET /playlists/{id}
- lastTimestampMs? PlaylistLastTimestampMsField -
- 'type? "episode_list"|"podcast_list" - The selected view: episode_list or podcast_list. Uses the saved default type unless the request specifies a type query parameter
- items? PlaylistItem[] - A list of playlist items
- listennotesUrl? PlaylistListennotesUrlField -
listennotes: PlaylistsResponse
Fields
- total? int -
- pageNumber? int -
- hasPrevious? boolean -
- nextPageNumber? int -
- playlists? PlaylistsResponsePlaylists[] -
- hasNext? boolean -
- previousPageNumber? int -
listennotes: PlaylistsResponsePlaylists
A playlist
Fields
- totalAudioLengthSec? int - Total audio length of all episodes in this playlist, in seconds
- image? PlaylistImageField - High resolution image url of the playlist
- thumbnail? PlaylistThumbnailField - Low resolution image url of the playlist
- episodeCount? int - The number of episodes (including custom audio) in this playlist
- visibility? PlaylistVisibilityField - Visibility of this playlist
- podcastCount? int - The number of podcasts in this playlist
- name? PlaylistNameField - Playlist name
- description? PlaylistDescriptionField - Playlist description
- id? PlaylistIdField - A 11-character playlist id, which can be used to further fetch detailed playlist metadata via
GET /playlists/{id}
- lastTimestampMs? PlaylistLastTimestampMsField - Pass to the
last_timestamp_msparameter ofGET /playlists/{id}to paginate through the items of this playlist
- 'type? PlaylistDefaultTypeField - The saved default view of the playlist. Changing it preserves all episodes and podcasts
- listennotesUrl? PlaylistListennotesUrlField - The url of this playlist on ListenNotes.com
listennotes: PlaylistSummary
A playlist
Fields
- totalAudioLengthSec? int - Total audio length of all episodes in this playlist, in seconds
- image? PlaylistImageField - High resolution image url of the playlist
- thumbnail? PlaylistThumbnailField - Low resolution image url of the playlist
- episodeCount? int - The number of episodes (including custom audio) in this playlist
- visibility? PlaylistVisibilityField - Visibility of this playlist
- podcastCount? int - The number of podcasts in this playlist
- name? PlaylistNameField - Playlist name
- description? PlaylistDescriptionField - Playlist description
- id? PlaylistIdField - A 11-character playlist id, which can be used to further fetch detailed playlist metadata via
GET /playlists/{id}
- 'type? PlaylistDefaultTypeField - The saved default view of the playlist. Changing it preserves all episodes and podcasts
- listennotesUrl? PlaylistListennotesUrlField - The url of this playlist on ListenNotes.com
listennotes: PodcastAudienceResponse
Fields
- byRegions? PodcastAudienceResponseByRegions[] -
listennotes: PodcastAudienceResponseByRegions
Fields
- region? string - 2-letter country code of a region
- ratio? string - percentage of audience from this specific region
listennotes: PodcastDomainResponse
Fields
- pageNumber? int -
- podcasts? PodcastSimple[] -
- hasPrevious? boolean -
- nextPageNumber? int -
- hasNext? boolean -
- previousPageNumber? int -
listennotes: PodcastExtraField
Fields
- twitterHandle? string - Twitter username affiliated with this podcast
- instagramHandle? string - Instagram username affiliated with this podcast
- url3? string - Url affiliated with this podcast
- amazonMusicUrl? string - Amazon Music url for this podcast
- url1? string - Url affiliated with this podcast
- url2? string - Url affiliated with this podcast
- facebookHandle? string - Facebook username affiliated with this podcast
- linkedinUrl? string - LinkedIn url affiliated with this podcast
- youtubeUrl? string - YouTube url affiliated with this podcast
- spotifyUrl? string - Spotify url for this podcast
- wechatHandle? string - WeChat username affiliated with this podcast
- patreonHandle? string - Patreon username affiliated with this podcast
listennotes: PodcastFull
Fields
- country? CountryField - The country where this podcast is produced
- updateFrequencyHours? UpdateFrequencyHoursField -
- listenScoreGlobalRank? ListenScoreGlobalRankField -
- explicitContent? ExplicitField -
- itunesId? ITunesIdField -
- audioLengthSec? AvgAudioLengthSecField -
- description? PodcastDescriptionField - Html of this episode's full description
- language? LanguageField - The language of this podcast. You can get all supported languages from
GET /languages
- 'type? PodcastTypeField - The type of this podcast - episodic or serial
- title? PodcastNameField - Podcast name
- isClaimed? IsClaimedField -
- nextEpisodePubDate? NextEpisodePubDateField -
- rss? RssField - RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan
- extra? PodcastExtraField -
- hasSponsors? HasSponsorsField -
- id? PodcastIdField - Podcast id, which can be used to further fetch detailed podcast metadata via
GET /podcasts/{id}
- episodes? EpisodeMinimum[] -
- email? EmailField - The email of this podcast's producer. This field is available only in the PRO/ENTERPRISE plan
- image? ImageField - Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- website? WebsiteField - Website url of this podcast
- thumbnail? ThumbnailField - Thumbnail image url for this podcast's artwork (300x300)
- earliestPubDateMs? EarliestPubDateMsField -
- genreIds? GenreIdsField -
- listennotesUrl? PodcastLNUrlField -
- totalEpisodes? TotalEpisodesField -
- hasGuestInterviews? HasGuestInterviewsField -
- lookingFor? PodcastLookingForField -
- latestEpisodeId? LatestEpisodeIdField -
- listenScore? ListenScoreField -
- publisher? PublisherField - Podcast publisher name
- latestPubDateMs? LatestPubDateMsField -
listennotes: PodcastLookingForField
Fields
- crossPromotion? boolean - Whether this podcast is looking for cross promotion opportunities with other podcasts
- sponsors? boolean - Whether this podcast is looking for sponsors
- guests? boolean - Whether this podcast is looking for guests
- cohosts? boolean - Whether this podcast is looking for cohosts
listennotes: PodcastMinimum
Fields
- image? ImageField - Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- thumbnail? ThumbnailField - Thumbnail image url for this podcast's artwork (300x300)
- listenScoreGlobalRank? ListenScoreGlobalRankField -
- listenScore? ListenScoreField -
- publisher? PublisherField - Podcast publisher name
- id? PodcastIdField - Podcast id, which can be used to further fetch detailed podcast metadata via
GET /podcasts/{id}
- title? PodcastNameField - Podcast name
- listennotesUrl? PodcastLNUrlField -
listennotes: PodcastSearchResult
When type is podcast
Fields
- updateFrequencyHours? UpdateFrequencyHoursField - How frequently this podcast releases a new episode, in hours
- descriptionOriginal? string - Plain text of podcast description
- listenScoreGlobalRank? ListenScoreGlobalRankField - The estimated popularity ranking of this podcast compared to all other rss-based public podcasts in the world, such as 0.5%
- itunesId? ITunesIdField - iTunes id for this podcast
- explicitContent? ExplicitField - Whether this podcast contains explicit language
- audioLengthSec? AvgAudioLengthSecField - Average audio length of all episodes of this podcast, in seconds
- titleOriginal? PodcastTitleOriginalField - Plain text of podcast name
- rss? RssField - RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan
- publisherOriginal? PublisherOriginalField - Plain text of this podcast's publisher name
- hasSponsors? HasSponsorsField - Whether this podcast has sponsors
- id? PodcastIdField - Podcast id, which can be used to further fetch detailed podcast metadata via
GET /podcasts/{id}
- email? EmailField - The email of this podcast's producer. This field is available only in the PRO/ENTERPRISE plan
- image? ImageField - Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- thumbnail? ThumbnailField - Thumbnail image url for this podcast's artwork (300x300)
- website? WebsiteField - Website url of this podcast
- publisherHighlighted? PublisherHighlightedField - Highlighted segment of this podcast's publisher name
- earliestPubDateMs? EarliestPubDateMsField - The published date of the oldest episode of this podcast, as an Epoch Unix timestamp in milliseconds
- genreIds? GenreIdsField - Ids of the genres this podcast belongs to
- listennotesUrl? PodcastLNUrlField - The url of this podcast on ListenNotes.com
- totalEpisodes? TotalEpisodesField - Total number of episodes in this podcast
- titleHighlighted? PodcastTitleHighlightedField - Highlighted segment of podcast name
- hasGuestInterviews? HasGuestInterviewsField - Whether this podcast has guest interviews
- descriptionHighlighted? string - Highlighted segment of podcast description
- latestEpisodeId? LatestEpisodeIdField - The id of the most recently published episode of this podcast
- listenScore? ListenScoreField - The estimated popularity score of this podcast compared to all other rss-based public podcasts in the world, on a scale from 0 to 100
- latestPubDateMs? LatestPubDateMsField - The published date of the latest episode of this podcast, as an Epoch Unix timestamp in milliseconds
listennotes: PodcastSimple
Fields
- country? CountryField - The country where this podcast is produced
- updateFrequencyHours? UpdateFrequencyHoursField -
- listenScoreGlobalRank? ListenScoreGlobalRankField -
- explicitContent? ExplicitField -
- itunesId? ITunesIdField -
- audioLengthSec? AvgAudioLengthSecField -
- description? PodcastDescriptionField - Html of this episode's full description
- language? LanguageField - The language of this podcast. You can get all supported languages from
GET /languages
- 'type? PodcastTypeField - The type of this podcast - episodic or serial
- title? PodcastNameField - Podcast name
- isClaimed? IsClaimedField -
- rss? RssField - RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan
- extra? PodcastExtraField -
- hasSponsors? HasSponsorsField -
- id? PodcastIdField - Podcast id, which can be used to further fetch detailed podcast metadata via
GET /podcasts/{id}
- email? EmailField - The email of this podcast's producer. This field is available only in the PRO/ENTERPRISE plan
- image? ImageField - Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- website? WebsiteField - Website url of this podcast
- thumbnail? ThumbnailField - Thumbnail image url for this podcast's artwork (300x300)
- earliestPubDateMs? EarliestPubDateMsField -
- genreIds? GenreIdsField -
- listennotesUrl? PodcastLNUrlField -
- totalEpisodes? TotalEpisodesField -
- hasGuestInterviews? HasGuestInterviewsField -
- lookingFor? PodcastLookingForField -
- latestEpisodeId? LatestEpisodeIdField -
- listenScore? ListenScoreField -
- publisher? PublisherField - Podcast publisher name
- latestPubDateMs? LatestPubDateMsField -
listennotes: PodcastTypeaheadResult
Fields
- titleHighlighted? PodcastTitleHighlightedField -
- titleOriginal? PodcastTitleOriginalField -
- image? ImageField - Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
- thumbnail? ThumbnailField - Thumbnail image url for this podcast's artwork (300x300)
- explicitContent? ExplicitField -
- publisherOriginal? PublisherOriginalField -
- publisherHighlighted? PublisherHighlightedField -
- id? PodcastIdField - Podcast id, which can be used to further fetch detailed podcast metadata via
GET /podcasts/{id}
listennotes: RefreshRssResponse
Fields
- lastRefreshedAtMs? int - The timestamp when the rss was last refreshed. It is an Epoch Unix timestamp in milliseconds
- status "refreshing"|"refreshed" - The status of the rss refreshing request
listennotes: RelatedSearchesResponse
Fields
- terms string[] - Related search terms
listennotes: SearchEpisodeTitlesQueries
Represents the Queries record for the operation: searchEpisodeTitles
Fields
- q string - An episode's title, e.g., Jerusalem Demsas on The Dispossessed. You can use double quotes to do verbatim match, e.g., "Jerusalem Demsas on The Dispossessed". Otherwise, it's fuzzy search
- podcastIdType "listennotes_id"|"itunes_id"|"spotify_id"|"rss" (default "listennotes_id") - The type of podcast id. Valid values are listennotes_id, itunes_id, spotify_id, and rss. Note: itunes_id is for Apple Podcasts
- podcastId? string - Refine search results by specifying a podcast through its unique ID. The format of the podcast ID is governed by the podcast_id_type parameter. For listennotes_id, the podcast ID will look like 'cda18f20f1be4ac7b3cce7d0eb168fff'. For itunes_id, it will be a numerical value like '983795625'. For spotify_id, expect a format like '0Z1234tGXD2hVhjFrrhJ7g'. For rss, the podcast ID will be the RSS URL, e.g., 'https://cowenconvos.libsyn.com/rss'
listennotes: SearchEpisodeTitlesResponse
Fields
- took? decimal - The time it took to fetch these search results. In seconds
- total? int - The total number of search results
- count? int - The number of search results in this page
- nextOffset? int - Pass this value to the offset parameter to do pagination of search results
- results? EpisodeSearchResult[] - A list of search results
listennotes: SearchQueries
Represents the Queries record for the operation: search
Fields
- uniquePodcasts 0|1 (default 0) - Whether or not to keep only one episode per podcast in search results. 1 is yes and 0 is no. It works only when type is episode
- episodeCountMin? int - Minimum number of episodes. Applicable only when type parameter is podcast
- 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
- offset int(default 0) - Offset for search results, for pagination. You'll use next_offset from response for this parameter
- publishedBefore? int - Only show episodes/podcasts/curated lists published before this Epoch Unix timestamp (in milliseconds). If published_before & published_after are used at the same time, published_before should be bigger than published_after
- safeMode 0|1 (default 0) - Whether or not to exclude podcasts/episodes with explicit language. 1 is yes and 0 is no. It works only when type is episode or podcast
- 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
- sponsoredOnly 0|1 (default 0) - Whether or not to keep only podcasts that have sponsors in search results. 1 is yes and 0 is no. It works only when type is podcast. This parameter is available only in the PRO/ENTERPRISE plan
- updateFreqMin? int - Minimum update frequency in hours (how frequently does a podcast release a new episode). For example, if you want to find "weekly" podcasts, then you can set update_freq_min=144 hours (or 6 days) and update_freq_max=192 hours (or 8 days). Applicable only when type parameter is podcast
- onlyIn string(default "title,description,author,audio") - A comma-delimited string to search only in specific fields. Allowed values are title, description, author, and audio. If not specified, then search every fields
- 'type "episode"|"podcast"|"curated" (default "episode") - What type of contents do you want to search for?
- episodeCountMax? int - Maximum number of episodes. Applicable only when type parameter is podcast
- genreIds? 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
- lenMax? int - Maximum audio length in minutes. Applicable only when type parameter is episode or podcast. If type parameter is episode, it's for audio length of an episode. If type parameter is podcast, it's for average audio length of all episodes in a podcast
- q string - 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
- interviewsOnly 0|1 (default 0) - Whether or not to keep only podcasts that have guest interviews in search results. 1 is yes and 0 is no. It works only when type is podcast. This parameter is available only in the PRO/ENTERPRISE plan
- sortByDate 0|1 (default 0) - Sort by date or not? If 0, then sort by relevance. If 1, then sort by date
- updateFreqMax? int - Maximum update frequency in hours (how frequently does a podcast release a new episode). For example, if you want to find "weekly" podcasts, then you can set update_freq_min=144 hours (or 6 days) and update_freq_max=192 hours (or 8 days). Applicable only when type parameter is podcast
- publishedAfter int(default 0) - Only show episodes/podcasts/curated lists published after this Epoch Unix timestamp (in milliseconds). If published_before & published_after are used at the same time, published_before should be bigger than published_after
- 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
- lenMin int(default 0) - Minimum audio length in minutes. Applicable only when type parameter is episode or podcast. If type parameter is episode, it's for audio length of an episode. If type parameter is podcast, it's for average audio length of all episodes in a podcast
- pageSize int(default 10) - The maximum number of search results per page. A valid value should be an integer between 1 and 10 (inclusive)
listennotes: SearchResponse
Fields
- took? decimal - The time it took to fetch these search results. In seconds
- total? int - The total number of search results
- count? int - The number of search results in this page
- nextOffset? int - Pass this value to the offset parameter to do pagination of search results
- results? SearchResponseResults[] - A list of search results
listennotes: SpellcheckQueries
Represents the Queries record for the operation: spellcheck
Fields
- q string - Search term, e.g., person, place, topic..
listennotes: SpellCheckResponse
Fields
- correctedTextHtml string - The corrected text for the entire search term (multiple words/tokens), where misspelled tokens are replaced with the correct texts and html tags <b><i>
- tokens SpellCheckResponseTokens[] - The word in the text query string that is not spelled correctly
listennotes: SpellCheckResponseTokens
Fields
- offset? int - The zero-based offset from the beginning of the text query string to the word that is misspelled
- suggestion? string - A word that corrects the spelling error
- token? string - The misspelled word
listennotes: SubmitPodcastForm
Fields
- rss string - A valid podcast rss url
- email? string - A valid email address. If email is specified, then we'll notify this email address once the podcast is accepted
listennotes: SubmitPodcastResponse
Fields
- podcast PodcastMinimum -
- status "found"|"in review"|"rejected" - The status of this submission
listennotes: TrendingSearchesResponse
Fields
- terms string[] - Trending search terms
listennotes: TypeaheadQueries
Represents the Queries record for the operation: typeahead
Fields
- q string - 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
- showGenres 0|1 (default 0) - Whether or not to autosuggest genres. 1 is yes, 0 is no
- showPodcasts 0|1 (default 0) - Autosuggest podcasts. This only searches podcast title and publisher and returns very limited info of 5 podcasts. 1 is yes, 0 is no. It's a bit slow to autosuggest podcasts, so we turn it off by default. If show_podcasts=1, you can also pass iTunes id (e.g., 474722933) to the q parameter to fetch podcast meta data
- safeMode 0|1 (default 0) - Whether or not to exclude podcasts/episodes with explicit language. 1 is yes and 0 is no. It works only when show_podcasts is 1
listennotes: TypeaheadResponse
Fields
- podcasts? PodcastTypeaheadResult[] - Podcast suggestions. It'll show up when the show_podcasts parameter is 1
- terms string[] - Search term suggestions
- genres? Genre[] - Genre suggestions. It'll show up when the show_genres parameter is 1
listennotes: UpdatePlaylistItemNotesRequest
Fields
- notes string - Plain-text notes. An empty string clears existing notes
listennotes: UpdatePlaylistRequest
Fields
- visibility? "public"|"unlisted"|"private" - Who can view the playlist. Creation defaults to public
- name? string - Nonblank playlist name. Leading/trailing whitespace is trimmed; rss is reserved (case insensitive)
- description? string - Playlist description. An empty string clears it
- 'type? "episode_list"|"podcast_list" - The saved default view. Changing it preserves all episodes and podcasts in the playlist
Union types
listennotes: PodcastTypeField
PodcastTypeField
The type of this podcast - episodic or serial
listennotes: PlaylistVisibilityField
PlaylistVisibilityField
Visibility of this playlist
listennotes: SearchResponseResults
SearchResponseResults
listennotes: PlaylistDefaultTypeField
PlaylistDefaultTypeField
The saved default view of the playlist. Changing it preserves all episodes and podcasts
Array types
listennotes: GenreIdsField
GenreIdsField
String types
listennotes: PlaylistNameField
PlaylistNameField
Playlist name
listennotes: PublisherField
PublisherField
Podcast publisher name
listennotes: ImageField
ImageField
Image url for this podcast's artwork. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
listennotes: CuratedSourceDomainField
CuratedSourceDomainField
The domain name of the source of this curated list
listennotes: ListenScoreGlobalRankField
ListenScoreGlobalRankField
The estimated popularity ranking of a podcast compared to all other rss-based public podcasts in the world. For 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. If the ranking is not available, it'll be null. Learn more at listennotes.com/listen-score
listennotes: PodcastDescriptionField
PodcastDescriptionField
Html of this episode's full description
listennotes: AudioField
AudioField
Audio url of this episode, which can be played directly
listennotes: PlaylistListennotesUrlField
PlaylistListennotesUrlField
The URL of the playlist view indicated by type. Playlist summaries use the saved default view; fetching items with an explicit type returns the URL for that selected view
listennotes: EpisodeIdField
EpisodeIdField
Episode id, which can be used to further fetch detailed episode metadata via GET /episodes/{id}
listennotes: PlaylistIdField
PlaylistIdField
A 11-character playlist id, which can be used to further fetch detailed playlist metadata via GET /playlists/{id}
listennotes: LinkField
LinkField
Web link of this episode
listennotes: RssField
RssField
RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan
listennotes: CuratedIdField
CuratedIdField
Curated list id, which can be used to further fetch detailed curated list metadata via GET /curated_podcasts/{id}
listennotes: PublisherHighlightedField
PublisherHighlightedField
Highlighted segment of this podcast's publisher name
listennotes: EpisodeLNEditUrlField
EpisodeLNEditUrlField
Edit url of this episode where you can update the audio url if you find the audio is broken
listennotes: PodcastNameField
PodcastNameField
Podcast name
listennotes: EpisodeLNUrlField
EpisodeLNUrlField
The url of this episode on ListenNotes.com
listennotes: PodcastLNUrlField
PodcastLNUrlField
The url of this podcast on ListenNotes.com
listennotes: PodcastTitleOriginalField
PodcastTitleOriginalField
Plain text of podcast name
listennotes: PlaylistThumbnailField
PlaylistThumbnailField
Low resolution image url of the playlist
listennotes: EpisodeNameField
EpisodeNameField
Episode name
listennotes: LatestEpisodeIdField
LatestEpisodeIdField
The id of the most recently published episode of this podcast, which can be used to further fetch detailed episode metadata via GET /episodes/{id}
listennotes: EpisodeImageField
EpisodeImageField
Image url for this episode. If an episode doesn't have its own image, then this field would be the url of the podcast artwork image. If you are using PRO/ENTERPRISE plan, then it's a high resolution image (1400x1400). If you are using FREE plan, then it's the same as thumbnail, low resolution image (300x300)
listennotes: CuratedDescriptionField
CuratedDescriptionField
This curated list's description
listennotes: CountryField
CountryField
The country where this podcast is produced
listennotes: EpisodeDescriptionField
EpisodeDescriptionField
Html of this episode's full description
listennotes: PlaylistImageField
PlaylistImageField
High resolution image url of the playlist
listennotes: PublisherOriginalField
PublisherOriginalField
Plain text of this podcast's publisher name
listennotes: PodcastTitleHighlightedField
PodcastTitleHighlightedField
Highlighted segment of podcast name
listennotes: ThumbnailField
ThumbnailField
Thumbnail image url for this podcast's artwork (300x300)
listennotes: TranscriptField
TranscriptField
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
listennotes: WebsiteField
WebsiteField
Website url of this podcast
listennotes: CuratedNameField
CuratedNameField
Curated list name
listennotes: LanguageField
LanguageField
The language of this podcast. You can get all supported languages from GET /languages
listennotes: PlaylistDescriptionField
PlaylistDescriptionField
Playlist description
listennotes: EmailField
EmailField
The email of this podcast's producer. This field is available only in the PRO/ENTERPRISE plan
listennotes: CuratedLNUrlField
CuratedLNUrlField
The url of this curated list on ListenNotes.com
listennotes: CuratedSourceUrlField
CuratedSourceUrlField
Url of the source of this curated list
listennotes: BestPodcastsLNUrlField
BestPodcastsLNUrlField
Url of the list of best podcasts on ListenNotes.com
listennotes: EpisodeThumbnailField
EpisodeThumbnailField
Thumbnail image (300x300) url for this episode. If an episode doesn't have its own image, then this field would be the url of the podcast artwork thumbnail image
listennotes: PodcastIdField
PodcastIdField
Podcast id, which can be used to further fetch detailed podcast metadata via GET /podcasts/{id}
Integer types
listennotes: AvgAudioLengthSecField
AvgAudioLengthSecField
Average audio length of all episodes of this podcast. In seconds
listennotes: EpisodePubDateMsField
EpisodePubDateMsField
Published date for this episode. It is an Epoch Unix timestamp in milliseconds
listennotes: UpdateFrequencyHoursField
UpdateFrequencyHoursField
How frequently does this podcast release a new episode? In hours. For example, if the value is 166, then it's every 166 hours (or weekly)
listennotes: NextEpisodePubDateField
NextEpisodePubDateField
Passed to the next_episode_pub_date parameter of GET /podcasts/{id} to paginate through episodes of that podcast. It is an Epoch Unix timestamp in milliseconds
listennotes: PlaylistLastTimestampMsField
PlaylistLastTimestampMsField
Passed to the last_timestamp_ms parameter of GET /playlists/{id} to paginate through items of that playlist.
It is an Epoch Unix timestamp in milliseconds
listennotes: LatestPubDateMsField
LatestPubDateMsField
The published date of the latest episode of this podcast. It is an Epoch Unix timestamp in milliseconds
listennotes: CuratedPubDateMsField
CuratedPubDateMsField
Published date of this curated list. It is an Epoch Unix timestamp in milliseconds
listennotes: AudioLengthSecField
AudioLengthSecField
Audio length of this episode. In seconds
listennotes: EarliestPubDateMsField
EarliestPubDateMsField
The published date of the oldest episode of this podcast. It is an Epoch Unix timestamp in milliseconds
listennotes: ListenScoreField
ListenScoreField
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. If the score is not available, it'll be null. Learn more at listennotes.com/listen-score
listennotes: ITunesIdField
ITunesIdField
iTunes id for this podcast
listennotes: CuratedTotalPodcastsField
CuratedTotalPodcastsField
The total number of podcasts in this curated list
listennotes: TotalEpisodesField
TotalEpisodesField
Total number of episodes in this podcast
Boolean types
listennotes: IsClaimedField
IsClaimedField
Whether this podcast is claimed by its producer on ListenNotes.com
listennotes: ExplicitField
ExplicitField
Whether this podcast contains explicit language
listennotes: MaybeAudioInvalidField
MaybeAudioInvalidField
Whether or not this episode's audio is invalid. Podcasters may delete the original audio
listennotes: HasSponsorsField
HasSponsorsField
Whether this podcast has sponsors
listennotes: HasGuestInterviewsField
HasGuestInterviewsField
Whether this podcast has guest interviews
Import
import ballerinax/listennotes;Other versions
1.0.0
Metadata
Released date: 1 day ago
Version: 1.0.0
License: Apache-2.0
Security
Direct vulnerabilities: No known direct vulnerabilities
Indirect vulnerabilities:
Checked on 2026-11-21 via OSV.dev
Compatibility
Platform: any
Ballerina version: 2201.12.0
GraalVM compatible: Yes
Pull count
Total: 1
Current verison: 1
Weekly downloads
Keywords
Vendor/Listen Notes
Area/Communication
Type/Connector
Contributors