Quickstart

Welcome to the Chartmetric Developer API. Programmatic access to artists, tracks, albums, charts, playlists, and brands across streaming, social, and radio platforms.

The API is REST-based: predictable resource URLs, JSON responses, standard HTTP status codes.

Base URL: https://api.chartmetric.com
Auth: Bearer access token (short-lived, exchanged from a refresh token)

1. Get a Refresh Token

Each API user is issued a long-lived refresh token. To sign up, email hi@chartmetric.com. The refresh token is sent to your personal email.

Treat refresh tokens like passwords. Never commit them or expose them in client-side code.

2. Exchange Refresh Token for an Access Token

Access tokens expire in 1 hour. Mint one by POSTing your refresh token to /api/token:

curl -X POST https://api.chartmetric.com/api/token \
  -H "Content-Type: application/json" \
  -d '{"refreshtoken":"YOUR_REFRESH_TOKEN"}'

Response:

{
  "token": "...",
  "expires_in": 3600,
  "refresh_token": "...",
  "scope": "..."
}

Reuse the same access token across requests until it expires — do not mint a new one per call.

Full details: Authentication.

3. Make Your First Request

Pass the access token in the Authorization header:

curl https://api.chartmetric.com/api/artist/206557 \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Python:

from requests import get, post

HOST = 'https://api.chartmetric.com'
REFRESH_TOKEN = '...'

token = post(f'{HOST}/api/token', json={'refreshtoken': REFRESH_TOKEN}).json()['token']

res = get(f'{HOST}/api/artist/206557', headers={'Authorization': f'Bearer {token}'})
print(res.json())

4. Explore the API

API Reference — every endpoint with parameters, responses, and a try-it console.
Authentication — token flow, refresh, error handling.
Rate Limits & Plans — throughput tiers and 429 handling.

Tips

URL-encode strings with non-alphanumeric characters (artist names, track titles).
Array query params use the param[]=1&param[]=2 form.
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset headers — use them to pace requests.

Support

Questions or token issues: hi@chartmetric.com.

API FAQ: help.chartmetric.com.

Authentication