Data API for 222,825,218 domain ratings

Authentication

Generate a key on your account page and send it as a bearer token:

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 endpoint additionally requires 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

60 requests a minute and 5,000 a day per key, 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.

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.