Developers

Use the static data carefully.

PainMap data is public and read-only, but it is not a universal moral scoreboard. Keep provenance, uncertainty, and method fields attached to every value you reuse.

Quickstart

Fetch the contract

curl https://painmap.org/v1/releases.json
curl https://painmap.org/releases/2026-05-31/manifest.json
curl https://painmap.org/data/openapi.json
curl https://painmap.org/data/release-modes.json
curl https://painmap.org/v1/places/index.json
curl https://painmap.org/v1/adm1/index.json
curl https://painmap.org/v1/coverage.json
curl https://painmap.org/v1/places/IND/adm1.json
curl https://painmap.org/v1/places/IND/neighbors.json
curl https://painmap.org/ogc/collections/places/items.json
curl https://painmap.org/ogc/collections/places/item-index.json
curl https://painmap.org/ogc/collections/places/items/IND.json
curl https://painmap.org/data/place-measurements.json
curl https://painmap.org/v1/places/BRA.json
curl https://painmap.org/data/provenance-registry.json
curl https://painmap.org/schemas/place-index.schema.json
curl https://painmap.org/schemas/adm1-context.schema.json
curl https://painmap.org/releases/2026-05-31/diff.json

The API has no authentication and no write side. Use immutable release URLs for reproducible work; use latest aliases only when freshness matters more than exact replay. Validate client assumptions against the JSON Schemas and coverage status before treating a place as measured.

TypeScript client Python client Example recipes

must keep

Provenance

Carry source ids, source vintage, evidence kind, confidence bounds, uncertainty class, release id, and license id with every copied value.

must not

Overclaim

Country and ADM1 rows are directional proxies unless the evidence kind says direct or modeled.

security

Headers

The repository includes a static-host header policy and a Vercel header config for CSP, referrer policy, nosniff, and permissions policy.

budgets

Field performance

LCP, INP, and CLS budgets are published with the release, alongside endpoint smoke targets and telemetry event names.

freshness

Source cadence

Source freshness JSON records review cadence by source family, validation lanes, and the weekly workflow that opens release-candidate PRs when artifacts drift.

modes

Snapshot vs live

The homepage defaults to immutable snapshot mode. Live overlay mode is explicitly labeled and may load current public-source rows outside the release measurements.

reuse

Typed clients

Small TypeScript and Python clients cover releases, coverage, place indexes, ADM1 context, place profiles, and measurement payloads.

ADM1

Subnational context

ADM1 poverty-context rows are static proxy overlays. They are useful for discovery, but they are not canonical PainMap pain measurements.

geo

OGC-style features

Static OGC API - Features-style JSON exposes both the full country feature collection and per-country item files for partitioned geometry loading.

release

Diffs and migrations

Release diff JSON records changed surfaces, while migration notes document schema changes, renamed fields, removed fields, and new layer IDs.

fixtures

Local preview fixtures

Mock registry and fixture measurement files support disposable preview releases through npm run fixtures:check and npm run preview:fixture.

API reference Fixture workflow Security baseline