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.
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.
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.
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
Status
Meaning
400
Invalid query, limit, cursor or comparison parameters.
403
Current source export rights do not permit CSV.
404
Unknown route or no approved publication, native cohort or metric.
405
Method is not supported; use GET or HEAD.
409
Publication or visible inventory changed, a retained publication became unavailable, metric/period selection is ambiguous, or a complete compatible ranking cohort is unavailable.
The 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.