API

The public record, over HTTP.

Every page on this site is built from the same retained data. Read it directly: no key needed to start, a free key for more, Pro for the full archive and bulk exports.

Get a free key Read the endpoints

Quick start

One request, no key.

curl "https://china-snapshot.com/api/datasets?dataset=indicators&limit=5"

Anonymous callers get 60 requests a minute per IP, 100 rows a page and a 1 years window. Responses are cached at the edge, so a repeated read costs nothing.

{
  "schema_version": 1,
  "dataset": "indicators",
  "as_of": "2026-10-30T06:14:06+00:00",
  "items": [
    {
      "id": "indicators:1234",
      "title": "China CPI",
      "source": "National Bureau of Statistics",
      "source_url": "https://www.stats.gov.cn/",
      "period": "2026-09",
      "value": "0.4%",
      "numeric_value": 0.4,
      "unit": "%",
      "collected_at": "2026-10-09T02:10:00+00:00"
    }
  ],
  "row_count": 1,
  "next_cursor": null,
  "coverage": { "...": "date field, order and known limits" },
  "fields": [ "...": "every column this dataset can return" ]
}

Endpoints

Four routes and a catalog.

GET /api/datasets

Page through one retained dataset. dataset is documents, social or indicators. Filters: q, source, from, to, text=available (documents only), id for one record. Paging: limit (max 100 anonymously), cursor from next_cursor. Shape: fields to choose columns, format=csv for CSV.

# One document with its reviewed original text
curl "https://china-snapshot.com/api/datasets?dataset=documents&id=documents:1234"

# A CSV page, chosen columns
curl "https://china-snapshot.com/api/datasets?dataset=social&format=csv&fields=id,title,rank&limit=50"

# With a key
curl -H "Authorization: Bearer $CHINA_SNAPSHOT_KEY" \
  "https://china-snapshot.com/api/datasets?dataset=documents&from=2026-01-01&limit=500"

next_cursor is a signed continuation token: pass it back with the same filters to get the next page. Sending it with different filters is a 400, not a wrong page.

GET /api/usage

Your own metered counts for the key you sent: today, this month, your tier and its limits.

curl -H "Authorization: Bearer $CHINA_SNAPSHOT_KEY" \
  "https://china-snapshot.com/api/usage?days=30"

POST /api/key_signup

Issues one Free key key for an email address. One live key per address. The key is emailed when mail delivery is configured, and returned in the response when it is not, so it can only be shown once.

GET /api/checkout/pro

Starts the Pro subscription checkout and redirects to the hosted payment page. Billing is processed by Airwallex. Nothing is charged until you complete the hosted checkout.

Machine-readable

/openapi.json describes the whole surface. /data/endpoints.json is the catalog of every public feed with its access level. /llms.txt is the agent entry point and /developers.md is the Markdown copy.

Limits

What each tier allows.

Anonymous

Free

No monthly cap
60 requests per minute
100 rows per page
CSV export up to 100 rows
1 years of history
No full dataset dumps
No key

Free key

Free

5,000 / month
30 requests per minute
500 rows per page
CSV export up to 1,000 rows
2 years of history
No full dataset dumps
1 active key

Pro

$49 / month

100,000 / month
300 requests per minute
5,000 rows per page
CSV export up to 50,000 rows
Full retained archive of history
Bulk dataset exports
3 active keys

Enterprise

Contact us

By contract
600 requests per minute
5,000 rows per page
CSV export up to 50,000 rows
Full retained archive of history
Bulk dataset exports
10 active keys

Every response names your tier in X-Api-Tier. A refused request is a 429 with X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and Retry-After, and a body that links back to this page. Limits are hard caps with no overage charge: reaching one returns a limit response, never a bill.

What the data is

A retained record, not a register.

The API returns what was collected and kept. Each dataset response carries a coverage object naming its date field, its ordering and its known limits, and text_status says whether an original text may be republished. Dates filter on collection time in UTC; a publication date is a separate field. Original publisher rights still apply to anything you quote.

Search