iTunesSearchAPIClient

class minim.api.apple.iTunesSearchAPIClient(*, enable_cache: bool = True, limit_rate: bool = True, user_agent: str | None = None)

Bases: APIClient

iTunes Search API client.

Parameters:

enable_cachebool; keyword-only; default: True

Whether to enable an in-memory time-to-live (TTL) cache with a least recently used (LRU) eviction policy for this client.

limit_ratebool; keyword-only; default: True

Whether to enable a token bucket rate limiter for this client.

user_agentstr; keyword-only; optional

User-Agent value to include in the headers of HTTP requests.

Methods

clear_cache	Clear specific or all cache entries for this client.
close	Terminate the underlying HTTP client session.
lookup	Get Apple catalog information for albums, artists, audiobooks, ebooks, movies, music, music videos, podcasts, and television shows using their iTunes IDs, All Music Guide (AMG) IDs, Universal Product Codes (UPCs), European Article Numbers (EANs), or International Standard Book Numbers (ISBNs).
open	Initialize a new HTTP client session.
search	Search for audiobooks, ebooks, movies, music, music videos, podcasts, and/or television shows in the Apple catalog.
set_cache_enabled	Enable or disable the in-memory TTL cache for this client.

Attributes

BASE_URL

Base URL for API endpoints.

BASE_URL: str = 'https://itunes.apple.com'

Base URL for API endpoints.

clear_cache(endpoint_methods: str | Callable[..., Any] | Collection[str | Callable[..., Any]] | None = None, /) → None

Clear specific or all cache entries for this client.

Warning

If endpoint_methods is not provided, all cache entries are cleared.

Parameters:

endpoint_methodsstr, Callable, or Collection[str | Callable]; positional-only; optional

Endpoint methods whose cache entries should be cleared.

close() → None

Terminate the underlying HTTP client session.

lookup(*, itunes_ids: int | str | Collection[int | str] | None = None, amg_album_ids: int | str | Collection[int | str] | None = None, amg_artist_ids: int | str | Collection[int | str] | None = None, amg_video_ids: int | str | Collection[int | str] | None = None, bundle_ids: str | Collection[str] | None = None, isbns: int | str | Collection[int | str] | None = None, barcodes: int | str | Collection[int | str] | None = None, item_type: str | None = None, limit: int | str | None = None, order: str | None = None) → dict[str, Any]

Get Apple catalog information for albums, artists, audiobooks, ebooks, movies, music, music videos, podcasts, and television shows using their iTunes IDs, All Music Guide (AMG) IDs, Universal Product Codes (UPCs), European Article Numbers (EANs), or International Standard Book Numbers (ISBNs).

Important

Exactly one of itunes_ids, amg_album_ids, amg_artist_ids, amg_video_ids, bundle_ids, isbns, or barcodes must be provided.

Parameters:

itunes_idsint, str, or Collection[int | str]; keyword-only; optional

iTunes IDs.

Examples: 984746615, "1440935756", [984746615, "1440935756"].

amg_album_idsint, str, or Collection[int | str]; keyword-only; optional

AMG album IDs.

Examples: 2025410, "2844399", [2025410, "2844399"].

amg_artist_idsint, str, or Collection[int | str]; keyword-only; optional

AMG artist IDs.

Examples: 472102, "2913530", [472102, "2913530"].

amg_video_idsint, str, or Collection[int | str]; keyword-only; optional

AMG video IDs.

Examples: 17120, "17121", [17122, "17123"].

bundle_idsstr or Collection[str]; keyword-only; optional

App bundle IDs.

Examples: "com.tripadvisor.LocalPicks", ["com.tripadvisor.LocalPicks", "com.yelp.yelpiphone"].

isbnsint, str, or Collection[int | str]; keyword-only; optional

ISBNs.

Examples: 9781637993415, "9781705142110", [9781637993415, "9781705142110"].

barcodesint, str, or Collection[int | str]; keyword-only; optional

Barcodes (UPCs and/or EANs).

Examples: 602448438034, "075678671173", [602448438034, "075678671173"].

item_typestr; keyword-only; optional

Type of item to return.

See also

iTunes Search API documentation (archived) – Available item (or entity) types.

Example: "movieArtist".

limitint; keyword-only; optional

Maximum number of items to return.

Valid range: 1 to 200.

API default: 50.

orderstr; keyword-only; optional

Ordering mode for the items.

Valid value: "recent".

Returns:

itemsdict[str, Any]

Apple metadata for the catalog items.

Sample response

{
  "resultCount": <int>,
  "results": [
    {
      "amgArtistId": <int>,
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl60": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionType": <str>,
      "collectionViewUrl": <str>,
      "contentAdvisoryRating": <str>,
      "copyright": <str>,
      "country": <str>,
      "currency": <str>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "trackCount": <int>,
      "wrapperType": "collection"
    },
    {
      "amgArtistId": <int>,
      "artistId": <int>,
      "artistLinkUrl": <str>,
      "artistName": <str>,
      "artistType": <str>,
      "primaryGenreId": <int>,
      "primaryGenreName": <str>,
      "wrapperType": "artist"
    },
    {
      "amgArtistId": <int>,
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl60": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionPrice": <float>,
      "collectionViewUrl": <str>,
      "copyright": <str>,
      "country": <str>,
      "currency": <str>,
      "description": <str>,
      "previewUrl": <str>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "trackCount": <int>,
      "wrapperType": "audiobook"
    },
    {
      "artistId": <int>,
      "artistIds": <list[int]>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl60": <str>,
      "averageUserRating": <float>,
      "currency": <str>,
      "description": <str>,
      "formattedPrice": <str>,
      "genreIds": <list[str]>,
      "genres": <list[str]>,
      "kind": "ebook",
      "price": <float>,
      "releaseDate": <str>,
      "trackCensoredName": <str>,
      "trackId": <int>,
      "trackName": <str>,
      "trackViewUrl": <str>,
      "userRatingCount": <int>
    },
    {
      "artistName": <str>,
      "artworkUrl100": <str>,
      "artworkUrl30": <str>,
      "artworkUrl60": <str>,
      "artworkUrl600": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionHdPrice": <int>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionPrice": <float>,
      "collectionViewUrl": <str>,
      "contentAdvisoryRating": <str>,
      "country": <str>,
      "currency": <str>,
      "feedUrl": <str>,
      "genreIds": <list[str]>,
      "genres": <list[str]>,
      "kind": "podcast",
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "trackCensoredName": <str>,
      "trackCount": <int>,
      "trackExplicitness": <str>,
      "trackId": <int>,
      "trackName": <str>,
      "trackPrice": <float>,
      "trackTimeMillis": <int>,
      "trackViewUrl": <str>,
      "wrapperType": "track"
    }
    {
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl30": <str>,
      "artworkUrl60": <str>,
      "collectionArtistId": <int>,
      "collectionArtistName": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionPrice": <float>,
      "collectionViewUrl": <str>,
      "country": <str>,
      "currency": <str>,
      "discCount": <int>,
      "discNumber": <int>,
      "isStreamable": <bool>,
      "kind": <str>,
      "previewUrl": <str>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "trackCensoredName": <str>,
      "trackCount": <int>,
      "trackExplicitness": <str>,
      "trackId": <int>,
      "trackName": <str>,
      "trackNumber": <int>,
      "trackPrice": <float>,
      "trackTimeMillis": <int>,
      "trackViewUrl": <str>,
      "wrapperType": "track"
    },
    {
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl30": <str>,
      "artworkUrl60": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionHdPrice": <float>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionPrice": <float>,
      "collectionViewUrl": <str>,
      "contentAdvisoryRating": <str>,
      "country": <str>,
      "currency": <str>,
      "discCount": <int>,
      "discNumber": <int>,
      "kind": "tv-episode",
      "longDescription": <str>,
      "previewUrl": <str>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "shortDescription": <str>,
      "trackCensoredName": <str>,
      "trackCount": <int>,
      "trackExplicitness": <str>,
      "trackHdPrice": <float>,
      "trackId": <int>,
      "trackName": <str>,
      "trackNumber": <int>,
      "trackPrice": <float>,
      "trackTimeMillis": <int>,
      "trackViewUrl": <str>,
      "wrapperType": "track"
    },
    {
      "advisories": <list[str]>,
      "appletvScreenshotUrls": <list[str]>,
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl512": <str>,
      "artworkUrl60": <str>,
      "averageUserRating": <float>,
      "averageUserRatingForCurrentVersion": <float>,
      "bundleId": <str>,
      "contentAdvisoryRating": <str>,
      "currency": <str>,
      "currentVersionReleaseDate": <str>,
      "description": <str>,
      "features": <list[str]>,
      "fileSizeBytes": <str>,
      "formattedPrice": <str>,
      "genreIds": <list[str]>,
      "genres": <list[str]>,
      "ipadScreenshotUrls": <list[str]>,
      "isGameCenterEnabled": <bool>,
      "isVppDeviceBasedLicensingEnabled": <bool>,
      "kind": "software",
      "languageCodesISO2A": <list[str]>,
      "minimumOsVersion": <str>,
      "price": <float>,
      "primaryGenreId": <int>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "releaseNotes": <str>,
      "screenshotUrls": <list[str]>,
      "sellerName": <str>,
      "sellerUrl": <str>,
      "supportedDevices": <list[str]>,
      "trackCensoredName": <str>,
      "trackContentRating": <str>,
      "trackId": <int>,
      "trackName": <str>,
      "trackViewUrl": <str>,
      "userRatingCount": <int>,
      "userRatingCountForCurrentVersion": <int>,
      "version": <str>,
      "wrapperType": "software"
    }
  ]
}

open() → None

Initialize a new HTTP client session.

search(query: str, /, country_code: str, *, media_type: str | None = None, item_type: str | None = None, search_field: str | None = None, limit: int | None = None, locale: str | None = None, api_version: int | None = None, include_explicit: bool | str | None = None) → dict[str, Any]

Search for audiobooks, ebooks, movies, music, music videos, podcasts, and/or television shows in the Apple catalog.

Parameters:

querystr; positional-only

Search query.

Example: "jack johnson".

countrystr

ISO 3166-1 alpha-2 country code.

media_typestr; keyword-only; optional

Media type to search for.

Valid values: "all", "audiobook", "ebook", "movie", "music", "musicVideo", "podcast", "shortFilm", "software", "tvShow".

API default: "all".

item_typestr; keyword-only; optional

Type of item to return for the given media type.

See also

iTunes Search API documentation (archived) – Available item (or entity) types for each media type.

Example: "movieArtist" when media="movie".

API default: Track item type associated with the media type.

search_fieldstr; keyword-only; optional

Field to search within for the given media type.

See also

iTunes Search API documentation (Apple Services Performance Partner Program) – Available search fields (or attributes) for each media type.

Example: "allArtistTerm" when media="all" and entity="allArtist".

limitint; keyword-only; optional

Maximum number of items to return.

Valid range: 1 to 200.

API default: 50.

localestr; keyword-only; optional

IETF BCP 47 language tag consisting of an ISO 639-1 language code and an ISO 3166-1 alpha-2 country code joined by an underscore. If provided, items are returned in the specified language.

Valid values:

• "en_us" – English.

• "ja_jp" – Japanese.

API default: "en_us".

api_versionint; keyword-only; optional

Search result key version.

Valid values: 1, 2.

API default: 2.

include_explicitbool or str; keyword-only; optional

Whether to include explicit content in the results.

Valid values: "Yes" (or True), "No" (or False).

API default: "Yes".

Returns:

resultsdict[str, Any]

Apple metadata for the matching catalog items.

Sample responses

Current key version

{
  "resultCount": <int>,
  "results": [
    {
      "amgArtistId": <int>,
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl60": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionPrice": <float>,
      "collectionViewUrl": <str>,
      "copyright": <str>,
      "country": <str>,
      "currency": <str>,
      "description": <str>,
      "previewUrl": <str>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "trackCount": <int>,
      "wrapperType": "audiobook"
    },
    {
      "artistId": <int>,
      "artistIds": <list[int]>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl60": <str>,
      "averageUserRating": <float>,
      "currency": <str>,
      "description": <str>,
      "formattedPrice": <str>,
      "genreIds": <list[str]>,
      "genres": <list[str]>,
      "kind": "ebook",
      "price": <float>,
      "releaseDate": <str>,
      "trackCensoredName": <str>,
      "trackId": <int>,
      "trackName": <str>,
      "trackViewUrl": <str>,
      "userRatingCount": <int>
    },
    {
      "artistName": <str>,
      "artworkUrl100": <str>,
      "artworkUrl30": <str>,
      "artworkUrl60": <str>,
      "artworkUrl600": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionHdPrice": <int>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionPrice": <float>,
      "collectionViewUrl": <str>,
      "contentAdvisoryRating": <str>,
      "country": <str>,
      "currency": <str>,
      "feedUrl": <str>,
      "genreIds": <list[str]>,
      "genres": <list[str]>,
      "kind": "podcast",
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "trackCensoredName": <str>,
      "trackCount": <int>,
      "trackExplicitness": <str>,
      "trackId": <int>,
      "trackName": <str>,
      "trackPrice": <float>,
      "trackTimeMillis": <int>,
      "trackViewUrl": <str>,
      "wrapperType": "track"
    }
    {
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl30": <str>,
      "artworkUrl60": <str>,
      "collectionArtistId": <int>,
      "collectionArtistName": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionPrice": <float>,
      "collectionViewUrl": <str>,
      "country": <str>,
      "currency": <str>,
      "discCount": <int>,
      "discNumber": <int>,
      "isStreamable": <bool>,
      "kind": <str>,
      "previewUrl": <str>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "trackCensoredName": <str>,
      "trackCount": <int>,
      "trackExplicitness": <str>,
      "trackId": <int>,
      "trackName": <str>,
      "trackNumber": <int>,
      "trackPrice": <float>,
      "trackTimeMillis": <int>,
      "trackViewUrl": <str>,
      "wrapperType": "track"
    },
    {
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl30": <str>,
      "artworkUrl60": <str>,
      "collectionCensoredName": <str>,
      "collectionExplicitness": <str>,
      "collectionHdPrice": <float>,
      "collectionId": <int>,
      "collectionName": <str>,
      "collectionPrice": <float>,
      "collectionViewUrl": <str>,
      "contentAdvisoryRating": <str>,
      "country": <str>,
      "currency": <str>,
      "discCount": <int>,
      "discNumber": <int>,
      "kind": "tv-episode",
      "longDescription": <str>,
      "previewUrl": <str>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "shortDescription": <str>,
      "trackCensoredName": <str>,
      "trackCount": <int>,
      "trackExplicitness": <str>,
      "trackHdPrice": <float>,
      "trackId": <int>,
      "trackName": <str>,
      "trackNumber": <int>,
      "trackPrice": <float>,
      "trackTimeMillis": <int>,
      "trackViewUrl": <str>,
      "wrapperType": "track"
    },
    {
      "advisories": <list[str]>,
      "appletvScreenshotUrls": <list[str]>,
      "artistId": <int>,
      "artistName": <str>,
      "artistViewUrl": <str>,
      "artworkUrl100": <str>,
      "artworkUrl512": <str>,
      "artworkUrl60": <str>,
      "averageUserRating": <float>,
      "averageUserRatingForCurrentVersion": <float>,
      "bundleId": <str>,
      "contentAdvisoryRating": <str>,
      "currency": <str>,
      "currentVersionReleaseDate": <str>,
      "description": <str>,
      "features": <list[str]>,
      "fileSizeBytes": <str>,
      "formattedPrice": <str>,
      "genreIds": <list[str]>,
      "genres": <list[str]>,
      "ipadScreenshotUrls": <list[str]>,
      "isGameCenterEnabled": <bool>,
      "isVppDeviceBasedLicensingEnabled": <bool>,
      "kind": "software",
      "languageCodesISO2A": <list[str]>,
      "minimumOsVersion": <str>,
      "price": <float>,
      "primaryGenreId": <int>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "releaseNotes": <str>,
      "screenshotUrls": <list[str]>,
      "sellerName": <str>,
      "sellerUrl": <str>,
      "supportedDevices": <list[str]>,
      "trackCensoredName": <str>,
      "trackContentRating": <str>,
      "trackId": <int>,
      "trackName": <str>,
      "trackViewUrl": <str>,
      "userRatingCount": <int>,
      "userRatingCountForCurrentVersion": <int>,
      "version": <str>,
      "wrapperType": "software"
    }
  ]
}

Legacy key version

{
  "resultCount": <int>,
  "results": [
    {
      "amgArtistId": <int>,
      "artistId": <int>,
      "artistName": <str>,
      "artworkUrl100": <str>,
      "artworkUrl60": <str>,
      "collectionId": <int>,
      "copyright": <str>,
      "country": <str>,
      "currency": <str>,
      "itemExplicitness": <str>,
      "itemId": <int>,
      "itemLinkUrl": <str>,
      "itemPrice": <str>,
      "primaryGenreId": <int>,
      "primaryGenreName": <str>,
      "releaseDate": <str>,
      "wrapperType": "audiobook"
    },
    {
      "artistLinkUrl": <str>,
      "artistName": <str>,
      "artworkUrl100": <str>,
      "artworkUrl60": <str>,
      "country": <str>,
      "currency": <str>,
      "discCount": <int>,
      "discNumber": <int>,
      "itemCensoredName": <str>,
      "itemExplicitness": <str>,
      "itemLinkUrl": <str>,
      "itemName": <str>,
      "itemParentCensoredName": <str>,
      "itemParentExplicitness": <str>,
      "itemParentLinkUrl": <str>,
      "itemParentName": <str>,
      "itemParentPrice": <str>,
      "itemPrice": <str>,
      "kind": <str>,
      "mediaType": <str>,
      "previewUrl": <str>,
      "primaryGenreName": <str>,
      "trackCount": <int>,
      "trackNumber": <int>,
      "trackTime": <int>,
      "wrapperType": "track"
    },
  ]
}

set_cache_enabled(enable: bool, /) → None

Enable or disable the in-memory TTL cache for this client.

Parameters:

enablebool; positional-only

Whether to enable the cache.