Web Service Endpoint

Get Catalog Charts

Fetch one or more charts from the Apple Music Catalog.

URL

GET https://api.music.apple.com/v1/catalog/{storefront}/charts

Path Parameters

storefront
string
(Required)

An iTunes Store territory, specified by an ISO 3166 alpha-2 country code. The possible values are the id attributes of Storefront objects.

Query Parameters

types
[string]

A list of the types of charts to include in the results. The possible values are albums, songs, and music-videos.

l
string

The localization to use, specified by a language tag. The possible values are in the supportedLanguageTags array belonging to the Storefront object specified by storefront. Otherwise, the storefront’s defaultLanguageTag is used.

chart
string

The chart to fetch for the specified types. For possible values, get all the charts by sending this endpoint without the chart parameter. The possible values for this parameter are the chart attributes of the Chart objects in the response.

genre
string

The identifier for the genre to use in the chart results.

limit
number

The number of resources to include per chart. The default value is 20 and the maximum value is 50.

offset
string

(Optional; only appears when chart is specified) The next page or group of objects to fetch.

Response Codes

200 OK
OK

The request was successful.

Discussion

If successful, the HTTP status code is 200 (OK) and the response contains an object where results contains chart collections. The members for the collections are the chart types in the request and the values are Chart objects. The data member of each Chart object contains an array of the corresponding resource ordered by popularity. For example, if the songs chart type is specified in the request, the object contains a songs member whose value is a Chart object that contains Song objects. This response may be paginated. See Fetch Resources by Page.

If unsuccessful, the HTTP status code indicates the error and the details are in the errors array. See Handle a Response.

Example

https://api.music.apple.com/v1/catalog/us/charts?types=songs,albums,playlists&genre=20&limit=1
{ "results": { "albums": [ { "chart": "most-played", "data": [ { "attributes": { "artistName": "Paramore", "artwork": { "bgColor": "fffffd", "height": 1425, "textColor1": "1a1918", "textColor2": "262625", "textColor3": "474746", "textColor4": "515150", "url": "https://example.mzstatic.com/image/thumb/Music2/v4/2a/5b/83/2a5b8300-a511-2b3a-8a52-aa9936f78507/075679955005.jpeg/{w}x{h}bb.jpeg", "width": 1425 }, "copyright": "\u2117 2007 Atlantic Recording Corporation for the United States and WEA International Inc. for the world outside of the United States. All Rights Reserved.", "editorialNotes": { "short": "The Tennessee four-piece\u2019s second album is full of emotive pop-punk thrills.", "standard": "Thank goodness for Paramore: With their second album, they continue to combine the giddy thrash of Fall Out Boy with the sophisticated emo of their label, Fueled by Ramen, sparked by the firecracker presence of frontwoman Hayley Williams. Until Paramore appeared, emo had been almost entirely dominated by male perspectives. Here, Williams brings a much-needed female outlook to the genre\u2014and some serious nerve, in the case of boyfriend-stealing anthem \u201cMisery Business\u201d\u2014along with the ability to sing like a demon (\u201cMiracle\u201d) and an angel (ballad \u201cWhen It Rains\u201d)." }, "genreNames": [ "Alternative", "Music", "Punk" ], "isComplete": true, "isMasteredForItunes": true, "isSingle": false, "name": "Riot!", "playParams": { "id": "604804755", "kind": "album" }, "recordLabel": "Fueled By Ramen/Atlantic", "releaseDate": "2007-06-12", "trackCount": 11, "url": "https://itunes.apple.com/us/album/riot/604804755" }, "href": "/v1/catalog/us/albums/604804755", "id": "604804755", "type": "albums" } ], "href": "/v1/catalog/us/charts?chart=most-played&genre=20&limit=1&types=albums", "name": "Top Albums", "next": "/v1/catalog/us/charts?chart=most-played&genre=20&limit=1&offset=1&types=albums" } ], "playlists": [ { "chart": "most-played", "href": "/v1/catalog/us/charts?chart=most-played&genre=20&limit=1&types=playlists", "name": "Top Playlists" } ], "songs": [ { "chart": "most-played", "data": [ { "attributes": { "albumName": "Up Next Session: Billie Eilish", "artistName": "Billie Eilish", "artwork": { "bgColor": "000022", "height": 1800, "textColor1": "ffffff", "textColor2": "efb66e", "textColor3": "cbccd2", "textColor4": "bf915f", "url": "https://example.mzstatic.com/image/thumb/Music128/v4/d1/9f/14/d19f147a-cf71-ff9c-a764-1c56245288ca/source/{w}x{h}bb.jpeg", "width": 1800 }, "composerName": "Finneas O'Connell & Billie Eilish O'Connell", "discNumber": 1, "durationInMillis": 186973, "genreNames": [ "Alternative", "Music" ], "isrc": "USUM71709384", "name": "bellyache (Live)", "playParams": { "id": "1282152699", "kind": "song" }, "previews": [ { "url": "https://audio-ssl.itunes.apple.com/apple-itms7-assets-us-std-000001/AudioPreview118/v4/a9/36/7b/a9367b3f-c295-99b0-d60b-01aa8e2a784d/mzaf_4775367231644089353.plus.aac.p.m4a" } ], "releaseDate": "2017-09-20", "trackNumber": 1, "url": "https://itunes.apple.com/us/album/bellyache-live/1282152143?i=1282152699" }, "href": "/v1/catalog/us/songs/1282152699", "id": "1282152699", "type": "songs" } ], "href": "/v1/catalog/us/charts?chart=most-played&genre=20&limit=1&types=songs", "name": "Top Songs", "next": "/v1/catalog/us/charts?chart=most-played&genre=20&limit=1&offset=1&types=songs" } ] }}

See Also