Developer overview
Start here for anonymous Atlas REST reads, the guide map, and the limits of the public contract.
These guides take a developer from no Atlas context to one successful public REST read, and they explain the semantics that an operation name leaves out. Parameter tables, component schemas, and generated examples stay in the API reference. This section explains how to use the contract.
Access
Ordinary public reads are anonymous HTTPS GET requests. They require no API key, no signed-in session, no SDK, and no MCP server. These guides call the public API at https://api.onehealthatlas.org. The HTTP contract is /v1. The OpenAPI info.version is a separate application version.
Send the request URL with its query string. A collection returns data, meta, and links. A single resource returns data. Errors use application/problem+json.
Guide map
| Guide | Use it when you need to |
|---|---|
| Quickstart | Complete one current-release county observation read |
| REST API | Page a collection, handle errors, and tell versions apart |
| Geography | Identify a county, and see which geography delivery is unavailable |
| Indicators, measures, and observations | Choose a measure and read value with value_state |
| Provenance and evidence | Cite source, methodology, release, and freshness fields |
| Workflow guides | Query one county, compare counties, read environmental context, and reproduce a result |
| OpenAPI, GitHub, and support | Open the machine-readable contract and report a request_id |
Reviewers who are interpreting a screen, rather than calling the API, should use Evidence, provenance, and uncertainty. MCP status stays on API, MCP, and access. How governed sources are intended to become this canonical evidence contract, and which of that design is released, is in Sources and canonical evidence.
Where the reference lives
The authoritative document is the public OpenAPI schema. The Swagger reference and ReDoc reference render that same document.
The generated reference for that contract is the API reference, with pages for discovery, observations, provenance, geographies, atlas, counties, states, and schemas. Those pages are produced from the pinned public spec. These guides link to that location and do not copy its operation catalog.
Two public route families
These guides cover two route families. Read the family you called.
| Family | Routes | Error shape |
|---|---|---|
| Canonical current-release resources | Indicators, measures, observations, sources, methodologies, and geography identity | Problem details with a stable code |
| Legacy Atlas analytics and exports | County and state review, scores, display geometry, rankings, and PDF reports | Existing status codes, including 422. A problem body may omit code |
Internal conversational AI, literature retrieval, account, and feedback product routes are excluded from this public contract.
Geography used in examples
Atlas product geography for these guides is the lower 48 states and the District of Columbia. Examples use county FIPS 36061 (New York County, New York), 08001 (Adams County, Colorado), 09110 (Capitol Planning Region, Connecticut), and 51013 (Arlington County, Virginia). Preserve leading zeros. Five-digit FIPS strings are identifiers, so keep them as strings.
Limits recorded with the contract
Current-release observations have a default pre-execution logical-result ceiling of 10,000. That ceiling is not truncation. The public document does not publish a numeric request quota. Honor Retry-After on 429 and 503. See REST API.
GET /v1/geographies/{geography_type}/{geography_id} is declared, and its description says delivery currently returns 503 with CANONICAL_DATA_UNAVAILABLE and no geometry. See Geography.
The observations operation describes separately enabled January 2025 environmental measures that carry environmental_context. The current GET /v1/measures catalog does not list a measure id for that daily series. surveillance_context is optional and requires an admitted Data delivery. See Workflow guides.