Article

Handling Relationships and Pagination

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

Overview

You can fetch the resources and related objects your app needs in a single request. To get related objects, you fetch specific relationships along with the resource objects. If the query results contain too many objects, you can use pagination to fetch the next set of objects.

Fetch Resource Relationships

To reduce response sizes and improve performance, not all available relationships of a resource object—such as an album, song, playlist, or music video—are included by default. You can include additional related resources in the response by using the include query parameter.

There are three possible default behaviors for fetching resources in relationships:

  • The resources are included, with their attributes, as secondary resource objects.

  • The resources are included, without their attributes, as resource identifiers only.

  • The relationship is omitted from the response entirely and must be explicitly included.

For example, these Album relationships have different default behaviors:

  • The tracks relationship includes the resource objects for the album’s songs and music videos, which are typically essential for working with albums.

  • The artists relationship only includes resource identifiers for the artist or artists associated with the album and excludes the attributes member in each resource object. This relationship allows you to easily link to an artist from an album, although some artist attributes are also attributes of the album.

  • The genres relationship is omitted by default. This relationship is seldom used, and the names of the genres already appear as an attribute of the album, genreNames.

See the corresponding object model reference for the default behavior of other objects.

Use the include parameter to include the resource objects for one or more available relationships in the response. The value of the include parameter is a comma-separated list of the relationship names. Relationships that include resource objects by default don’t have to be specified in the list; they’ll continue to be included along with the specified relationships. For example, when fetching an Artist object, you can request that the playlists objects be included:

GET https://api.music.apple.com/v1/catalog/us/artists/462006?include=playlists

To fetch a relationship exclusively, specify the name of the relationship after the id path parameter. For example, fetch just the tracks belonging to an album:

GET https://api.music.apple.com/v1/catalog/us/albums/310730204/tracks

Not all objects in a relationship are fetched by default. See the corresponding object model reference for the default fetch limits. To specify the number of objects fetched, use the limit resource parameter. For example, you can fetch an artist's first five albums:

GET https://api.music.apple.com/v1/catalog/us/artists/462006/albums?limit=5

Fetch Resources by Page

Some GET requests support pagination of the objects or an object’s relationships. If you specify a limit parameter, the number of resources returned is restricted to that limit. If no limit is supplied, the default limit is used. If you reach the limit to the number of resource objects in a response, the response contains a subset of the resource objects matching your criteria, and more requests are needed to get the rest of the objects.

See the corresponding resource’s object model for the default fetch limit. If there are more resource objects than permitted by the fetch limit, the ResponseRoot object contains a next member whose value is a subpath you use in the next request. The subpath contains the offset parameter that specifies the next page. Similarly, a Relationship object may contain a next member that you use to fetch more objects in a relationship.

For example, fetch all objects of a resource type, but specify the amount in the response by using the limit parameter:

GET https://api.music.apple.com/v1/storefronts?limit=2

If there are more objects to fetch, the response contains a next member:

{
    "data":[
        {
            "attributes":{
                "defaultLanguageTag":"en-gb",
                "name":"Anguilla",
                "supportedLanguageTags":[
                    "en-gb"
                ]
            },
            "href":"/v1/storefronts/ai",
            "id":"ai",
            "type":"storefronts"
        },
        {
            "attributes":{
                "defaultLanguageTag":"en-gb",
                "name":"Antigua and Barbuda",
                "supportedLanguageTags":[
                    "en-gb"
                ]
            },
            "href":"/v1/storefronts/ag",
            "id":"ag",
            "type":"storefronts"
        }
    ],
    "next":"/v1/storefronts?offset=2"
}

Pass the next subpath, and optionally, the limit parameter again, in the next request:

GET https://api.music.apple.com/v1/storefronts?offset=2&limit=2

Continue requesting the resource objects until the next member no longer appears in the response.

See Also

First Steps

About the Apple Music API

Learn how Apple Music data is handled using this API.

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.