SearchAPI#

class minim.itunes.SearchAPI[source]#

Bases: object

iTunes Search API client.

The iTunes Search API allows searching for a variety of content, including apps, iBooks, movies, podcasts, music, music videos, audiobooks, and TV shows within the iTunes Store, App Store, iBooks Store and Mac App Store. It also supports ID-based lookup requests to create mappings between your content library and the digital catalog.

See also

For more information, see the iTunes Search API documentation.

Attributes:
API_URLstr

Base URL for the iTunes Search API.

Methods

lookup

Search for content based on iTunes IDs, AMG IDs, UPCs/EANs, or ISBNs.

search

Search for content using the iTunes Search API.
lookup(id: int | str | list[int | str] = None, *, amg_artist_id: int | str | list[int | str] = None, amg_album_id: int | str | list[int | str] = None, amg_video_id: int | str | list[int | str] = None, bundle_id: str | list[str] = None, upc: int | str | list[int | str] = None, isbn: int | str | list[int | str] = None, entity: str | list[str] = None, limit: int | str = None, sort: str = None) → dict[str, Any][source]#

Search for content based on iTunes IDs, AMG IDs, UPCs/EANs, or ISBNs. ID-based lookups are faster and contain fewer false-positive results.

Parameters:
idint, str, or list, optional

The iTunes ID(s) to lookup.

amg_artist_idint, str, or list, keyword-only, optional

The AMG artist ID(s) to lookup.

amg_album_idint, str, or list, keyword-only, optional

The AMG album ID(s) to lookup.

amg_video_idint, str, or list, keyword-only, optional

The AMG video ID(s) to lookup.

bundle_idstr or list, keyword-only, optional

The Apple bundle ID(s) to lookup.

upcint, str, or list, keyword-only, optional

The UPC(s) to lookup.

isbnint, str, or list, keyword-only, optional

The 13-digit ISBN(s) to lookup.

entitystr or list, keyword-only, optional

The type(s) of results you want returned.

See also

For a list of available entities, see the iTunes Store API Table 2-1.

Default: The track entity associated with the specified media type.

limitint or str, keyword-only, optional

The number of search results you want the iTunes Store to return.

Valid values: limit must be between 1 and 200.

Default: 50.

sortstr, keyword-only, optional

The sort applied to the search results.

Allowed value: "recent".

Returns:
resultsdict

The lookup results.

Sample response

{
  "resultCount": <int>,
  "results": [
    {
      "wrapperType": <str>,
      "kind": <str>,
      "artistId": <int>,
      "collectionId": <int>,
      "trackId": <int>,
      "artistName": <str>,
      "collectionName": <str>,
      "trackName": <str>,
      "collectionCensoredName": <str>,
      "trackCensoredName": <str>,
      "collectionArtistId": <int>,
      "collectionArtistName": <str>,
      "artistViewUrl": <str>,
      "collectionViewUrl": <str>,
      "trackViewUrl": <str>,
      "previewUrl": <str>,
      "artworkUrl30": <str>,
      "artworkUrl60": <str>,
      "artworkUrl100": <str>,
      "collectionPrice": <float>,
      "trackPrice": <float>,
      "releaseDate": <str>,
      "collectionExplicitness": <str>,
      "trackExplicitness": <str>,
      "discCount": <int>,
      "discNumber": <int>,
      "trackCount": <int>,
      "trackNumber": <int>,
      "trackTimeMillis": <int>,
      "country": <str>,
      "currency": <str>,
      "primaryGenreName": <str>,
      "isStreamable": <bool>
    }
  ]
}

Examples

Look up Jack Johnson by iTunes artist ID:

>>> itunes.lookup(909253)

Look up the Yelp application by iTunes ID:

>>> itunes.lookup(284910350)

Look up Jack Johnson by AMG artist ID:

>>> itunes.lookup(amg_artist_id=468749)

Look up multiple artists by their AMG artist IDs:

>>> itunes.lookup(amg_artist_id=[468749, 5723])

Look up all albums for Jack Johnson:

>>> itunes.lookup(909253, entity="album")

Look up multiple artists by their AMG artist IDs and get each artist’s top 5 albums:

>>> itunes.lookup(amg_artist_id=[468749, 5723], entity="album",
...               limit=5)

Look up multiple artists by their AMG artist IDs and get each artist’s 5 most recent songs:

>>> itunes.lookup(amg_artist_id=[468749, 5723], entity="song",
...               limit=5, sort="recent")

Look up an album or video by its UPC:

>>> itunes.lookup(upc=720642462928)

Look up an album by its UPC, including the tracks on that album:

>>> itunes.lookup(upc=720642462928, entity="song")

Look up an album by its AMG Album ID:

>>> itunes.lookup(amg_album_id=[15175, 15176, 15177, 15178,
...                             15183, 15184, 15187, 15190,
...                             15191, 15195, 15197, 15198])

Look up a Movie by AMG Video ID:

>>> itunes.lookup(amg_video_id=17120)

Look up a book by its 13-digit ISBN:

>>> itunes.lookup(isbn=9780316069359)

Look up the Yelp application by iTunes bundle ID:

>>> itunes.lookup(bundle_id="com.yelp.yelpiphone")
search(term: str, *, country: str = None, media: str = None, entity: str | list[str] = None, attribute: str = None, limit: int | str = None, lang: str = None, version: int | str = None, explicit: bool | str = None) → dict[str, Any][source]#

Search for content using the iTunes Search API.

Parameters:
termstr

The text string to search for.

Note

URL encoding replaces spaces with the plus (+) character, and all characters except letters, numbers, periods (.), dashes (-), underscores (_), and asterisks (*) are encoded.

Example: "jack+johnson".

countrystr, keyword-only, optional

The two-letter country code for the store you want to search. The search uses the default store front for the specified country.

See also

For a list of ISO country codes, see the ISO OBP.

Default: "US".

mediastr, keyword-only, optional

The media type you want to search for.

Valid values: "movie", "podcast", "music", "musicVideo", "audioBook", "shortFilm", "tvShow", "software", and "ebook".

Default: "all".

entitystr or list, keyword-only, optional

The type(s) of results you want returned, relative to the specified media type in media.

See also

For a list of available entities, see the iTunes Store API Table 2-1.

Default: The track entity associated with the specified media type.

Example: "movieArtist" for a movie media type search.

attributestr, keyword-only, optional

The attribute you want to search for in the stores, relative to the specified media type (media).

See also

For a list of available attributes, see the iTunes Store API Table 2-2.

Default: All attributes associated with the specified media type.

Example: If you want to search for an artist by name, specify entity="allArtist" and attribute="allArtistTerm". Then, if you search for term="maroon", iTunes returns “Maroon 5” in the search results, instead of all artists who have ever recorded a song with the word “maroon” in the title.

limitint or str, keyword-only, optional

The number of search results you want the iTunes Store to return.

Valid values: limit must be between 1 and 200.

Default: 50.

langstr, keyword-only, optional

The language, English or Japanese, you want to use when returning search results. Specify the language using the five-letter codename.

Valid values:

  • "en_us" for English.

  • "ja_jp" for Japanese.

Default: "en_us".

versionint or str, keyword-only, optional

The search result key version you want to receive back from your search.

Valid values: 1 and 2.

Default: 2.

explicitbool or str, keyword-only, optional

A flag indicating whether or not you want to include explicit content in your search results.

Default: "Yes".

Returns:
resultsdict

The search results.

Sample response

{
  "resultCount": <int>,
  "results": [
    {
      "wrapperType": <str>,
      "kind": <str>,
      "artistId": <int>,
      "collectionId": <int>,
      "trackId": <int>,
      "artistName": <str>,
      "collectionName": <str>,
      "trackName": <str>,
      "collectionCensoredName": <str>,
      "trackCensoredName": <str>,
      "collectionArtistId": <int>,
      "collectionArtistName": <str>,
      "artistViewUrl": <str>,
      "collectionViewUrl": <str>,
      "trackViewUrl": <str>,
      "previewUrl": <str>,
      "artworkUrl30": <str>,
      "artworkUrl60": <str>,
      "artworkUrl100": <str>,
      "collectionPrice": <float>,
      "trackPrice": <float>,
      "releaseDate": <str>,
      "collectionExplicitness": <str>,
      "trackExplicitness": <str>,
      "discCount": <int>,
      "discNumber": <int>,
      "trackCount": <int>,
      "trackNumber": <int>,
      "trackTimeMillis": <int>,
      "country": <str>,
      "currency": <str>,
      "primaryGenreName": <str>,
      "isStreamable": <bool>
    }
  ]
}

Examples

To search for all Jack Johnson audio and video content (movies, podcasts, music, music videos, audiobooks, short films, and TV shows),

>>> itunes.search("jack johnson")

To search for all Jack Johnson audio and video content and return only the first 25 items,

>>> itunes.search("jack johnson", limit=25)

To search for only Jack Johnson music videos,

>>> itunes.search("jack johnson", entity="musicVideo")

To search for all Jim Jones audio and video content and return only the results from the Canada iTunes Store,

>>> itunes.search("jack johnson", country="ca")

To search for applications titled “Yelp” and return only the results from the United States iTunes Store,

>>> itunes.search("yelp", country="us", entity="software")