ChartVault

For developers, researchers & data teams

The ChartVault API

Every chart week, song run and artist in the archive, as clean JSON. Free for non-commercial use, with a key, on the terms below.

What you can get

  • Chart weeks — every position of an issue, with last week, two and three weeks ago, weeks on chart, peak, bullets, debuts and re-entries, and for Billboard what the page itself printed (label, annotations, Hot Shot Debuts and No. 1 weeks).
  • Songs — each record’s run on every chart it made, with week-by-week history.
  • Artists — every credited act and all their charted records.
  • Charts and years — what the archive holds, and what each chart was called in print through its history.

How to get a key

  1. Ask for one with the short request form: who you are and what you’ll build.
  2. Confirm your email from the link we send.
  3. We review it, usually within a few days, and email you the decision.
  4. Sign in and reveal your key. It’s shown once; keep it secret, keep it on your server.

Request a key Read the docs Sign in

A request:

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

The answer (shortened):

{
  "data": {
    "chart": "H100",
    "chartName": "The Billboard Hot 100",
    "issueDate": "1985-07-13",
    "entries": [
      {
        "rank": 1, "lastWeek": 2, "weeksOnChart": 12,
        "peak": 1, "bullet": true, "status": null,
        "song": { "id": 4127, "title": "..." },
        "artist": "..."
      }, ...
    ]
  },
  "meta": { "attribution": "Chart data from ChartVault (www.chartvault.fm)" }
}

Tiers

Limits are per key. A minute is a clock minute; a day is a UTC day.

Free

Free

60calls / minute

10,000calls / day

  • Commercial use
  • AI training

Personal projects, research, teaching and journalism. Non-commercial use only; attribution required; not for training AI models.

Developer

By arrangement

120calls / minute

50,000calls / day

  • Commercial use
  • AI training

Commercial apps and sites at a modest scale. Attribution required; not for training AI models.

Business

By arrangement

300calls / minute

250,000calls / day

  • Commercial use
  • AI training
  • Overage instead of a hard daily stop

Higher limits for production services. Calls past the daily limit keep working and are counted as overage.

Data license

By agreement

600calls / minute

Nodaily limit

  • Commercial use
  • AI training

Bulk access under a written license, including AI training where the agreement allows it.

Commercial use and AI. Paid tiers are set up by arrangement while we finalise pricing: request the tier you need and tell us about the project. Using the data to train, fine-tune or ground AI models is allowed only under a Data license.

The short version of the rules

  • Credit ChartVault wherever you show the data: “Chart data from ChartVault (chartvault.fm)”, linked where you can.
  • Keep your key private. Call the API from your server, never from a web page or app users can inspect. Don’t share a key between organisations.
  • Stay within your limits. Back off when you’re told to (HTTP 429 and its Retry-After). Keys that hammer, spread across many addresses or leak are suspended automatically.
  • Don’t rebuild the archive. Bulk copying, reselling the data or offering it as a competing service needs a Data license.
  • Keys last a year and are renewed in one click. The full API Terms of Use apply.