Web Service

Apple Music API

A web services API that lets you integrate streaming music with Apple Music content.

Overview

The Apple Music API is the web services portion of MusicKit. Using the Apple Music API, you can access information about media—such as albums, songs, artists, and playlists—in the Apple Music catalog and in a user’s personal cloud library. If authorized by a user, you can also access or modify data associated with that user. For example, you can find music recommendations for the user or change their rating of a particular song, both in the catalog and in their library.

Requests to the Apple Music API are sent securely using HTTPS commands. All requests to the Apple Music API are associated with your app or website. A request includes a developer token that authenticates you as a trusted developer and member of the Apple Developer Program. Requests that access information for a specific user must also include a music user token that authorizes you to access that user’s information. See Getting Keys and Creating Tokens.

Responses are provided as JSON objects. Apple Music provides a rich object model with many predefined resource types. For example, the Album resource type specifies the data associated with an album. Resources in the Apple Music object model are often related to each other. For example, an album has artists, genres, and tracks, all of which are represented by other object types. See Handling Requests and Responses.

Apple Music is a worldwide service that operates in many countries and languages. However, the available content varies by region. In Apple Music, a region is called a storefront, and each storefront vends a different music catalog. In most cases, a request URL includes a storefront code that specifies which storefront the request should be routed to. For example, when you search for an album, the request specifies a storefront, and the response tells you whether that album is available in that storefront. Choose an appropriate storefront for the user’s location. For example, in an iOS app, you can call StoreKit to find out which storefront the user is logged in to on that device.

With localization, responses are automatically localized in an appropriate language for the storefront you select. Each storefront has a default language, but a storefront can support multiple languages. For example, the United States storefront supports both American English and Mexican Spanish. When you create a request, you can optionally specify that the response should be returned in one of the other languages instead. See Using Storefronts and Localizations.

The Apple Music API balances usefulness with processing time and bandwidth usage. By default, it might not provide all of the information in a single response. For example, when returning a resource that has relationships with other resources, some or all of the information about those relationships might be omitted. Similarly, if a request results in a large number of objects, Apple Music might return a subset of those objects in the initial response and ask you to make subsequent requests to get the rest of the data. If your app has specific needs, you can modify your request so that more information is returned in a single response. See Handling Relationships and Pagination.

Topics

First Steps

Getting Keys and Creating Tokens

Obtain developer tokens and keys needed to make requests to the Apple Music API.

Handling Requests and Responses

Write a request and handle a response from the Apple Music API.

Using Storefronts and Localizations

Get storefront and localization information for the Apple Music catalog.

Handling Relationships and Pagination

Fetch relationships and paginate response results from the Apple Music API.

HTTP Status Codes

Reference error codes returned by the Apple Music API.

Fetch Storefronts

Get a storefront

Fetch a single storefront using its identifier.

Get all storefronts

Fetch all the storefronts in alphabetical order.

Get a user's storefront

Fetch a user’s storefront.

Fetch Resources

Catalog Resources

Get resources from the Apple Music catalog.

Library Resources

Get resources from a user's Cloud Library.

Fetch Charts

Fetch Genres

Get a catalog genre

Fetch a genre using its identifier.

Get catalog top charts genres

Fetch all genres for the current top charts.

Search the Catalog

Search for catalog resources

Search the catalog using a query.

Get catalog search hints

Fetch the search term results for a hint.

Search the Library

Search for library resources

Search the library using a query.

Fetch Recent History

Get heavy rotation content

Fetch the resources in heavy rotation for the user.

Get recently played

Fetch the recently played resources for the user.

Get recent stations

Fetch recently played radio stations for the user.

Get recently added

Fetch the resources recently added to the library.

Modify Library and Library Playlists

Add a resource to a library

Add a catalog resource to a user’s library.

Create a new library playlist

Create a new playlist in a user’s library.

Add tracks to library playlist

Add new tracks to the end of a library playlist.

Manage Ratings

Catalog Ratings

Get, add, and delete ratings for resources in the Apple Music catalog.

Library Ratings

Get, add, and delete ratings for resources in a user's Cloud Library.

Fetch Recommendations

Get a recommendation

Fetch a recommendation using its identifier.

Get multiple recommendations

Fetch one or more recommendations using their identifiers.

Object Models

Apple Music API Objects

Object models for requests, responses, and resources in the Apple Music API.

Endpoints

Get a catalog genre's relationship directly by name

Fetch a genre's relationship using its identifier.