API documentation

Quick start

1. Request a key, confirm your email, and once it’s approved, sign in and reveal it.
2. Call the API from your server with the key in the Authorization header:

curl -H "Authorization: Bearer $CHARTVAULT_KEY" \
  "https://www.chartvault.fm/api/v1/charts/H100/issues/1985-07-13"

The base address is https://www.chartvault.fm/api/v1. Every endpoint is a GET and answers in JSON (UTF-8). Add ?pretty=1 to any call for indented output while you explore.

Authentication

Every endpoint except /api/v1 itself needs a key. Send it in a header, either

Authorization: Bearer cv_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

or X-API-Key: cv_live_…. Keys sent in the URL (?api_key=) are refused, because URLs end up in logs and browser histories. Keys start with cv_live_ followed by 32 letters and digits.

Responses

A successful call answers 200 OK with an object holding data (the answer) and meta (about the answer):

{
  "data": { ... } or [ ... ],
  "meta": {
    "total": 412, "limit": 100, "offset": 0, "nextOffset": 100,   // lists only
    "attribution": "Chart data from ChartVault (www.chartvault.fm)",
    "terms": "https://www.chartvault.fm/api/terms"
  }
}

• Fields are camelCase. A field with no value is present and null; fields are never left out.
• Dates are YYYY-MM-DD (issue dates as printed: Billboard dated issues on Saturdays, Radio & Records on Fridays). Times are UTC, ISO 8601.
• Titles and names are given as the archive holds them, which for most charts is the magazine’s capitals.
• Lists take limit (1–1000, default 100) and offset. Keep asking with offset=nextOffset until nextOffset is null.
• Answers may be cached by your client for five minutes (Cache-Control: private, max-age=300). The archive changes only when new data is loaded.

Limits

Each key has a per-minute limit and, on most tiers, a daily limit (see tiers). A minute is a clock minute; a day is a UTC day, starting at 00:00 UTC. Every answer tells you where you stand:

Over a limit you get 429 Too Many Requests. Wait for Retry-After and slow down; don’t retry in a tight loop. A key that keeps going after being refused (more than about a thousand 429s in an hour) is suspended automatically. Refused calls don’t count against your daily allowance. Every call that gets past the key check and limits counts, including ones that answer 400 or 404.

Errors

Errors use the standard problem details format (RFC 9457), with Content-Type: application/problem+json. Branch on code, which never changes; title and detail are for people and may be reworded.

{
  "type": "https://www.chartvault.fm/api/docs#error-rate_limited",
  "title": "Too many requests",
  "status": 429,
  "detail": "This key may make 60 calls a minute. Wait 21 seconds (the Retry-After header) and try again.",
  "code": "rate_limited",
  "instance": "/api/v1/years",
  "requestId": "0HNPFL61ETV9E:00000001",
  "retryAfter": 21
}

Looking after a key

• Expiry. Keys last 12 months. We email the owner 30 and 7 days before; renew with one click on the developer page (from 30 days before expiry). The key itself doesn’t change.
• Rolling. If a key may have been exposed, roll it on the developer page. You get a new secret at once and the old one keeps working for 7 days, so you can switch without an outage. Calls with the old secret carry a Sunset header saying when it stops.
• IP allowlist. Restrict a key to your servers’ addresses (single addresses or ranges such as 203.0.113.0/24). A stolen key is then useless elsewhere.
• Automatic suspension. A key is suspended, and its owner emailed, if it is used from more than 25 addresses in a day (without an allowlist), keeps calling after being rate-limited, or is repeatedly used from outside its allowlist.
• Check a key’s tier, limits, usage and expiry at any time with /me.

Endpoints

{ "data": [ { "code": "H100", "name": "Billboard Hot 100", "publisher": "Billboard", "firstYear": 1958, "lastYear": 2026 }, ... ] }

{ "data": { "code": "BBMR", "name": "Billboard Mainstream Rock", "publisher": "Billboard", "firstYear": 1981, "lastYear": 2026,
    "namesInPrint": [ { "from": null, "until": "1984-09-15", "name": "Top Tracks" },
                      { "from": "1984-09-15", "until": "1986-04-12", "name": "Top Rock Tracks" }, ... ] } }

{ "data": [ "1985-01-05", "1985-01-12", ... ], "meta": { "chart": "H100", "year": 1985, "count": 52 } }

{ "data": {
    "chart": "H100", "chartName": "The Billboard Hot 100", "publisher": "Billboard", "issueDate": "1985-07-13",
    "positions": 100, "previousIssue": "1985-07-06", "nextIssue": "1985-07-20", "note": null,
    "entries": [ {
      "rank": 1, "lastWeek": 2, "twoWeeksAgo": 4, "threeWeeksAgo": 7, "weeksOnChart": 12, "peak": 1,
      "bullet": true, "status": null,
      "song": { "id": 4127, "title": "...", "flipSide": null },
      "artist": "...",
      "artists": [ { "id": 812, "name": "...", "joinedBy": null } ],
      "printed": { "lastWeek": "2", "twoWeeksAgo": "4", "weeksOnChart": 12, "title": "...", "artist": "...",
                   "label": "...", "annotation": null, "highlights": [ "NO1" ], "weeksAtNumberOne": 1 }
    }, ... ] } }

{ "data": [ { "year": 1958, "loaded": true, "note": null }, ... ], "meta": { "count": 69, "loaded": 36 } }

{ "data": [ { "chart": "CHR", "chartName": "R&R CHR / Top 40", "publisher": "Radio & Records", "issues": 52,
              "firstIssue": "1989-01-06", "lastIssue": "1989-12-29" }, ... ] }

{ "data": [ { "id": 4127, "title": "...", "artist": "...", "firstYear": 1985, "bestPeak": 1, "weeksOnCharts": 31, "charts": 3 }, ... ],
  "meta": { "total": 412, "limit": 100, "offset": 0, "nextOffset": 100, "letter": "B", "q": null } }

{ "data": { "id": 4127, "title": "...", "artist": "...", "artists": [ { "id": 812, "name": "...", "joinedBy": null } ],
    "charts": 3, "weeksOnCharts": 31, "bestPeak": 1,
    "chartRuns": [ { "chart": "H100", "chartName": "The Billboard Hot 100", "weeks": 20, "peak": 1, "weeksBulleted": 9,
                     "firstIssue": "1985-04-20", "lastIssue": "1985-08-31", "peakIssue": "1985-07-13", "flipSide": null,
                     "history": [ { "issueDate": "1985-04-20", "rank": 78, "bullet": true }, ... ] }, ... ] } }

{ "data": [ { "id": 812, "name": "...", "songs": 14 }, ... ], "meta": { "total": 96, ... } }

{ "data": { "id": 812, "name": "...", "songs": [ { "id": 4127, "title": "...", "artist": "...", "billingOrder": 1, "firstYear": 1985,
    "chartRuns": [ { "chart": "H100", "chartName": "The Billboard Hot 100", "weeks": 20, "peak": 1,
                     "firstIssue": "1985-04-20", "lastIssue": "1985-08-31" } ] }, ... ] } }

{ "data": { "key": { "id": 7, "label": "My project", "prefix": "cv_live_Ab3dEf", "created": "2026-10-21T19:42:25Z",
                     "expires": "2027-10-21T19:42:25Z", "ipAllowlist": [] },
            "tier": { "code": "FREE", "name": "Free", "commercialUse": false, "aiTraining": false },
            "limits": { "perMinute": 60, "perDay": 10000, "overageAllowed": false },
            "usage": { "today": 132, "remainingToday": 9868, "resetsInSeconds": 15840 } } }

Chart codes

Which of these hold data, and for which years, is answered by /charts. Names changed over the years; see namesInPrint.

Field glossary

Code examples

curl

curl -s -H "Authorization: Bearer $CHARTVAULT_KEY" \
  "https://www.chartvault.fm/api/v1/songs?q=hold%20on&limit=20&pretty=1"

Python (requests)

import os, time, requests

API = "https://www.chartvault.fm/api/v1"
session = requests.Session()
session.headers["Authorization"] = "Bearer " + os.environ["CHARTVAULT_KEY"]

def get(path, **params):
    while True:
        r = session.get(API + path, params=params, timeout=30)
        if r.status_code == 429:                      # over a limit: wait as told
            time.sleep(int(r.headers.get("Retry-After", "60")))
            continue
        if r.status_code >= 400:
            problem = r.json()
            raise RuntimeError(f"{problem['code']}: {problem['detail']}")
        return r.json()

week = get("/charts/H100/issues/1985-07-13")["data"]
for e in week["entries"][:10]:
    print(e["rank"], e["song"]["title"], "-", e["artist"])

# every song beginning with B, page by page
offset = 0
while offset is not None:
    page = get("/songs", letter="B", limit=1000, offset=offset)
    for s in page["data"]:
        ...
    offset = page["meta"]["nextOffset"]

JavaScript (Node 18+)

const API = "https://www.chartvault.fm/api/v1";

async function get(path) {
  for (;;) {
    const r = await fetch(API + path, { headers: { Authorization: `Bearer ${process.env.CHARTVAULT_KEY}` } });
    if (r.status === 429) {
      await new Promise(ok => setTimeout(ok, 1000 * Number(r.headers.get("retry-after") ?? 60)));
      continue;
    }
    const body = await r.json();
    if (!r.ok) throw new Error(`${body.code}: ${body.detail}`);
    return body;
  }
}

const { data: song } = await get("/songs/4127?include=history");
for (const run of song.chartRuns) console.log(run.chartName, "peak", run.peak, "for", run.weeks, "weeks");

Changes

Within v1, fields and endpoints may be added but are never removed or renamed, and code values never change. Anything incompatible would come as v2, with notice to key holders by email. Credit ChartVault wherever the data is shown, as the terms require; the wording is in every answer’s meta.attribution.

Questions or a problem? Use the contact page and include the requestId from any error.