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.
Dependencies¶
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¶
- Matt Palazzolo - GitHub Profile