Storefronts and Localization

Pick a country-specific geographic region from which to retrieve catalog information, or retrieve information from the user's personal library.

Overview

Apple Music is a worldwide service that operates in many countries and languages. Content varies from one geographic region to another, so each request must be accompanied by a storefront object, which defines the desired region and the supported languages for that region. For most requests, you specify the storefront associated with the current user, but you may also specify other storefronts as needed. For example, you might specify a storefront that better matches the user's preferred language.

Each storefront has a default language, and may support one or more additional languages. For example, the United States storefront includes American English as the default language, but also includes Mexican Spanish as an additional supported language. Apple Music automatically localizes responses using the storefront's default language, but you can localize to a different language using the l query parameter. The value of that parameter must be one of the values in the supportedLanguageTags attribute of the storefront object. For example, the following request asks the US storefront to return an album in the Mexican Spanish (es-MX) localization.

GET https://api.music.apple.com/v1/catalog/us/albums/310730204?l=es-MX

Topics

Requesting a Catalog Storefront

Get a User's Storefront

Fetch a user’s storefront.

Get a Storefront

Fetch a single storefront by using its identifier.

Get Multiple Storefronts

Fetch one or more storefronts by using their identifiers.

Get All Storefronts

Fetch all the storefronts in alphabetical order.

Handling the Response

object StorefrontResponse

The response to a storefront request.

object Storefront

A Resource object that represents a storefront, an iTunes Store territory that the content is available in.

See Also

Essentials

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.

Handling Relationships and Pagination

Fetch related objects as part of your original request and paginate the results from the Apple Music API.

Common Objects

Understand the base types used to construct the JSON data you receive.