Developer API — nstate

licence

Data: CC BY 4.0 — free to use, attribute nstate.org. Code: MIT. Rate limit: 30 requests/hour per IP for /query. All other endpoints are unlimited.

POST/query

Ask a plain-English question. Returns a cited, data-backed answer or a gap notice.

⚠ Rate limited: 30 requests/hour per IP.

curl -X POST https://api.nstate.org/query \
  -H 'Content-Type: application/json' \
  -d '{"question":"How many civil servants work for the UK?","country":"uk"}'

GET/findings

List published findings. Add ?status=reviewed_finding for curated ones.

curl "https://api.nstate.org/findings?country=uk&limit=10"

GET/findings/{id}

Single finding by ID — includes question, narrative, key stat, SQL.

curl "https://api.nstate.org/findings/uk-2026-0001"

GET/findings/{id}/export.csv

Download finding data as a CSV file. Re-runs stored SQL for fresh rows.

curl -O "https://api.nstate.org/findings/uk-2026-0001/export.csv"

POST/findings/{id}/flag

Flag a finding as incorrect, outdated, misleading, or other.

curl -X POST https://api.nstate.org/findings/uk-2026-0001/flag \
  -H 'Content-Type: application/json' \
  -d '{"flag_type":"outdated","note":"ONS updated this in June 2026"}'

GET/gaps

Top data gaps sorted by vote count — the public roadmap.

curl "https://api.nstate.org/gaps?country=uk&limit=20"

POST/gaps/vote

Vote to prioritise a gap topic.

curl -X POST "https://api.nstate.org/gaps/vote?topic=NHS+waiting+times+by+trust&country=uk"

GET/datasets

List loaded datasets for a country with source URLs and priority.

curl "https://api.nstate.org/datasets?country=uk"

GET/health

Health check — returns current UTC time.

curl "https://api.nstate.org/health"