Data API for 192,808,842 domain ratings

Authentication

Generate a key on your account page and send it as a bearer token. Any account can create one, free. No account yet? Get a free key with just your email address.

Authorization: Bearer cdr_AbCdEf123456_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

• • A key is shown once, when you create it. We store only a bcrypt hash, so we cannot show it again or recover it. If it is lost, generate another.
• • Generating a new key revokes the old one immediately.
• • The key goes in the header only. We do not accept it in a query string, because that would put it in access logs, proxy logs and shell history.
• • The key identifies your account. The ratings endpoint works with any key, within the free allowance if there is no subscription behind it. The downloads endpoint needs an active subscription.

Every mirrored release, newest first. URLs are signed per request, so call this each time rather than storing the links.

Query parameters

Example

curl -sS https://checkdomainrating.com/api/v1/downloads \
  -H "Authorization: Bearer $CDR_API_KEY"

{
  "generated_at": "2026-09-05T06:40:00Z",
  "current_month": "2025-12",
  "subscription_ends_at": "2027-07-05T09:12:44Z",
  "count": 2,
  "downloads": [
    {
      "month": "2025-12",
      "filename": "2025-12.parquet",
      "size_bytes": 24696061952,
      "domain_count": 248113004,
      "etag": "\"9f86d081884c7d65\"",
      "computed_at": "2026-01-06T09:30:00Z",
      "url": "https://checkdomainrating.com/...signed...",
      "url_expires_at": "2026-09-05T07:40:00Z"
    }
  ]
}

Response fields

Errors

Every error is JSON with an error code and a message.

Rate limits

Every key: 60 requests a minute and 5,000 a day, counted across both endpoints. A 429 carries a Retry-After header in seconds. At 100 domains a request that is half a million domains a day; for more than that, the monthly file has all of them and no limit at all.

A free key's day runs midnight to midnight UTC, and only requests that were answered count. A request refused for its body (a 400 or a 422) costs nothing. Every answer to a free key carries these headers, so a script can pace itself instead of finding out at the 429:

• • X-RateLimit-Limit: Requests a free key may make in a UTC day.
• • X-RateLimit-Remaining: How many of those are left today.
• • X-RateLimit-Reset: When the count starts again, as a Unix timestamp: the next midnight UTC.

Up to 100 domains in one request, answered in the order you sent them. Each entry is reduced to its apex domain first, so https://www.bbc.co.uk/news, www.bbc.co.uk:443 and bbc.co.uk are the same lookup. Repeats are answered once, so the answer can be shorter than the list. Nothing about the list is logged, cached or stored.

Request body

JSON, with domains as either a list of entries or one string with them separated by newlines, commas, spaces, tabs or semicolons. The second form takes a pasted file without splitting it first.

Example

curl -sS https://checkdomainrating.com/api/v1/ratings \
  -H "Authorization: Bearer $CDR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domains": ["bbc.co.uk", "https://www.gov.uk/page", "not a domain"]}'

{
  "generated_at": "2026-09-05T06:40:00Z",
  "month": "2025-12",
  "count": 3,
  "ratings": [
    { "input": "bbc.co.uk", "domain": "bbc.co.uk", "rating": 91 },
    { "input": "https://www.gov.uk/page", "domain": "www.gov.uk", "rating": 88 },
    { "input": "not a domain", "domain": null, "rating": null }
  ]
}

Response fields

A domain we hold no row for is a domain nothing links to, which is a rating of 0 rather than a missing one. Only an entry we cannot read as a domain at all comes back with null for both fields.

Fetching a release

The signed URL is an ordinary GET. Send no headers and no credentials with it: an Authorization header will make object storage reject the signature.

import os, requests

API = "https://checkdomainrating.com/api/v1"
headers = {"Authorization": f"Bearer {os.environ['CDR_API_KEY']}"}

catalogue = requests.get(f"{API}/downloads", headers=headers, timeout=30).json()
latest = catalogue["downloads"][0]

with requests.get(latest["url"], stream=True, timeout=60) as response:
    response.raise_for_status()
    with open(latest["filename"], "wb") as file:
        for chunk in response.iter_content(chunk_size=1 << 20):
            file.write(chunk)

Opening the files covers what to do with one once you have it. They are large, up to about 25 GB, so stream them to disk rather than into memory, and compare etag and size_bytes against a copy you already hold before downloading it again. A release you have already fetched never changes unless we republish that month, in which case its etag changes with it.