itunes.search module

This module contains utilities for performing a variety of different searches against the iTunes store API

itunes.search.search_track(query, limit=100, offset=0, order=None, store='US')

Search for a track resource

Parameters:

• query – The query to perform against the iTunes store API
• limit – The max number of responses to return. Default: 100
• offset – The offset into a collection of resources. Default: 0
• order – The key to order a collection of resources by. Possible values are ‘rank’ or ‘popular.’ Default: None
• store – The iTunes store localization to search against. Default: COUNTRY

itunes.search.search_album(query, limit=100, offset=0, order=None, store='US')

Search for an album resource

Parameters:

• query – The query to perform against the iTunes store API
• limit – The max number of responses to return. Default: 100
• offset – The offset into a collection of resources. Default: 0
• order – The key to order a collection of resources by. Possible values are ‘rank’ or ‘popular.’ Default: None
• store – The iTunes store localization to search against. Default: COUNTRY

itunes.search.search_artist(query, limit=100, offset=0, order=None, store='US')

Search for an artist resource

Parameters:

• query – The query to perform against the iTunes store API
• limit – The max number of responses to return. Default: 100
• offset – The offset into a collection of resources. Default: 0
• order – The key to order a collection of resources by. Possible values are ‘rank’ or ‘popular.’ Default: None
• store – The iTunes store localization to search against. Default: COUNTRY

itunes.search.search_app(query, limit=100, offset=0, order=None, store='US')

Search for an app resource

Parameters:

• query – The query to perform against the iTunes store API
• limit – The max number of responses to return. Default: 100
• offset – The offset into a collection of resources. Default: 0
• order – The key to order a collection of resources by. Possible values are ‘rank’ or ‘popular.’ Default: None
• store – The iTunes store localization to search against. Default: COUNTRY

itunes.search.search_episode(query, limit=100, offset=0, order=None, store='US')

Search for a TV Episode resource

Parameters:

• query – The query to perform against the iTunes store API
• limit – The max number of responses to return. Default: 100
• offset – The offset into a collection of resources. Default: 0
• order – The key to order a collection of resources by. Possible values are ‘rank’ or ‘popular.’ Default: None
• store – The iTunes store localization to search against. Default: COUNTRY

itunes.search.search_season(query, limit=100, offset=0, order=None, store='US')

Search for a TV Season resource

Parameters:

• query – The query to perform against the iTunes store API
• limit – The max number of responses to return. Default: 100
• offset – The offset into a collection of resources. Default: 0
• order – The key to order a collection of resources by. Possible values are ‘rank’ or ‘popular.’ Default: None
• store – The iTunes store localization to search against. Default: COUNTRY

itunes.search.search(query, media='all', limit=100, offset=0, order=None, store='US')

Search for any type of resource

Parameters:

• query – The query to perform against the iTunes store API
• limit – The max number of responses to return. Default: 100
• offset – The offset into a collection of resources. Default: 0
• order – The key to order a collection of resources by. Possible values are ‘rank’ or ‘popular.’ Default: None
• store – The iTunes store localization to search against. Default: COUNTRY

itunes.search.search_movie(query, limit=100, offset=0, order=None, store='US')

Search for a Movie resource

Parameters:

• query – The query to perform against the iTunes store API
• limit – The max number of responses to return. Default: 100
• offset – The offset into a collection of resources. Default: 0
• order – The key to order a collection of resources by. Possible values are ‘rank’ or ‘popular.’ Default: None
• store – The iTunes store localization to search against. Default: COUNTRY

class itunes.search.Search(query, country='US', media='all', entity=None, attribute=None, offset=0, limit=50, order=None, lang='en_us', version='2', explicit='Yes')

Bases: itunes.base.BaseObject

Search iTunes Store for a variety of different resource types

resource = 'search'

Example Usage

The itunes.search module is made up of a handful of different utility functions for performing a variety of different searches against the iTunes Store API.

Artist

Searching for an artist is as simple as passing an artist name to the search_artist function

>>> import itunes
>>> results = itunes.search_artist('Frank Sinatra')
>>> frank = results[0]
>>> frank
... '<Artist>: Frank Sinatra'

Albums

To find an artist’s albums, you can either use the search_album or access all of an artists albums via an Artist instance. Continuing from our above example we could do something similar to:

>>> for album in frank.get_albums():
...   print(album)
... <Collection>: Nothing But the Best (Remastered)
... <Collection>: Ultimate Sinatra
... <Collection>: Christmas With the Rat Pack
... <Collection>: Christmas
... <Collection>: A Jolly Christmas from Frank Sinatra (50th Anniversary)
... <Collection>: Sinatra At the Sands
... <Collection>: Classic Sinatra: His Great Performances 1953-1960
... ...

Apps

Apps available from the iTunes store are also available for searching:

>>> app = itunes.search_app('angry birds')[0]
>>> app.ratings
... {'avg': {'all': 4.5,
             'current': 4.0},
     'num': {'all': 823399,
             'current': 504}}

TV Shows

TV Shows are also searchable:

>>> s1 = itunes.search_season('Family Guy Season 1')[0]
>>> s1.release_date
... datetime.datetime(1999, 1, 31, 8, 0)
>>> s1.artwork
... {'60': 'http://is1.mzstatic.com/image/thumb/Music3/v4/60/15/b2/6015b219-e4cb-2a93-0369-c75b5e06e9df/source/60x60bb.jpg',
     '600': 'http://is1.mzstatic.com/image/thumb/Music3/v4/60/15/b2/6015b219-e4cb-2a93-0369-c75b5e06e9df/source/600x600bb.jpg'}
>>> s1.genre
... 'Comedy'