Ballerina library

listen.notes

Module listen.notes

OverviewPrerequisitesQuickstart

API

Client

Definitions

ApiKeysConfig
BestPodcastsResponse
ClientHttp1Settings
ConnectionConfig
CuratedListFull
CuratedListSearchResult
CuratedListSimple
CustomAudio
DeletedItem
DeletePodcastResponse
EpisodeFull
EpisodeMinimum
EpisodeSearchResult
EpisodesearchresultPodcast
EpisodeSimple
Genre
GetCuratedPodcastsResponse
GetEpisodeRecommendationsResponse
GetEpisodesInBatchForm
GetEpisodesInBatchResponse
GetGenresResponse
GetLanguagesResponse
GetPodcastRecommendationsResponse
GetPodcastsInBatchForm
GetPodcastsInBatchResponse
GetRegionsResponse
PlaylistItem
PlaylistResponse
PlaylistsResponse
PlaylistsresponsePlaylists
PodcastExtraField
PodcastFull
PodcastLookingForField
PodcastMinimum
PodcastSearchResult
PodcastSimple
PodcastTypeaheadResult
ProxyConfig
SearchResponse
SubmitPodcastForm
SubmitPodcastResponse
TypeaheadResponse

GenreIdsField

PodcastTitleOriginalField
PlaylistThumbnailField
EpisodeNameField
PodcastTypeField
PlaylistNameField
EpisodeImageField
CuratedDescriptionField
CountryField
PublisherField
ImageField
EpisodeDescriptionField
CuratedSourceDomainField
PlaylistImageField
PlaylistVisibilityField
PodcastDescriptionField
ListenScoreGlobalRankField
PublisherOriginalField
AudioField
PodcastTitleHighlightedField
ThumbnailField
TranscriptField
PlaylistListennotesUrlField
EpisodeIdField
WebsiteField
PlaylistIdField
LinkField
RssField
CuratedNameField
LanguageField
CuratedIdField
EpisodeLNEditUrlField
PublisherHighlightedField
PlaylistDescriptionField
EmailField
PodcastNameField
CuratedLNUrlField
CuratedSourceUrlField
BestPodcastsLNUrlField
EpisodeLNUrlField
EpisodeThumbnailField
PodcastLNUrlField
PodcastIdField

AudioLengthSecField
EarliestPubDateMsField
EpisodePubDateMsField
ListenScoreField
ITunesIdField
CuratedTotalPodcastsField
TotalEpisodesField
NextEpisodePubDateField
PlaylistLastTimestampMsField
LatestPubDateMsField
CuratedPubDateMsField

IsClaimedField
ExplicitField
MaybeAudioInvalidField

ballerinax/listen.notes Ballerina library

1.5.2

Overview

The Listen Notes API v2.0 connector(https://www.listennotes.com/) OpenAPI specification.

Simple & no-nonsense podcast search & directory API. Search all podcasts and episodes by people, places, or topics.

Key Features

  • Programmatic access to create and manage resources via REST API
  • Manage user accounts and profiles
  • Secure authentication with API key or OAuth support

Prerequisites

Before using this connector in your Ballerina application, complete the following:

Quickstart

To use the Listen Notes connector in your Ballerina application, update the .bal file as follows:

Step 1: Import connector

First, import the ballerinax/listen.notes module into the Ballerina project.

Copy
import ballerinax/listen.notes;

Step 2: Create a new connector instance

Create a notes:ApiKeysConfig with the <API_KEY> obtained, and initialize the connector with it.

Copy
notes:ApiKeysConfig apiKeyConfig = {
    xListenapiKey: `<API_KEY>`
};

notes:Client baseClient = check new Client(apiKeyConfig);

Step 3: Invoke connector operation

  1. Now you can use the operations available within the connector. Note that they are in the form of remote operations.

    Following is an example to search using the connector.

    Copy
    public function main() {
    string q = "game of thrones";

    notes:SearchResponse|error response = baseClient->search(q);
    if (response is notes:SearchResponse) {
        log:printInfo(response.toString());
    } else {
        log:printError(response.message());
    }
}

  2. Use bal run command to compile and run the Ballerina program.

Clients

listen.notes: Client

Isolated

This is a generated connector for Listen Notes API v2.0 OpenAPI specification. Simple & no-nonsense podcast search & directory API. Search all podcasts and episodes by people, places, or topics.

Constructor

Gets invoked to initialize the connector. The connector initialization requires setting the API credentials. Create a Listen Notes account and obtain tokens by following this guide.

init (ApiKeysConfig apiKeyConfig, ConnectionConfig config, string serviceUrl)
  • 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
Isolated FunctionRemote Function
function search(string q, int sortByDate, string 'type, int offset, int lenMin, int? lenMax, int? episodeCountMin, int? episodeCountMax, string? genreIds, int? publishedBefore, int publishedAfter, string onlyIn, string? language, string? region, string? ocid, string? ncid, int safeMode) returns SearchResponse|error

Full-text search

Parameters
  • 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.
  • sortByDate int (default 0) - Sort by date or not? If 0, then sort by relevance. If 1, then sort by date.
  • 'type string (default "episode") - What type of contents do you want to search for?
  • offset int (default 0) - Offset for search results, for pagination. You'll use next_offset from response for this parameter.
  • lenMin int (default 0) - Minimum audio length in minutes. Applicable only when type parameter is episode.
  • lenMax int? (default ()) - Maximum audio length in minutes. Applicable only when type parameter is episode.
  • episodeCountMin int? (default ()) - Minimum number of episodes. Applicable only when type parameter is podcast.
  • episodeCountMax int? (default ()) - Maximum number of episodes. Applicable only when type parameter is podcast.
  • genreIds string? (default ()) - 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.
  • publishedBefore int? (default ()) - 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.
  • publishedAfter int (default 0) - 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.
  • 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.
  • language string? (default ()) - 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? (default ()) - 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? (default ()) - 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? (default ()) - 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.
  • safeMode int (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.
Return Type

typeahead

Isolated FunctionRemote Function
function typeahead(string q, int showPodcasts, int showGenres, int safeMode) returns TypeaheadResponse|error

Typeahead search

Parameters
  • 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.
  • showPodcasts int (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.
  • showGenres int (default 0) - Whether or not to autosuggest genres. 1 is yes, 0 is no.
  • safeMode int (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.
Return Type

getBestPodcasts

Isolated FunctionRemote Function
function getBestPodcasts(string? genreId, int? page, string region, string? publisherRegion, string? language, int safeMode) returns BestPodcastsResponse|error

Fetch a list of best podcasts by genre

Parameters
  • genreId string? (default ()) - You can get the id from GET /genres. If not specified, it'll be the overall best podcasts, which can be considered as a special genre.
  • page int? (default ()) - Page number of those podcasts in this genre.
  • 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.
  • publisherRegion string? (default ()) - Filter best podcasts by the publisher's country/region. This is to narrow down the results to include "best podcasts" produced in a specific country/region. You can get the supported country codes (e.g., us, jp, gb...) from GET /regions. If not specified, you'll get "best podcasts" produced in any country/region. If you want to get a country/region's "best podcasts" that are also produced in that country/region, then you need to specify both region and publisher_region, e.g., region=jp and publisher_region=jp.
  • language string? (default ()) - 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.
  • safeMode int (default 0) - Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.
Return Type

getPodcastById

Isolated FunctionRemote Function
function getPodcastById(string id, int? nextEpisodePubDate, string sort) returns PodcastFull|error

Fetch 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...
  • nextEpisodePubDate int? (default ()) - 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.
  • sort string (default "recent_first") - How do you want to sort the episodes of this podcast?
Return Type

deletePodcastById

Isolated FunctionRemote Function
function deletePodcastById(string id, string? reason) returns DeletePodcastResponse|error

Request 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...
  • reason string? (default ()) - 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.
Return Type

getEpisodeById

Isolated FunctionRemote Function
function getEpisodeById(string id, int showTranscript) returns EpisodeFull|error

Fetch 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...
  • 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.
Return Type

getEpisodesInBatch

Isolated FunctionRemote Function
function getEpisodesInBatch(GetEpisodesInBatchForm payload) returns GetEpisodesInBatchResponse|error

Batch fetch basic meta data for episodes

Parameters
Return Type

getPodcastsInBatch

Isolated FunctionRemote Function
function getPodcastsInBatch(GetPodcastsInBatchForm payload) returns GetPodcastsInBatchResponse|error

Batch fetch basic meta data for podcasts

Parameters
Return Type

getCuratedPodcastById

Isolated FunctionRemote Function
function getCuratedPodcastById(string id) returns CuratedListFull|error

Fetch 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=curated or GET /curated_podcasts.
Return Type

getGenres

Isolated FunctionRemote Function
function getGenres(int topLevelOnly) returns GetGenresResponse|error

Fetch a list of podcast genres

Parameters
  • topLevelOnly int (default 0) - Just show top level genres? If 1, yes, just show top level genres. If 0, no, show all genres.
Return Type

getRegions

Isolated FunctionRemote Function
function getRegions() returns GetRegionsResponse|error

Fetch a list of supported countries/regions for best podcasts

Return Type

getLanguages

Isolated FunctionRemote Function
function getLanguages() returns GetLanguagesResponse|error

Fetch a list of supported languages for podcasts

Return Type

justListen

Isolated FunctionRemote Function
function justListen() returns EpisodeSimple|error

Fetch a random podcast episode

Return Type

getCuratedPodcasts

Isolated FunctionRemote Function
function getCuratedPodcasts(int page) returns GetCuratedPodcastsResponse|error

Fetch curated lists of podcasts

Parameters
  • page int (default 1) - Page number of curated lists.
Return Type

getPodcastRecommendations

Isolated FunctionRemote Function
function getPodcastRecommendations(string id, int safeMode) returns GetPodcastRecommendationsResponse|error

Fetch recommendations for a podcast

Parameters
  • safeMode int (default 0) - Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.
Return Type

getEpisodeRecommendations

Isolated FunctionRemote Function
function getEpisodeRecommendations(string id, int safeMode) returns GetEpisodeRecommendationsResponse|error

Fetch recommendations for an episode

Parameters
  • safeMode int (default 0) - Whether or not to exclude podcasts with explicit language. 1 is yes, and 0 is no.
Return Type

submitPodcast

Isolated FunctionRemote Function
function submitPodcast(SubmitPodcastForm payload) returns SubmitPodcastResponse|error

Submit a podcast to Listen Notes database

Parameters
Return Type

getPlaylistById

Isolated FunctionRemote Function
function getPlaylistById(string id, string 'type, int lastTimestampMs, string sort) returns PlaylistResponse|error

Fetch 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
  • 'type string (default "episode_list") - The type of this playlist, which should be either episode_list or podcast_list.
  • 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.
  • sort string (default "recent_added_first") - How do you want to sort playlist items?
Return Type

getPlaylists

Isolated FunctionRemote Function
function getPlaylists(string sort, int page) returns PlaylistsResponse|error

Fetch a list of your playlists.

Parameters
  • sort string (default "recent_added_first") - How do you want to sort playlists?
  • page int (default 1) - Page number of playlists.
Return Type

Records

listen.notes: ApiKeysConfig

Closed record

Provides API key configurations needed when communicating with a remote HTTP endpoint.

Fields
  • xListenapiKey string - Represents API Key X-ListenAPI-Key

listen.notes: BestPodcastsResponse

Fields
  • name string - This genre's name.
  • previous_page_number int -
  • page_number int -
  • next_page_number int -
  • parent_id int - The id of parent genre.
  • id int - The id of this genre

listen.notes: ClientHttp1Settings

Closed record

Provides settings related to HTTP/1.x protocol.

Fields
  • keepAlive KeepAlive(default http:KEEPALIVE_AUTO) - Specifies whether to reuse a connection for multiple requests
  • chunking Chunking(default http:CHUNKING_AUTO) - The chunking behaviour of the request

listen.notes: ConnectionConfig

Closed record

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
  • timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection
  • forwarded string(default "disable") - The choice of setting forwarded/x-forwarded header
  • cache? CacheConfig - 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
  • validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default

listen.notes: CuratedListFull

Fields
  • podcasts? PodcastSimple[] - Complete meta data of all podcasts in this curated list.

listen.notes: CuratedListSearchResult

When type is curated.

Fields
  • description_highlighted? string - Highlighted segment of this curated list's description
  • description_original? string - Plain text of this curated list's description
  • title_highlighted? string - Highlighted segment of this curated list's title
  • title_original? string - Plain text of this curated list's title

listen.notes: CuratedListSimple

Fields
  • podcasts? PodcastMinimum[] - Minimum meta data of up to 5 podcasts in this curated list.

listen.notes: CustomAudio

A custom audio in a playlist, which is a type of playlist item.

Fields
  • title? string - Custom audio title.
  • audio? string - Audio url, which can be played directly.
  • audio_length_sec? int - Audio length in seconds.
  • image? string - High resolution image url of this custom audio.
  • thumbnail? string - Low resolution image url of this custom audio.
  • pub_date_ms? int - Published date (in milliseconds) of this custom audio. For now, it's the same as added_at_ms of this playlist item.

listen.notes: 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.
  • status? string - The status of this episode or podcast. For now, the only possible value is deleted.
  • 'error? string - Why this episode or podcast is deleted?

listen.notes: DeletePodcastResponse

Fields
  • status string - The status of this podcast deletion request.

listen.notes: EpisodeFull

Fields
  • maybe_audio_invalid? MaybeAudioInvalidField - Whether or not this episode's audio is invalid. Podcasters may delete the original audio.
  • audio? AudioField - Audio url of this episode, which can be played directly.
  • listennotes_edit_url? EpisodeLNEditUrlField - Edit url of this episode where you can update the audio url if you find the audio is broken.
  • 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.
  • explicit_content? ExplicitField - Whether this podcast contains explicit language.
  • 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.

listen.notes: EpisodeMinimum

Fields
  • maybe_audio_invalid? MaybeAudioInvalidField - Whether or not this episode's audio is invalid. Podcasters may delete the original audio.
  • audio? AudioField - Audio url of this episode, which can be played directly.
  • listennotes_edit_url? EpisodeLNEditUrlField - Edit url of this episode where you can update the audio url if you find the audio is broken.
  • 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).
  • explicit_content? ExplicitField - Whether this podcast contains explicit language.

listen.notes: EpisodeSearchResult

When type is episode.

Fields
  • audio? AudioField - Audio url of this episode, which can be played directly.
  • rss? RssField - RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan.
  • description_highlighted? string - Highlighted segment of this episode's description
  • description_original? string - Plain text of this episode's description
  • title_highlighted? string - Highlighted segment of this episode's title
  • title_original? string - Plain text of this episode' title
  • transcripts_highlighted? string[] - Up to 2 highlighted segments of the audio transcript of this episode.
  • 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.
  • explicit_content? ExplicitField - Whether this podcast contains explicit language.

listen.notes: EpisodesearchresultPodcast

The podcast that this episode belongs to.

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).
  • listen_score? 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
  • listen_score_global_rank? 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

listen.notes: EpisodeSimple

Fields
  • maybe_audio_invalid? MaybeAudioInvalidField - Whether or not this episode's audio is invalid. Podcasters may delete the original audio.
  • audio? AudioField - Audio url of this episode, which can be played directly.
  • listennotes_edit_url? EpisodeLNEditUrlField - Edit url of this episode where you can update the audio url if you find the audio is broken.
  • 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.
  • explicit_content? ExplicitField - Whether this podcast contains explicit language.

listen.notes: Genre

Fields
  • id? int - Genre id
  • parent_id? int - Parent genre id.

listen.notes: GetCuratedPodcastsResponse

Fields
  • previous_page_number int -
  • page_number int -
  • next_page_number int -

listen.notes: GetEpisodeRecommendationsResponse

Fields

listen.notes: GetEpisodesInBatchForm

Fields
  • ids string - Comma-separated list of episode ids.

listen.notes: GetEpisodesInBatchResponse

Fields

listen.notes: GetGenresResponse

Fields

listen.notes: GetLanguagesResponse

Fields

listen.notes: GetPodcastRecommendationsResponse

Fields

listen.notes: GetPodcastsInBatchForm

Fields
  • ids? string - Comma-separated list of podcast ids.
  • rsses? string - Comma-separated rss urls.
  • itunes_ids? string - Comma-separated itunes ids.
  • show_latest_episodes? int - Whether or not to fetch up to 10 latest episodes from these podcasts, sorted by pub_date. 1 is yes, and 0 is no.
  • next_episode_pub_date? 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 10 episodes.

listen.notes: GetPodcastsInBatchResponse

Fields
  • latest_episodes? EpisodeSimple[] - Up to 10 latest episodes from these podcasts, sorted by pub_date. This field shows up only when show_latest_episodes is 1.

listen.notes: GetRegionsResponse

Fields
  • regions record {} -

listen.notes: PlaylistItem

An item in a playlist

Fields
  • id? int - Playlist item id.
  • 'type? string - 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.
  • notes? string - Notes for this item.
  • added_at_ms? int - Timestamp (in milliseconds) when this item is added.

listen.notes: PlaylistResponse

Fields
  • last_timestamp_ms? PlaylistLastTimestampMsField - Passed to the last_timestamp_ms parameter of GET /playlists/{id} to paginate through items of that playlist.
  • total? int - Total number of items in this playlist.
  • 'type? string - The type of this playlist, which should be either episode_list or podcast_list.

listen.notes: PlaylistsResponse

Fields
  • previous_page_number? int -
  • page_number? int -
  • next_page_number? int -

listen.notes: PlaylistsresponsePlaylists

A playlist

Fields
  • episode_count? int - The number of episodes (including custom audio) in this playlist.
  • podcast_count? int - The number of podcasts in this playlist.
  • last_timestamp_ms? PlaylistLastTimestampMsField - Passed to the last_timestamp_ms parameter of GET /playlists/{id} to paginate through items of that playlist.

listen.notes: PodcastExtraField

Fields
  • youtube_url? string - YouTube url affiliated with this podcast
  • facebook_handle? string - Facebook username affiliated with this podcast
  • instagram_handle? string - Instagram username affiliated with this podcast
  • twitter_handle? string - Twitter username affiliated with this podcast
  • wechat_handle? string - WeChat username affiliated with this podcast
  • patreon_handle? string - Patreon username affiliated with this podcast
  • google_url? string - Google Podcasts url for this podcast
  • linkedin_url? string - LinkedIn url affiliated with this podcast
  • spotify_url? string - Spotify url for this podcast
  • url1? string - Url affiliated with this podcast
  • url2? string - Url affiliated with this podcast
  • url3? string - Url affiliated with this podcast

listen.notes: PodcastFull

Fields
  • explicit_content? ExplicitField - Whether this podcast contains explicit language.
  • earliest_pub_date_ms? EarliestPubDateMsField - The published date of the oldest episode of this podcast. In milliseconds
  • rss? RssField - RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan.
  • latest_pub_date_ms? LatestPubDateMsField - The published date of the latest episode of this podcast. In milliseconds
  • language? LanguageField - The language of this podcast. You can get all supported languages from GET /languages.
  • 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).
  • country? CountryField - The country where this podcast is produced.
  • next_episode_pub_date? NextEpisodePubDateField - Passed to the next_episode_pub_date parameter of GET /podcasts/{id} to paginate through episodes of that podcast.
  • listen_score? 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
  • listen_score_global_rank? 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

listen.notes: PodcastLookingForField

Fields
  • cohosts? boolean - Whether this podcast is looking for cohosts.
  • cross_promotion? 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.

listen.notes: 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).
  • listen_score? 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
  • listen_score_global_rank? 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

listen.notes: PodcastSearchResult

When type is podcast.

Fields
  • rss? RssField - RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan.
  • description_highlighted? string - Highlighted segment of podcast description
  • description_original? string - Plain text of podcast description
  • 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).
  • latest_pub_date_ms? LatestPubDateMsField - The published date of the latest episode of this podcast. In milliseconds
  • earliest_pub_date_ms? EarliestPubDateMsField - The published date of the oldest episode of this podcast. In milliseconds
  • email? EmailField - The email of this podcast's producer. This field is available only in the PRO/ENTERPRISE plan.
  • explicit_content? ExplicitField - Whether this podcast contains explicit language.
  • listen_score? 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
  • listen_score_global_rank? 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

listen.notes: PodcastSimple

Fields
  • explicit_content? ExplicitField - Whether this podcast contains explicit language.
  • earliest_pub_date_ms? EarliestPubDateMsField - The published date of the oldest episode of this podcast. In milliseconds
  • rss? RssField - RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan.
  • latest_pub_date_ms? LatestPubDateMsField - The published date of the latest episode of this podcast. In milliseconds
  • language? LanguageField - The language of this podcast. You can get all supported languages from GET /languages.
  • 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).
  • country? CountryField - The country where this podcast is produced.
  • listen_score? 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
  • listen_score_global_rank? 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

listen.notes: PodcastTypeaheadResult

Fields
  • explicit_content? ExplicitField - Whether this podcast contains explicit language.
  • 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).

listen.notes: ProxyConfig

Closed record

Proxy server configurations to be used with the HTTP client endpoint.

Fields
  • host string(default "") - Host name of the proxy server
  • port int(default 0) - Proxy server port
  • userName string(default "") - Proxy server username
  • password string(default "") - Proxy server password

listen.notes: SearchResponse

Fields
  • next_offset? int - Pass this value to the offset parameter to do pagination of search results.
  • 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.

listen.notes: 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.

listen.notes: SubmitPodcastResponse

Fields
  • status string - The status of this submission.

listen.notes: TypeaheadResponse

Fields
  • terms string[] - Search term suggestions.
  • genres? Genre[] - Genre suggestions. It'll show up when the show_genres parameter is 1.
  • podcasts? PodcastTypeaheadResult[] - Podcast suggestions. It'll show up when the show_podcasts parameter is 1.

Array types

listen.notes: GenreIdsField

int[]

GenreIdsField

Array of genre ids.

String types

listen.notes: PodcastTitleOriginalField

string

PodcastTitleOriginalField

Plain text of podcast name.

listen.notes: PlaylistThumbnailField

string

PlaylistThumbnailField

Low resolution image url of the playlist.

listen.notes: EpisodeNameField

string

EpisodeNameField

Episode name.

listen.notes: PodcastTypeField

string

PodcastTypeField

The type of this podcast - episodic or serial.

listen.notes: PlaylistNameField

string

PlaylistNameField

Playlist name.

listen.notes: EpisodeImageField

string

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).

listen.notes: CuratedDescriptionField

string

CuratedDescriptionField

This curated list's description.

listen.notes: CountryField

string

CountryField

The country where this podcast is produced.

listen.notes: PublisherField

string

PublisherField

Podcast publisher name.

listen.notes: ImageField

string

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).

listen.notes: EpisodeDescriptionField

string

EpisodeDescriptionField

Html of this episode's full description

listen.notes: CuratedSourceDomainField

string

CuratedSourceDomainField

The domain name of the source of this curated list.

listen.notes: PlaylistImageField

string

PlaylistImageField

High resolution image url of the playlist.

listen.notes: PlaylistVisibilityField

string

PlaylistVisibilityField

Visibility of this playlist.

listen.notes: PodcastDescriptionField

string

PodcastDescriptionField

Html of this episode's full description

listen.notes: ListenScoreGlobalRankField

string

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

listen.notes: PublisherOriginalField

string

PublisherOriginalField

Plain text of this podcast's publisher name.

listen.notes: AudioField

string

AudioField

Audio url of this episode, which can be played directly.

listen.notes: PodcastTitleHighlightedField

string

PodcastTitleHighlightedField

Highlighted segment of podcast name.

listen.notes: ThumbnailField

string

ThumbnailField

Thumbnail image url for this podcast's artwork (300x300).

listen.notes: TranscriptField

string

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.

listen.notes: PlaylistListennotesUrlField

string

PlaylistListennotesUrlField

The url of this playlist on ListenNotes.com.

listen.notes: EpisodeIdField

string

EpisodeIdField

Episode id.

listen.notes: WebsiteField

string

WebsiteField

Website url of this podcast.

listen.notes: PlaylistIdField

string

PlaylistIdField

A 11-character playlist id.

listen.notes: LinkField

string

LinkField

Web link of this episode.

listen.notes: RssField

string

RssField

RSS url of this podcast. This field is available only in the PRO/ENTERPRISE plan.

listen.notes: CuratedNameField

string

CuratedNameField

Curated list name.

listen.notes: LanguageField

string

LanguageField

The language of this podcast. You can get all supported languages from GET /languages.

listen.notes: CuratedIdField

string

CuratedIdField

Curated list id.

listen.notes: EpisodeLNEditUrlField

string

EpisodeLNEditUrlField

Edit url of this episode where you can update the audio url if you find the audio is broken.

listen.notes: PublisherHighlightedField

string

PublisherHighlightedField

Highlighted segment of this podcast's publisher name.

listen.notes: PlaylistDescriptionField

string

PlaylistDescriptionField

Playlist description.

listen.notes: EmailField

string

EmailField

The email of this podcast's producer. This field is available only in the PRO/ENTERPRISE plan.

listen.notes: PodcastNameField

string

PodcastNameField

Podcast name.

listen.notes: CuratedLNUrlField

string

CuratedLNUrlField

The url of this curated list on ListenNotes.com.

listen.notes: CuratedSourceUrlField

string

CuratedSourceUrlField

Url of the source of this curated list.

listen.notes: BestPodcastsLNUrlField

string

BestPodcastsLNUrlField

Url of the list of best podcasts on ListenNotes.com.

listen.notes: EpisodeLNUrlField

string

EpisodeLNUrlField

The url of this episode on ListenNotes.com.

listen.notes: EpisodeThumbnailField

string

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.

listen.notes: PodcastLNUrlField

string

PodcastLNUrlField

The url of this podcast on ListenNotes.com.

listen.notes: PodcastIdField

string

PodcastIdField

Podcast id.

Integer types

listen.notes: AudioLengthSecField

int

AudioLengthSecField

Audio length of this episode. In seconds.

listen.notes: EarliestPubDateMsField

int

EarliestPubDateMsField

The published date of the oldest episode of this podcast. In milliseconds

listen.notes: EpisodePubDateMsField

int

EpisodePubDateMsField

Published date for this episode. In millisecond.

listen.notes: ListenScoreField

int

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

listen.notes: ITunesIdField

int

ITunesIdField

iTunes id for this podcast.

listen.notes: CuratedTotalPodcastsField

int

CuratedTotalPodcastsField

The total number of podcasts in this curated list.

listen.notes: TotalEpisodesField

int

TotalEpisodesField

Total number of episodes in this podcast.

listen.notes: NextEpisodePubDateField

int

NextEpisodePubDateField

Passed to the next_episode_pub_date parameter of GET /podcasts/{id} to paginate through episodes of that podcast.

listen.notes: PlaylistLastTimestampMsField

int

PlaylistLastTimestampMsField

Passed to the last_timestamp_ms parameter of GET /playlists/{id} to paginate through items of that playlist.

listen.notes: LatestPubDateMsField

int

LatestPubDateMsField

The published date of the latest episode of this podcast. In milliseconds

listen.notes: CuratedPubDateMsField

int

CuratedPubDateMsField

Published date of this curated list. In milliseconds.

Boolean types

listen.notes: IsClaimedField

boolean

IsClaimedField

Whether this podcast is claimed by its producer on ListenNotes.com.

listen.notes: ExplicitField

boolean

ExplicitField

Whether this podcast contains explicit language.

listen.notes: MaybeAudioInvalidField

boolean

MaybeAudioInvalidField

Whether or not this episode's audio is invalid. Podcasters may delete the original audio.

Import

import ballerinax/listen.notes;Copy

Other versions

1.5.2

1.5.11.5.01.4.01.2.0
See more...

Metadata

Released date: 1 day ago

Version: 1.5.2

License: Apache-2.0

Compatibility

Platform: any

Ballerina version: 2201.8.0

GraalVM compatible: Yes

Pull count

Total: 26

Current verison: 0

Weekly downloads

Source repository

Keywords

Type/Connector

Vendor/Listen Notes

Area/Storage & File Management

Content & Files/Video & Audio

Cost/Freemium

Contributors

Dependencies

ballerina/url/2.4.0ballerina/http/2.10.24

Terms of service

Privacy policy

Cookie policy

Delete policy

© 2026 WSO2 LLC