Workflow guides

Each workflow is an anonymous GET. Use county FIPS in the lower 48 or the District of Columbia. Replace example ids if discovery returns different ones.

Query a county

Goal: retrieve the current-release case-count floor for one county and year.

curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=36061&year=2023'

Then open source_id and methodology_id from that body. The checked release used:

curl -fsS 'https://api.onehealthatlas.org/v1/sources/human'
curl -fsS 'https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1'

County analytics and display scores are a different route, GET /v1/counties/{fips}. That route returns the legacy county document, including release metadata. GET /v1/counties/00000 returned HTTP 404 with detail County or dataset release not found and no code. Use the observations route when you need value_state.

State	What the county observation query does
Success	HTTP 200 and one or more rows. Checked for FIPS 36061, year=2023: value_state OBSERVED
Empty	HTTP 200 and data: []. Checked for FIPS 99999
Not found	Declared HTTP 404 RESOURCE_NOT_FOUND. The legacy county route's 404 can omit code
Invalid parameters	HTTP 400 INVALID_REQUEST when the period is missing, when year is combined with a date range, or when geography_type is not county or state
Unsupported filter	HTTP 400 UNSUPPORTED_FILTER for sort, aggregation, or an unknown parameter
Unsupported stratification	HTTP 400 UNSUPPORTED_STRATIFICATION
Query too broad	HTTP 400 QUERY_TOO_BROAD. The public overview states a default pre-execution logical-result ceiling of 10,000, and that ceiling is not truncation
Rate limited	HTTP 429 RATE_LIMITED and Retry-After
Server unavailable	HTTP 503 and Retry-After
Unknown or limited data	HTTP 200 with MISSING, SUPPRESSED, UNAVAILABLE, or NO_COUNTY_LINKED_RECORD. Checked for FIPS 08001: MISSING and value null

Compare geographies

Goal: retrieve the same measure and period for two counties in one request. Repeat geography_id.

curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=08001&geography_id=36061&year=2023'

The service orders by measure id, county FIPS, period start, and observation id. On 12 October 2026 this comparison returned two rows in one HTTP 200 page: FIPS 08001 with value_state MISSING and value null, then FIPS 36061 with value_state OBSERVED and a numeric value. Both rows shared measure_id, unit cases, period year 2023, and release_id. A missing row and an observed row are not two numbers on one scale. Compare value_state before comparing value.

You can repeat up to 500 county ids. There is no rank and no winner field. Do not send sort or aggregation.

State	What a comparison does
Success	HTTP 200 and a row per matched county. Counties can differ in value_state
Empty	HTTP 200 and data: [] when none of the ids match
Partial	HTTP 200 and a row for some ids only. A county with no row is absent from data. It is not a zero
Not found	HTTP 404 RESOURCE_NOT_FOUND is declared for the operation. An unknown measure path is the checked 404
Invalid parameters	HTTP 400 INVALID_REQUEST for a bad period or geography_type
Unsupported filter or strata	HTTP 400 UNSUPPORTED_FILTER or UNSUPPORTED_STRATIFICATION
Query too broad	HTTP 400 QUERY_TOO_BROAD. The public overview states a default pre-execution logical-result ceiling of 10,000, and that ceiling is not truncation
Rate limited	HTTP 429 and Retry-After
Server unavailable	HTTP 503 and Retry-After
Unknown or limited data	Mixed value_state values, null denominator, or null context on either row

next_page_token can be non-null when the combined rows exceed page_size. Follow it with the same measure, counties, and period.

Retrieve environmental context

There is no separate environmental-context endpoint. environmental_context is an optional object on an observation. It is present only for reviewed environmental context. The observations operation describes it as descriptive weather, with no causal, disease-risk, or ML claim. surveillance_context is a different optional object. It is supplied only through an admitted Data release and supported slice. Omitted or null carries no evidence-state, comparability, or lag claim.

When the object is present, read coverage_status before the measure value. The status is COMPLETE, PARTIAL_COVERAGE, SOURCE_MISSING, or OUT_OF_SOURCE_COVERAGE. Coverage is independent of value_state. day_convention is the publisher's labeled 24-hour period. source_coverage_fraction is monthly source-supported area over legal county area. valid_fraction_of_supported_area is daily valid area over source-supported area, with a completeness threshold of 0.95. Area quantities may be numbers or exact numeric strings. geometry_version names analysis geometry and does not include polygons. Null context does not establish absence or temporal comparability.

The current measure catalog does not publish a measure id for that daily weather series. GET /v1/measures on 12 October 2026 returned 21 measures and a null next_page_token. None of those ids is a daily weather measure. Do not invent one.

The catalog does publish annual land-cover context under indicator land_cover_context. Those measures name selected geographies 09110 and 51013 only. Their missingness text says a true zero stays zero, and unselected counties have no observation. Their limitations describe land-cover context only, with no Lyme causal or risk estimate.

curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=nlcd_forest_area_share_county_year&geography_type=county&geography_id=09110&year=2025'

That request returned HTTP 200, value_state OBSERVED, unit fraction, temporal grain YEAR, and environmental_context null. The land-cover row is not a weather environmental_context object.

curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=nlcd_forest_area_share_county_year&geography_type=county&geography_id=08001&year=2025'

FIPS 08001 is outside the selected land-cover geographies. That request returned HTTP 200 and data: []. The empty page is not a zero share.

State	Environmental and land-cover reads
Success with context	HTTP 200 and an observation whose environmental_context object is present. Read coverage_status with the value
Success without context	HTTP 200 and environmental_context null. Checked for the land-cover request above
Empty	HTTP 200 and data: [] for an unselected land-cover county. Checked for FIPS 08001
Not found	HTTP 404 RESOURCE_NOT_FOUND for an unknown measure id
Invalid parameters	HTTP 400 INVALID_REQUEST for a missing or contradictory period
Unsupported filter or strata	HTTP 400 UNSUPPORTED_FILTER or UNSUPPORTED_STRATIFICATION. These measures declare no supported strata
Query too broad	HTTP 400 QUERY_TOO_BROAD. The public overview states a default pre-execution logical-result ceiling of 10,000, and that ceiling is not truncation
Rate limited	HTTP 429 and Retry-After
Server unavailable	HTTP 503 and Retry-After
Unknown or limited data	coverage_status of PARTIAL_COVERAGE, SOURCE_MISSING, or OUT_OF_SOURCE_COVERAGE, a null area field, a null environmental_context, or a null or omitted surveillance_context

Reproduce and cite an observation

Goal: store enough of one response to explain the number later, after the current release has moved on.

1. Save the request URL.
2. Save the observation fields in Provenance and evidence, including value_state, release_id, semantic_version, methodology ids and versions, source id, lineage source id, dataset id, source vintage, and limitations.
3. Save the source resource for that source_id and the methodology resource when methodology_id is not null.
4. Save meta.response_at as the retrieval time. Keep it distinct from period_start, source_vintage, and source_published_at.
5. Save the response body, or a checksum of that body.

A practical attribution names Atlas, the public API /v1, the measure id, county FIPS, period, release_id, semantic_version, retrieval time, and the publisher and dataset from the source resource you received. provenance_ref is the observation's provenance identity. It is not a literature citation. A page_token is not a citation.

The same URL reads the current release. It is not a permanent snapshot. The saved response is the record of what you retrieved.

State	How citation changes
Success	Cite value, value_state, unit, period, release, semantic version, source, and methodology from that body
Empty	Cite the request and the empty data array. Do not cite a value
Not found	Cite HTTP 404, request_id, and the id that was missing. There is no observation to cite
Invalid parameters	Fix the query and retrieve again. A 400 body is not an observation
Rate limited or unavailable	Wait for Retry-After when present, then retrieve again. Keep request_id if you need support
Gap, suppression, or no linked record	Cite value_state and the null or literal value. Do not cite a reconstructed number