Music

Search the catalogue

GET/v1/music/search

No API keyRate-limited

Searches the Apple Music catalogue. Results are grouped by type: one key for each type you asked for that had matches.

Parameters#

Query parameters#

Name	Type	Description
qrequired	string	What to search for. At least two characters; only the first 120 are used. Example: `discovery daft punk`
types	string default album,artist,song	Comma-separated: any of `album`, `artist` and `song`. Example: `album,song`
limit	integer default 10	How many items to return. Default 10, at most 25. Larger values are capped at 25; anything that is not a positive whole number gives the default.

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/search?q=discovery%20daft%20punk&types=album%2Csong"

const response = await fetch('https://api.rankdmusic.app/v1/music/search?q=discovery%20daft%20punk&types=album%2Csong');
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/search?q=discovery%20daft%20punk&types=album%2Csong")!
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/search?q=discovery%20daft%20punk&types=album%2Csong", 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 MusicSearchResults, and meta is a Meta.

Field	Type	Description
album	array of MusicSummary
artist	array of MusicSummary
song	array of MusicSummary

Responses#

200Matches, grouped by type.

Captured from production: GET /v1/music/search?q=discovery%20daft%20punk&types=album,song&limit=1

200 response

{
  "data": {
    "song": [
      {
        "provider": "apple_music",
        "type": "song",
        "id": "697195633",
        "title": "Digital Love",
        "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",
        "releaseYear": 2001
      }
    ],
    "album": [
      {
        "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",
        "releaseYear": 2001
      }
    ]
  },
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

400q is shorter than two characters.

Captured from production: GET /v1/music/search?q=a

400 response

{
  "error": {
    "code": "invalid_query",
    "message": "Search for at least two characters."
  }
}

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"
}

503The catalogue is not configured on this deployment.

503 response

{
  "error": {
    "code": "catalogue_unavailable",
    "message": "The music catalogue is not configured on this deployment."
  }
}