Welcome to apple-music-python’s documentation!

A python wrapper for the Apple Music API.

See the Apple Music API documentation for additional info:

NOTE: This does not support library resources.

Prerequisites

You must have an Apple Developer Account and a MusicKit API Key. See instructions on how to obtain these here: Getting Keys And Creating Tokens.

Installation

python setup.py install

or:

pip install apple-music-python

Example

import applemusicpy

secret_key = 'x'
key_id = 'y'
team_id = 'z'

am = applemusicpy.AppleMusic(secret_key, key_id, team_id)
results = am.search('travis scott', types=['albums'], limit=5)

for item in results['results']['albums']['data']:
    print(item['attributes']['name'])

client Module

class applemusicpy.client.AppleMusic(secret_key, key_id, team_id, proxies=None, requests_session=True, max_retries=10, requests_timeout=None, session_length=12)

This class is used to connect to the Apple Music API and make requests for catalog resources

__init__(secret_key, key_id, team_id, proxies=None, requests_session=True, max_retries=10, requests_timeout=None, session_length=12)
Parameters:
  • proxies – A dictionary of proxies, if needed
  • secret_key – Secret Key provided by Apple
  • key_id – Key ID provided by Apple
  • team_id – Team ID provided by Apple
  • requests_session – Use request Sessions class. Speeds up API calls significantly when set to True
  • max_retries – Maximum amount of times to retry an API call before stopping
  • requests_timeout – Number of seconds requests should wait before timing out
  • session_length – Length Apple Music token is valid, in hours
activities(activity_ids, storefront='us', l=None, include=None)

Get all catalog activity data associated with the IDs provided

Parameters:
  • activity_ids – a list of activity IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog activity data in JSON format

activity(activity_id, storefront='us', l=None, include=None)

Get a catalog Activity by ID

Parameters:
  • activity_id – Activity ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Activity data in JSON format

activity_relationship(activity_id, relationship, storefront='us', limit=None, offset=None)

Get an Activity’s relationship (e.g. playlists)

Parameters:
  • activity_id – Activity ID
  • relationship – Relationship type (e.g. “playlists”)
  • storefront – Apple Music store front
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A List of relationship data in JSON format

album(album_id, storefront='us', l=None, include=None)

Get a catalog Album by ID

Parameters:
  • album_id – Album ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Album data in JSON format

album_relationship(album_id, relationship, storefront='us', l=None, limit=None, offset=None)

Get an Album’s relationship (e.g. list of tracks, or list of artists)

Parameters:
  • album_id – Album ID
  • relationship – Relationship type (e.g. “artists”)
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A List of relationship data in JSON format

albums(album_ids, storefront='us', l=None, include=None)

Get all catalog album data associated with the IDs provided

Parameters:
  • album_ids – a list of album IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog album data in JSON format

apple_curator(apple_curator_id, storefront='us', l=None, include=None)

Get a catalog Apple Curator by ID

Parameters:
  • apple_curator_id – Apple Curator ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Apple Curator data in JSON format

apple_curator_relationship(apple_curator_id, relationship, storefront='us', l=None, limit=None, offset=None)

Get an Apple Curator’s relationship (e.g. playlists)

Parameters:
  • apple_curator_id – Apple Curator ID
  • relationship – Relationship type (e.g. “playlists”)
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A List of relationship data in JSON format

apple_curators(apple_curator_ids, storefront='us', l=None, include=None)

Get all catalog apple curator data associated with the IDs provided

Parameters:
  • apple_curator_ids – a list of apple curator IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog apple curator data in JSON format

artist(artist_id, storefront='us', l=None, include=None)

Get a catalog Artist by ID

Parameters:
  • artist_id – Artist ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Artist data in JSON format

artist_relationship(artist_id, relationship, storefront='us', l=None, limit=None, offset=None)

Get a Artist’s relationship (e.g. song)

Parameters:
  • artist_id – Artist ID
  • relationship – Relationship type (e.g. “songs”)
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A List of relationship data in JSON format

artists(artist_ids, storefront='us', l=None, include=None)

Get all catalog artist data associated with the IDs provided

Parameters:
  • artist_ids – a list of artist IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog artist data in JSON format

charts(storefront='us', chart=None, types=None, l=None, genre=None, limit=None, offset=None)

Get Apple Music Chart data

Parameters:
  • storefront – Apple Music store front
  • chart – Chart ID
  • types – List of resource types (e.g. songs, albums, etc.)
  • l – The localization to use, specified by a language tag. Check API documentation.
  • genre – The genre of the chart
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A list of chart data in JSON format

curator(curator_id, storefront='us', l=None, include=None)

Get a catalog Curator by ID

Parameters:
  • curator_id – Curator ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Curator data in JSON format

curator_relationship(curator_id, relationship, storefront='us', l=None, limit=None, offset=None)

Get a Curator’s relationship (e.g. playlists)

Parameters:
  • curator_id – Curator ID
  • relationship – Relationship type (e.g. “playlists”)
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A List of relationship data in JSON format

curators(curator_ids, storefront='us', l=None, include=None)

Get all curator album data associated with the IDs provided

Parameters:
  • curator_ids – a list of curator IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog curator data in JSON format

generate_token(session_length)

Generate encrypted token to be used by in API requests. Set the class token parameter.

Parameters:session_length – Length Apple Music token is valid, in hours
genre(genre_id, storefront='us', l=None)

Get a catalog Genre by ID

Parameters:
  • genre_id – Genre ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
Returns:

Genre data in JSON format

genres(genre_ids, storefront='us', l=None)

Get all catalog genre data associated with the IDs provided

Parameters:
  • genre_ids – a list of genre IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
Returns:

A list of catalog genre data in JSON format

genres_all(storefront='us', l=None, limit=None, offset=None)

Get all genres

Parameters:
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A list of genre data in JSON format

music_video(music_video_id, storefront='us', l=None, include=None)

Get a catalog Music Video by ID

Parameters:
  • music_video_id – Music Video ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Music Video data in JSON format

music_video_relationship(music_video_id, relationship, storefront='us', l=None, limit=None, offset=None)

Get a Music Videos’s relationship (e.g. list of artists)

Parameters:
  • music_video_id – Music Video ID
  • relationship – Relationship type (e.g. “artists”)
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A List of relationship data in JSON format

music_videos(music_video_ids, storefront='us', l=None, include=None)

Get all catalog music video data associated with the IDs provided

Parameters:
  • music_video_ids – a list of music video IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog music video data in JSON format

music_videos_by_isrc(isrcs, music_video_ids=None, storefront='us', l=None, include=None)

Get all catalog music videos associated with the ISRCs provided

Parameters:
  • isrcs – list of ISRCs
  • music_video_ids – IDs of music videos for additional filtering in conjunction with ISRC
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog music video data in JSON format

playlist(playlist_id, storefront='us', l=None, include=None)

Get a catalog Playlist by ID

Parameters:
  • playlist_id – Playlist ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Playlist data in JSON format

playlist_relationship(playlist_id, relationship, storefront='us', l=None, limit=None, offset=None)

Get a Playlists’s relationship (e.g. list of tracks)

Parameters:
  • playlist_id – Playlist ID
  • relationship – Relationship type (e.g. “tracks”)
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A List of relationship data in JSON format

playlists(playlist_ids, storefront='us', l=None, include=None)

Get all catalog album data associated with the IDs provided

Parameters:
  • playlist_ids – a list of playlist IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog playlist data in JSON format

search(term, storefront='us', l=None, limit=None, offset=None, types=None, hints=False, os='linux')

Query the Apple Music API based on a search term

Parameters:
  • term – Search term
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
  • types – A list of resource types to return (e.g. songs, artists, etc.)
  • hints – Include search hints
  • os – Operating System being used. If search isn’t working on Windows, try os=’windows’.
Returns:

The search results in JSON format

song(song_id, storefront='us', l=None, include=None)

Get a catalog Song by ID

Parameters:
  • song_id – Song ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Song data in JSON format

song_relationship(song_id, relationship, storefront='us', l=None, limit=None, offset=None)

Get a Song’s relationship (e.g. artist)

Parameters:
  • song_id – Song ID
  • relationship – Relationship type (e.g. “artists”)
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A List of relationship data in JSON format

songs(song_ids, storefront='us', l=None, include=None)

Get all catalog song data associated with the IDs provided

Parameters:
  • song_ids – a list of song IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog song data in JSON format

songs_by_isrc(isrcs, song_ids=None, storefront='us', l=None, include=None)

Get all catalog songs associated with the ISRCs provided

Parameters:
  • isrcs – list of ISRCs
  • song_ids – IDs of songs for additional filtering in conjunction with ISRC
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog song data in JSON format

station(station_id, storefront='us', l=None, include=None)

Get a catalog Station by ID

Parameters:
  • station_id – Station ID
  • storefront – Apple Music Storefront
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

Station data in JSON format

stations(station_ids, storefront='us', l=None, include=None)

Get all catalog station data associated with the IDs provided

Parameters:
  • station_ids – a list of station IDs
  • storefront – Apple Music store front
  • l – The localization to use, specified by a language tag. Check API documentation.
  • include – Additional relationships to include in the fetch. Check API documentation.
Returns:

A list of catalog station data in JSON format

storefront(storefront_id, l=None)

Get a Storefront by ID

Parameters:
  • storefront_id – Storefont ID
  • l – The localization to use, specified by a language tag. Check API documentation.
Returns:

Storefront data in JSON format

storefronts(storefront_ids, l=None)

Get all storefront data associated with the IDs provided

Parameters:
  • storefront_ids – a list of storefront IDs
  • l – The localization to use, specified by a language tag. Check API documentation.
Returns:

A list of storefront data in JSON format

storefronts_all(l=None, limit=None, offset=None)

Get all storefronts

Parameters:
  • l – The localization to use, specified by a language tag. Check API documentation.
  • limit – The maximum amount of items to return
  • offset – The index of the first item returned
Returns:

A list of storefront data in JSON format

Versioning

v1.0.0 - Initial Release - 12/15/2018 v1.0.1 - Updated package info on PyPI - 12/16/2018 v1.0.2 - Added Windows search support - 01/21/2019 v1.0.3 - Fixed error handling of HTTPError - 11/03/2019 v1.0.4 - Fixed error with reading token - 01/24/2021

Authors

Indices and tables