Developer reference · API v1

Use the facts.
Keep the context.

A read-only interface to approved place publications, with source definitions, reference periods, geographic identity and permissions intact.

Download OpenAPI 3.1
i

Publication gates apply to the API. A source-linked development profile does not automatically become an API publication. Empty results or a place-not-found response can be the correct outcome while review is open.

Public, read-only access

No API key is required for these public reads. GET and HEAD are supported; dataset mutation methods are rejected. The separate correction form records reports for review and cannot change facts. Same-origin browser and server-to-server access are supported; cross-origin browser CORS access is not promised.

Best-effort edge limits

Requests are limited to 60 per 60 seconds per edge IP when the binding is active. Edge-local enforcement is best effort, not an account quota or a globally exact allowance. A 429 includes Retry-After.

Current rights matter

Display and export rights are independent. The place response's effectivePermissions describes current authorization. Embedded source.rights preserves the immutable publication-time evidence.

Available routes

Small, explicit contracts.

Machine-readable specification
GET

/api/v1/rankings/current-{place|cdp}-{metric}

Order the full current approved native-type cohort with source-linked observations. This is not a national/statewide or curated ranking.

direction=ascending|descending; limit 1–50; returned after cursor. Full compatible coverage, at least 2 members, one publication/source/vintage/window; other native types excluded explicitly; overlap unknown. Current rights rechecked before 304.

GET

/api/v1/sources/{id}

Read one approved source resource with current rights and release checks before conditional reuse.

id: stable source or release identity · If-None-Match: prior ETag

GET

/api/v1/source-releases/{id}

Read one approved source resource with current rights and release checks before conditional reuse.

id: stable source or release identity · If-None-Match: prior ETag

GET

/api/v1/metrics

Read source-linked definitions and release evidence reachable from the current approved publication.

geography: optional stable identity · limit:1–50 · after: returned opaque cursor, with unchanged filters and limit

GET

/api/v1/sources

Read source-linked definitions and release evidence reachable from the current approved publication.

geography: optional stable identity · limit:1–50 · after: returned opaque cursor, with unchanged filters and limit

GET

/api/v1/source-releases

Read source-linked definitions and release evidence reachable from the current approved publication.

geography: optional stable identity · limit:1–50 · after: returned opaque cursor, with unchanged filters and limit

GET

/api/v1/observations

Read native observations, explicit missingness and margins of error within one approved geography.

geography: required · metric: optional · periodStart/periodEnd: inclusive observation bounds · limit/after: cursor pagination

GET

/api/v1/geographies/suggestions

Native name/ID suggestions with exact state/type qualifiers from the current approved publication. Response headers retain match counts, required choice, truncation and eligibility date even at limit1. Empty query returns no suggestions; no-store, no cursor.

q: up to100 Unicode characters · limit:1–8 · type:place/cdp · stateFips:50-state/DC code

GET

/api/v1/geographies

Search approved geography publications by display name. Paginate using the returned next cursor.

q: up to 100 characters · limit: 1–50 (default 20) · after: previous next cursor

GET

/api/v1/places/{id}

Read one source-linked, approved place snapshot with current effective display/export permissions.

id: stable geography identity · If-None-Match: previous permission-sensitive ETag

GET

/api/v1/places/{id}.csv

Export the approved snapshot only when current source permissions authorize CSV redistribution.

id: stable geography identity · returns 403 when export rights are restricted

GET

/api/v1/compare

Compare one metric across two distinct approved geographies in the same publication.

ids: exactly two comma-separated identities · metric: stable metric id

GET

/healthz

Check publication-service database connectivity. This does not establish dataset freshness or launch readiness.

No query parameters

Pagination and conditional reads

Geography and resource results are ordered by stable identity. Resource catalogs include one publicationId and a next cursor; an absent production pointer returns publicationId:null for resource catalogs. A retained but unavailable publication returns503 on an initial request and409 on continuation; it is not reported as an absent publication. Observations require a geography and retain their source period. The initial resource catalog supports up to1000 approved profiles and refuses larger inventories until catalog indexing is implemented. Pass the response's opaque next value unchanged as after for the following page. Ordinary list cursors bind publication, visible inventory and permissions, normalized filters and page size; keep limit and filters unchanged. Plain record IDs are rejected. Restart after a 409 publication or inventory change; a changed request scope is a 400. The cursor digest is not authentication or permission to select a private release. Stop when next is null; an empty data array is valid.

The place response includes an ETag. Send it with If-None-Match to request a conditional read. Current source rights are checked before a 304 is returned. Permission changes alter the ETag so stale export authorization is not preserved by an unchanged snapshot id.

Descriptive current-cohort rankings

Choose incorporated places or census-designated places explicitly. Ranking membership comes from the approved publication, not arbitrary user IDs. Every selected member must retain display permission and one compatible usable measure; a missing or suppressed cell withholds the full result. Other native geography types are disclosed as excluded counts. Competition ties and the exact observation window remain visible. Overlap is unknown, values are not summed and no national, statewide, independence or significance claim is made.

Ranking cursors bind publication, cohort and direction. A publication change requires restarting traversal. ETags hash the exact page representation; membership and current source rights are re-read before a 304. These bounded checks do not claim globally isolated database transactions.

Reading comparison results

The shared resolver can return compatible, compatible-with-caveat or incompatible. Incompatible observations do not receive a numeric difference. Differences are the second place minus the first place. Sampling uncertainty is not propagated into a statistical-significance claim.

Predictable failure states

Error response contract
StatusMeaning
400Invalid query, limit, cursor or comparison parameters.
403Current source export rights do not permit CSV.
404Unknown route or no approved publication, native cohort or metric.
405Method is not supported; use GET or HEAD.
409Publication or visible inventory changed, a retained publication became unavailable, metric/period selection is ambiguous, or a complete compatible ranking cohort is unavailable.
429Best-effort edge request limit exceeded; respect Retry-After.
503The publication database is not configured or is temporarily unavailable.

JSON errors have the form {"error":{"code":"…","message":"…"}}. Private database connection details are not included.

Source-linked reuse

Preserve geography, units, periods, source links, missing-value states and method caveats when using a response. Display permission alone does not authorize export or commercial reuse.

Read the source standards and the methodology. This reference describes implemented routes; it does not promise account plans, paid quotas, future endpoints or an indexing outcome.