Music

Get an album, song or artist

GET/v1/music/{type}/{id}

No API keyRate-limited

One catalogue item as Rankd shows it: Apple Music’s details plus Rankd’s community numbers. Which fields are filled in depends on type. An album has tracks; an artist has albums, singles, topSongs and similarArtists; a song has its album. Fields that do not apply are empty arrays or null.

Parameters#

Path parameters#

Name	Type	Description
typerequired	string	What kind of catalogue item. One of: `album`, `song`, `artist` · Example: `album`
idrequired	string	The Apple Music catalogue id. Pattern: `^[0-9]{1,15}$` · Example: `697194953`

Try it#

Sends a real request to the production API through this site. No credentials are used, so you see exactly what anyone would.

Request#

curl "https://api.rankdmusic.app/v1/music/album/697194953"

const response = await fetch('https://api.rankdmusic.app/v1/music/album/697194953');
const body = await response.json();

if (!response.ok) {
  const code = typeof body.error === 'string' ? body.error : body.error.code;
  throw new Error(`Rankd API ${response.status}: ${code}`);
}

const { data, meta } = body;

import Foundation

let url = URL(string: "https://api.rankdmusic.app/v1/music/album/697194953")!
let (data, response) = try await URLSession.shared.data(from: url)

guard let http = response as? HTTPURLResponse, http.statusCode == 200 else {
    throw URLError(.badServerResponse)
}

let body = try JSONSerialization.jsonObject(with: data) as? [String: Any]
let result = body?["data"]

import requests

response = requests.get("https://api.rankdmusic.app/v1/music/album/697194953", timeout=10)
body = response.json()

if not response.ok:
    error = body["error"]
    raise RuntimeError(error if isinstance(error, str) else error["code"])

data = body["data"]

Response#

A successful response is { "data": …, "meta": … }. data is a MusicItem, and meta is a Meta.

Field	Type	Description
musicalways	MusicRef
artworkTemplate	string or null	Artwork with `{w}x{h}` in place of the size.
releaseDate	string or null	Release date, `YYYY-MM-DD`.
releaseYear	integer or null	Release year.
genreNames	array of string	Apple’s genres.
trackCount	integer or null	For albums: how many tracks.
tracks	array of MusicSummary	For albums: the tracklist.
artistId	string or null	For albums and songs: the lead artist’s id.
albums	array of MusicSummary	For artists: their albums.
singles	array of MusicSummary	For artists: their singles and EPs.
topSongs	array of MusicSummary	For artists: their most popular songs.
similarArtists	array of MusicSummary	For artists: artists like them.
album	MusicSummary or null	For songs: the album they are from.
about	string or null	Apple’s editorial notes, as plain text.
recordLabel	string or null	For albums: the label.
copyright	string or null	For albums: the copyright line.
durationSeconds	integer or null	Length in seconds.
previewUrl	string or null	For songs: Apple’s 30-second preview.
motion	object or null	Where Rankd’s apps look for the album’s animated cover.
storefront	string	Apple Music storefront.
albumId	string	Album id.
catalogueAvailablealways	boolean	Whether Apple Music answered. When `false`, only the details Rankd stored are shown.
communityalways	Community

Responses#

200The item and its community numbers.

Captured from production: GET /v1/music/album/697194953

200 response

{
  "data": {
    "music": {
      "provider": "apple_music",
      "type": "album",
      "id": "697194953",
      "title": "Discovery",
      "artistName": "Daft Punk",
      "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg"
    },
    "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg",
    "releaseDate": "2001-03-12",
    "releaseYear": 2001,
    "genreNames": [
      "Dance",
      "House"
    ],
    "trackCount": 14,
    "tracks": [
      {
        "provider": "apple_music",
        "type": "song",
        "id": "697195462",
        "title": "One More Time",
        "artistName": "Daft Punk",
        "albumTitle": "Discovery",
        "trackNumber": 1,
        "discNumber": 1,
        "durationSeconds": 320,
        "isExplicit": false,
        "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/5d/93/d8/5d93d83f-ad1e-da4d-1d79-9937bdff24ec/mzaf_14396932211949300852.plus.aac.p.m4a",
        "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg",
        "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg"
      },
      {
        "provider": "apple_music",
        "type": "song",
        "id": "697195570",
        "title": "Aerodynamic",
        "artistName": "Daft Punk",
        "albumTitle": "Discovery",
        "trackNumber": 2,
        "discNumber": 1,
        "durationSeconds": 213,
        "isExplicit": false,
        "previewUrl": "https://audio-ssl.itunes.apple.com/itunes-assets/AudioPreview221/v4/0e/ab/8f/0eab8f87-87db-9501-110a-ad681b23ca0f/mzaf_16233060439128880755.plus.aac.p.m4a",
        "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg",
        "artworkTemplate": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/{w}x{h}bb.jpg"
      }
    ],
    "artistId": "5468295",
    "albums": [],
    "singles": [],
    "topSongs": [],
    "similarArtists": [],
    "album": null,
    "about": "100 Best Albums There’s a video that Daft Punk made to promote 2001’s Discovery in which the French duo, wearing their famous robot helmets, dance on the Tokyo subway. Some riders smile and stare, while others look politely away. At the time, Daft Punk were big enough business to dismiss goofing off—their first album, 1997’s Homework, had already sold two million copies. And yet, when asked about Discovery’s turn toward ’70s and ’80s pop, Thomas Bangalter said the goal wasn’t to evoke a specific sound or era, but the raw wonder they’d felt encountering that music as children. Dancing on the subway in a city where they didn’t speak the language, liberated from judgement and self-criticism: It’s all there in the title.\n\nThe album’s biggest singles—“One More Time”, “Harder Better Faster Stronger”, “Digital Love”—were as useful to wedding DJs as they were to pop philosophers. And the rest—the faux-metal guitars of “Aerodynamic”, the sci-fi daydream of “Veridis Quo”, the UK garage showcase of Todd Edwards on “Face to Face”—glimpsed down dozens of stylistic alleyways without disrupting the album’s course. “Electronic music”—a term that always suggested the future, however vague—was demonstrated to be as familiar and comforting as classic rock, and no less real in its depth of feeling.\n\nYou can easily trace Discovery forward to EDM and the continuing entwinement of techno and rock. But you can also trace it back to The Beatles circa Sgt. Pepper’s Lonely Hearts Club Band or The Beach Boys circa Pet Sounds and Smile: music that took pop seriously as art, but also recontextualised older, seemingly uncool styles in ways that felt progressive and fresh. Most of all, though, Daft Punk wanted to be universal. And as implausible as it may have seemed for two French men in robot helmets, Discovery got them there. “We hope all the kids will love the video,” a disembodied voice says near the end of the promo clip. “As well as their parents.”",
    "recordLabel": "Daft Life Ltd./ADA France",
    "copyright": "℗ 2001 Daft Life Limited",
    "durationSeconds": 3668,
    "previewUrl": null,
    "motion": {
      "storefront": "gb",
      "albumId": "697194953"
    },
    "catalogueAvailable": true,
    "community": {
      "ratingCount": 4,
      "averageRating": 98,
      "distribution": [
        0,
        0,
        0,
        0,
        4
      ],
      "reviewCount": 2,
      "myRating": null,
      "myReview": null,
      "snapshot": {
        "title": "Discovery",
        "artistName": "Daft Punk",
        "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg"
      }
    }
  },
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

400type or id is not a music reference Rankd understands.

Captured from production: GET /v1/music/album/abc

400 response

{
  "error": {
    "code": "invalid_music_reference",
    "message": "Not a music reference Rankd understands."
  }
}

404Neither the catalogue nor Rankd knows this item.

Captured from production: GET /v1/music/album/999999999999

404 response

{
  "error": {
    "code": "not_found",
    "message": "That music is not in the catalogue."
  }
}

429Too many requests this minute. Wait Retry-After seconds, then try again.

Headers: Retry-After Seconds to wait. Always 60.

429 response

{
  "error": "rate limited"
}