Discovery

Rankd Charts

GET/v1/charts

No API keyRate-limited

The community’s weekly chart, built from Rankd ratings: each entry’s rank, how it moved since last week, and its community average.

Parameters#

Query parameters#

Name	Type	Description
type	string default album	What to chart. One of: `album`, `song`, `artist`, `music_video` · Example: `album`
limit	integer default 20	How many items to return. Default 20, at most 50. Larger values are capped at 50; 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/charts?type=album"

const response = await fetch('https://api.rankdmusic.app/v1/charts?type=album');
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/charts?type=album")!
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/charts?type=album", 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 Chart, and meta is a Meta.

Field	Type	Description
typealways	string	What is charted. One of: `album`, `song`, `artist`, `music_video`
windowalways	string	The period ranked. One of: `week`
generatedAt	string (date-time)	When the chart was worked out.
entriesalways	array of object
rank	integer	This week’s position.
previousRank	integer or null	Last week’s position. `null` when new.
movement	string	Which way it moved. One of: `up`, `down`, `same`, `new`
change	integer or null	How many places it moved.
music	MusicSummary
community	object
average	number	Average rating, 0–100.
count	integer	How many ratings.
rankedThisWeek	integer	Ratings made this week.

Responses#

200This week’s chart.

Captured from production: GET /v1/charts?type=album&limit=2

200 response

{
  "data": {
    "type": "album",
    "window": "week",
    "generatedAt": "2026-09-30T11:14:42.709Z",
    "entries": [
      {
        "rank": 1,
        "previousRank": 5,
        "movement": "up",
        "change": 4,
        "music": {
          "type": "album",
          "id": "697194953",
          "title": "Discovery",
          "artistName": "Daft Punk",
          "albumId": null,
          "albumTitle": null,
          "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music221/v4/fd/4a/77/fd4a77db-0ebc-d043-41a2-f32fa1bb0fb4/dj.qrikkdwj.jpg/600x600bb.jpg",
          "releaseYear": 2001
        },
        "community": {
          "average": 97.5,
          "count": 4
        },
        "rankedThisWeek": 2
      },
      {
        "rank": 2,
        "previousRank": 13,
        "movement": "up",
        "change": 11,
        "music": {
          "type": "album",
          "id": "1590368448",
          "title": "Red (Taylor’s Version) [+ A Message from Taylor]",
          "artistName": "Taylor Swift",
          "albumId": null,
          "albumTitle": null,
          "artworkUrl": "https://is1-ssl.mzstatic.com/image/thumb/Music115/v4/15/38/9b/15389bf4-8074-06c3-11ee-655b5453af68/21UM1IM25046.rgb.jpg/600x600bb.jpg",
          "releaseYear": 2021
        },
        "community": {
          "average": 91.3,
          "count": 4
        },
        "rankedThisWeek": 2
      }
    ]
  },
  "meta": {
    "apiVersion": 1,
    "migrationPhase": 3,
    "sourceOfTruth": "per_account"
  }
}

400type is not something Rankd charts.

Captured from production: GET /v1/charts?type=playlist

400 response

{
  "error": {
    "code": "invalid_type",
    "message": "Charts are for album, song, artist or music_video."
  }
}

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