AppleMusicAPI (apple_music_api v0.3.0)

Elixir client for the Apple Music API.

The public surface is intentionally small:

AppleMusicAPI.search_catalog("The Beatles", types: ["songs", "albums"])
AppleMusicAPI.get_song("123456789")
AppleMusicAPI.get_album("987654321")
AppleMusicAPI.get_artist("111111111")
AppleMusicAPI.get_playlist("222222222")
AppleMusicAPI.get_songs_by_isrc("USUG12002836")
AppleMusicAPI.get_user_playlists()
AppleMusicAPI.token()

Configuration

config :apple_music_api,
  team_id: System.get_env("APPLE_TEAM_ID"),
  key_id: System.get_env("MUSIC_KEY_ID"),
  private_key: System.get_env("MUSIC_PRIVATE_KEY"),
  base_url: "https://api.music.apple.com",
  storefront: "us",
  token_ttl_seconds: 600

Every function also accepts per-call opts that override the application config.

Summary

Types

opts()

response()

Functions

add_to_library(ids, opts \\ [])

Add a resource to the user's library (requires user token).

get_album(id, opts \\ [])

Get an album by ID.

get_albums(ids, opts \\ [])

Get multiple albums by IDs.

get_artist(id, opts \\ [])

Get an artist by ID.

get_artists(ids, opts \\ [])

Get multiple artists by IDs.

get_charts(opts \\ [])

Get charts for a specific type (songs, albums, playlists).

get_playlist(id, opts \\ [])

Get a playlist by ID.

get_playlists(ids, opts \\ [])

Get multiple playlists by IDs.

get_recommendations(opts \\ [])

Get recommendations for the user (requires user token).

get_song(id, opts \\ [])

Get a song by ID.

get_songs(ids, opts \\ [])

Get multiple songs by IDs.

get_songs_by_isrc(isrc, opts \\ [])

Get a song by ISRC (International Standard Recording Code).

get_user_albums(opts \\ [])

Get the user's library albums (requires user token).

get_user_artists(opts \\ [])

Get the user's library artists (requires user token).

get_user_playlist_tracks(playlist_id, opts \\ [])

Get tracks from the user's library playlist (requires user token).

get_user_playlists(opts \\ [])

Get the user's library playlists (requires user token).

get_user_songs(opts \\ [])

Get the user's library songs (requires user token).

list_genres(opts \\ [])

List all genres available in the catalog.

search_catalog(term, opts \\ [])

Search the Apple Music catalog.

token(opts \\ [])

Return a cached-per-call Apple Music access token (after the JWT → token exchange).

Types

opts()

@type opts() :: keyword()

response()

@type response() :: {:ok, map()} | {:error, term()}

Functions

add_to_library(ids, opts \\ [])

@spec add_to_library(map(), opts()) :: :ok | {:error, term()}

Add a resource to the user's library (requires user token).

Parameters

ids: Map of type to list of IDs, e.g., %{songs: ["123"], albums: ["456"]}
opts:
- :user_token - User MusicKit token (required)

Examples

AppleMusicAPI.add_to_library(%{songs: ["123456789"]})

get_album(id, opts \\ [])

@spec get_album(String.t(), opts()) :: response()

Get an album by ID.

Parameters

id: Apple Music album ID
opts: Optional :storefront override

get_albums(ids, opts \\ [])

@spec get_albums([String.t()], opts()) :: response()

Get multiple albums by IDs.

Parameters

ids: List of Apple Music album IDs (max 100)
opts: Optional :storefront override

get_artist(id, opts \\ [])

@spec get_artist(String.t(), opts()) :: response()

Get an artist by ID.

Parameters

id: Apple Music artist ID
opts: Optional :storefront override

get_artists(ids, opts \\ [])

@spec get_artists([String.t()], opts()) :: response()

Get multiple artists by IDs.

Parameters

ids: List of Apple Music artist IDs (max 100)
opts: Optional :storefront override

get_charts(opts \\ [])

@spec get_charts(opts()) :: response()

Get charts for a specific type (songs, albums, playlists).

Parameters

opts:
- :types - List of types to get charts for ["songs", "albums", "playlists"]
- :storefront - Storefront code
- :chart - Chart ID (optional)

Examples

AppleMusicAPI.get_charts(types: ["songs", "albums"])

get_playlist(id, opts \\ [])

@spec get_playlist(String.t(), opts()) :: response()

Get a playlist by ID.

Parameters

id: Apple Music playlist ID
opts: Optional :storefront override

get_playlists(ids, opts \\ [])

@spec get_playlists([String.t()], opts()) :: response()

Get multiple playlists by IDs.

Parameters

ids: List of Apple Music playlist IDs (max 100)
opts: Optional :storefront override

get_recommendations(opts \\ [])

@spec get_recommendations(opts()) :: response()

Get recommendations for the user (requires user token).

Parameters

opts:
- :user_token - User MusicKit token (required)
- :limit - Maximum results (default 10)

get_song(id, opts \\ [])

@spec get_song(String.t(), opts()) :: response()

Get a song by ID.

Parameters

id: Apple Music song ID
opts: Optional :storefront override

get_songs(ids, opts \\ [])

@spec get_songs([String.t()], opts()) :: response()

Get multiple songs by IDs.

Parameters

ids: List of Apple Music song IDs (max 100)
opts: Optional :storefront override

get_songs_by_isrc(isrc, opts \\ [])

@spec get_songs_by_isrc(String.t(), opts()) :: response()

Get a song by ISRC (International Standard Recording Code).

Parameters

isrc: ISRC code (e.g., "USUG12002836")
opts: Optional :storefront override

get_user_albums(opts \\ [])

@spec get_user_albums(opts()) :: response()

Get the user's library albums (requires user token).

Parameters

opts:
- :user_token - User MusicKit token (required)
- :limit - Maximum results (default 25)
- :offset - Pagination offset

get_user_artists(opts \\ [])

@spec get_user_artists(opts()) :: response()

Get the user's library artists (requires user token).

Parameters

opts:
- :user_token - User MusicKit token (required)
- :limit - Maximum results (default 25)
- :offset - Pagination offset

get_user_playlist_tracks(playlist_id, opts \\ [])

@spec get_user_playlist_tracks(String.t(), opts()) :: response()

Get tracks from the user's library playlist (requires user token).

Parameters

playlist_id: Library playlist ID
opts:
- :user_token - User MusicKit token (required)
- :limit - Maximum results (default 25)

get_user_playlists(opts \\ [])

@spec get_user_playlists(opts()) :: response()

Get the user's library playlists (requires user token).

Parameters

opts:
- :user_token - User MusicKit token (required)
- :limit - Maximum results (default 25)
- :offset - Pagination offset

get_user_songs(opts \\ [])

@spec get_user_songs(opts()) :: response()

Get the user's library songs (requires user token).

Parameters

opts:
- :user_token - User MusicKit token (required)
- :limit - Maximum results (default 25)
- :offset - Pagination offset

list_genres(opts \\ [])

@spec list_genres(opts()) :: response()

List all genres available in the catalog.

Parameters

opts: Optional :storefront override

search_catalog(term, opts \\ [])

@spec search_catalog(String.t(), opts()) :: response()

Search the Apple Music catalog.

Parameters

term: Search query term
opts:
- :types - List of resource types to search ("songs", "albums", "artists", "playlists")
- :limit - Maximum results per type (1-25, default 5)
- :offset - Pagination offset
- :storefront - Storefront code (default from config or "us")

Examples

AppleMusicAPI.search_catalog("The Beatles", types: ["songs", "albums"])
AppleMusicAPI.search_catalog("rock", types: ["playlists"], limit: 10)

token(opts \\ [])

@spec token(opts()) :: {:ok, String.t()} | {:error, term()}

Return a cached-per-call Apple Music access token (after the JWT → token exchange).