# Start with Atlas Lyme (https://onehealthatlas.org/docs) > Understand Atlas Lyme, an Epidemiologist Decision Intelligence Platform for evidence-backed tick-borne disease investigation. Atlas Lyme is an **Epidemiologist Decision Intelligence Platform** for Lyme disease and other tick-borne diseases. It brings fragmented human disease, tick/vector, pathogen, climate, habitat, population, and scientific evidence together so epidemiologists can understand what is happening, investigate why, and decide what deserves closer review. Our product vision is **from fragmented surveillance data to timely, interpretable, evidence-backed public-health action**. Atlas is being built to identify what matters, explain why it matters, communicate uncertainty, and help epidemiologists decide what deserves investigation. The platform supports a practical path from `data` to `signals`, `context`, `interpretation`, `investigation`, and—when the evidence supports it—public-health action. Start with the orientation guides: * [What is Atlas Lyme?](https://onehealthatlas.org/docs/what-is-atlas) — the product category, purpose, and boundaries. * [Who is Atlas for?](https://onehealthatlas.org/docs/who-is-atlas-for) — the people and questions the platform is designed to support. * [The Atlas decision-support workflow](https://onehealthatlas.org/docs/atlas-workflow) — how Atlas moves from One Health evidence to an investigation question. * [Professional workspace](https://onehealthatlas.org/docs/professional-workspace) — the signed-in Atlas Explorer, Compare, Ask Atlas, Feed, Settings, and Docs destinations. * [Current capabilities](https://onehealthatlas.org/docs/current-capabilities) — what is available now, planned, experimental, or not supported. * [Investigation workflows](https://onehealthatlas.org/docs/investigation-workflows) — practical question-to-next-step guides for reviewing a signal. * [Evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty) — how to interpret outputs and distinguish missing evidence from low observed signal. * [Sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence) — how governed sources are designed to become one evidence model, and what is released today. * [AI-enabled decision intelligence](https://onehealthatlas.org/docs/ai-enabled-decision-intelligence) — what AI means in Atlas and the status of current, planned, and experimental capabilities. * [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access) — the public REST contract, and the current status of MCP and API keys. * [API reference](https://onehealthatlas.org/docs/api-reference) — the public OpenAPI contract rendered from the pinned spec, including version and source. * [FAQ and troubleshooting](https://onehealthatlas.org/docs/faq-and-troubleshooting) — answers for interpretation, loading, filters, data availability, and HelpDocs navigation. * [Developer overview](https://onehealthatlas.org/docs/develop) — anonymous REST reads, from one county request through citation. ## Who Atlas is for [#who-atlas-is-for] Atlas is designed for epidemiologists, public-health surveillance teams, researchers, and other partners who need to review geographic signals without losing sight of the evidence quality behind them. Use Atlas when you need to ask: * What is happening, and where? * What evidence supports that interpretation? * How current, complete, and comparable is the evidence? * Which areas or signals may warrant investigation next? ## What Atlas is — and is not [#what-atlas-is--and-is-not] Atlas is a decision-support platform, not an autonomous decision-maker. It helps users organize and interpret public evidence; it does not replace epidemiologists, public-health analysts, or domain experts. Atlas helps users explore patterns in public evidence at the county level. A review-priority score or other analytical signal is a structured way to focus questions; it is not a diagnosis, an individual exposure or disease-risk prediction, a measure of disease burden, or proof of causation. The current release is an early public prototype and situational-awareness foundation. Capability pages distinguish verified public behavior from planned, in-development, and experimental work. Atlas should help identify signals and investigation candidates—not claim that an outbreak will occur or that a geography is definitively safe or unsafe. ## A quick start [#a-quick-start] Signed-in workspace: 1. Sign in and open [Atlas Explorer](https://onehealthatlas.org/explore). Choose the United States or one state. 2. Use the map and the county list together, then open county evidence for one county. Suggested follow-up is on that same page. 3. Open [Compare](https://onehealthatlas.org/compare) for two counties. Read [the professional workspace](https://onehealthatlas.org/docs/professional-workspace) for the six destinations and for what is still empty or experimental. 4. Open **Docs** from the workspace navigation when you need this reference. It opens in a new tab and leaves the review address in the original tab. Older public bookmarks such as `/overview`, `/geographic_explorer`, and `/investigate` open Atlas Explorer after sign-in. They are not separate pages. ## Read the evidence carefully [#read-the-evidence-carefully] Atlas combines measures that can have different geographies, years, publishers, and update schedules. The application displays the release and methodology information available for the current result. Check the source and vintage before comparing measures. ### Missing is not zero [#missing-is-not-zero] An absent published county record can reflect zero reported cases, suppression, an unavailable source, a different reporting boundary, or another limitation. Do not treat a missing value as proof that no disease or surveillance activity exists. ### Start with provenance [#start-with-provenance] For a defensible follow-up question, record the source, source vintage, geography, retrieval or load context when available, methodology version, and known limitations. Use the in-application data dictionary and methodology sections for context that must stay close to the result. ## Help and trustworthy use [#help-and-trustworthy-use] Use **Docs** in the public Atlas utility bar, or **Docs** in the professional workspace navigation. Both open this help center in a new tab and leave the analytical page in the original tab. The public [Privacy page](https://onehealthatlas.org/privacy) and [AI Ethics page](https://onehealthatlas.org/ai-ethics) remain the approved in-application sources for those topics; this guide does not create separate policy commitments. Workspace pages do not add a separate contextual-help layer. ## Developer and agent access [#developer-and-agent-access] The public REST API is documented by its owning service. Start with [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access), the [developer overview](https://onehealthatlas.org/docs/develop), the generated [API reference](https://onehealthatlas.org/docs/api-reference), and the machine-readable [OpenAPI schema](https://api.onehealthatlas.org/openapi.json). Public reads do not use an API key. Production MCP exposes bounded anonymous read-only evidence tools for that same governed evidence. Connection recipes and agent guardrails are in [MCP clients](https://onehealthatlas.org/docs/develop/mcp-clients). The September 2026 smoke-only development receipt is historical. Settings does not generate API keys in this release. # AI-enabled decision intelligence (https://onehealthatlas.org/docs/ai-enabled-decision-intelligence) > Understand what AI means in Atlas Lyme, what is available now, and which future capabilities still require release and human review. Atlas Lyme is an **Epidemiologist Decision Intelligence Platform**. The product direction is AI-enabled: it is intended to help people organize, compare, synthesize, and explain governed One Health evidence so they can decide what deserves investigation. AI-enabled does not mean that Atlas replaces epidemiologists or turns a score into a prediction. The preferred public-health framing is: **signals → evidence → hypotheses → anomaly candidates → investigation priorities** Each step must remain interpretable, bounded by the evidence, clear about uncertainty, and accountable to human review. ## Capability status [#capability-status] | Capability | Status | What you can rely on | | --------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Transparent follow-up-priority scoring | Available now | The current score is a deterministic, adjustable calculation over released inputs. It helps focus review; it is not a predictive model, diagnosis, causal claim, disease-burden estimate, or individual-risk output. | | Public evidence and provenance context | Available now | The Explorer provides released signals, source/release/method context, limitations, and a table path for reviewing results. Start with [evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty). | | Atlas Assistant: reviewed literature | Early access, feature-gated | `/assistant` can ask the Atlas API about reviewed PubMed and PMC Open Access literature when enabled. Answers include cited evidence and explicit unavailable-evidence outcomes. This does not query live Atlas geography or scores, provide medical advice, or replace human review. | | Ask Atlas in the professional workspace | Experimental/demo | Atlas Explorer and Compare open the dedicated [Ask Atlas page](https://onehealthatlas.org/askatlas). When literature chat is enabled, it uses that same reviewed-literature service and leaves navigation with you. When it is disabled, the Ask Atlas page says Ask Atlas is unavailable and the other workspace pages stay usable. The request is a message plus optional conversation history. There is no Structured mode and no Both mode. | | Ask Atlas page at `/askatlas` | Experimental/demo | The dedicated page uses the reviewed-literature service. Saved chats stay in this browser. It does not offer Structured or Both mode, and it does not store chats on Atlas servers. | | Broader Atlas evidence assistant | Planned | Mixed Atlas data and knowledge-graph questions need separate governed work and release review. This is not a released capability. | | Anomaly candidates and interpretable modeling | Planned | Future outputs may help identify unusual patterns or explain modeled context, but no current public result should be described that way without a released model, inputs, validation, uncertainty, and review record. | | Literature monitoring or agent assistance | Planned | Future monitoring or agent workflows must use approved sources and explicit release controls. Released MCP evidence tools are anonymous reads of governed public evidence. They do not run an agent. The September 2026 smoke-only development receipt is historical. See [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access). | The status labels are intentionally explicit. A planned architecture, a design exploration, or a local demo is not evidence that a capability is available in the public release. ## What the current release does [#what-the-current-release-does] Today, Atlas helps you: * explore public county and state patterns; * review human disease, tick/vector, pathogen, environmental, population, and related context when released; * inspect the source, vintage, geography, release, method, completeness, and limitations behind a result; * compare supported geographies descriptively; and * turn a review-priority signal or evidence gap into a bounded investigation question. See [current capabilities](https://onehealthatlas.org/docs/current-capabilities) and [investigation workflows](https://onehealthatlas.org/docs/investigation-workflows) for the released behavior and task steps. ## What human review means [#what-human-review-means] Use an AI-assisted or analytical output as a prompt for review. A responsible reviewer should: 1. check the source and provenance; 2. verify that the geography, period, coverage, and method fit the question; 3. distinguish observed evidence from a derived score, contextual evidence, or modeled output; 4. state missing evidence and uncertainty rather than filling gaps with assumptions; and 5. decide whether source validation, local surveillance review, additional analysis, expert consultation, or no action is appropriate. If an output cannot show the evidence and limits needed for that review, treat it as unavailable. Do not infer certainty from fluent language, a rank, a map color, or an AI-generated summary. ## What Atlas AI is not for [#what-atlas-ai-is-not-for] Atlas does not: * diagnose Lyme disease or provide clinical or treatment advice; * predict an individual's exposure, infection, or disease risk; * guarantee that an outbreak will or will not occur; * prove that a vector, pathogen, environment, or population factor caused an outcome; * convert missing surveillance into evidence of absence or zero; or * make an automatic public-health decision or replace epidemiologists, analysts, local knowledge, or responsible authorities. The [AI Ethics commitments](https://onehealthatlas.org/ai-ethics) remain the public page for AI status, boundaries, and open decisions. Signed-in readers can open [AI / Responsible Use](https://onehealthatlas.org/app/ai-responsible-use) from the professional workspace footer for the same topic inside the workspace. That page uses capability-maturity labels and links here for methods. Privacy and data-use commitments belong on the [Privacy page](https://onehealthatlas.org/privacy); this guide does not add to either policy source. # API, MCP, and access (https://onehealthatlas.org/docs/api-mcp-and-access) > Use the public Atlas REST API, and see the current status of MCP and API keys. Atlas publishes one public HTTP contract. Human guides on this site explain how to use it. They do not copy a second schema. The [API reference](https://onehealthatlas.org/docs/api-reference) is generated from the pinned public OpenAPI contract and links the raw spec. Machine-readable definitions stay on the API service. ## What is available [#what-is-available] | Surface | Status | Where it lives | | --------------------------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Public REST API, version 1 | Available now | Anonymous read-only JSON at `https://api.onehealthatlas.org` | | OpenAPI schema | Available now | [OpenAPI schema](https://api.onehealthatlas.org/openapi.json) | | API reference | Available now | [Generated API reference](https://onehealthatlas.org/docs/api-reference) from that same public contract | | Interactive reference | Available now | [Swagger reference](https://api.onehealthatlas.org/docs) for approved public GET requests | | Read-only reference | Available now | [ReDoc reference](https://api.onehealthatlas.org/redoc) | | Bounded public MCP evidence tools | Available now | Anonymous read-only `atlas_discover_indicators`, `atlas_get_county_profile`, and `atlas_get_evidence_provenance` on the production MCP service. The [public evidence tool contract](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9/docs/public-evidence-tools.md) owns arguments and limits. | | MCP county identity | Available now | `atlas_resolve_geographies` resolves a county identity. Identity is not evidence availability, evidence adequacy, or comparability. | | MCP client transport | Available now | Anonymous Streamable HTTP at `https://mcp.onehealthatlas.org/mcp`. No API key and no OAuth. Client recipes are in [MCP clients](https://onehealthatlas.org/docs/develop/mcp-clients). | | Retired MCP smoke tools | Not supported | `server_status` and `atlas_smoke_test` are absent from the current production `tools/list`. | | User API keys in Settings | Not available | The public API does not use a key, and Settings does not create one | The OpenAPI application version and the `/v1` contract are different identifiers. Use the response fields below when you need to cite a result. ## Public reads do not use an API key [#public-reads-do-not-use-an-api-key] The canonical public API serves current-release metadata and county observations without an API key and without a signed-in session. A request is an HTTPS GET. Collections return `data`, `meta`, and `links`. A single resource returns `data`. Errors use `application/problem+json` with `code`, HTTP `status`, `detail`, and `request_id`. These routes do not select historical releases, aggregate arbitrary geographies, or return geometry. Account profile and privacy requests are separate account operations. Feedback submission accepts an optional account and still accepts a report when no account is present. Literature chat does not depend on an account session; `/assistant` and the legacy assistant drawer stay public and appear when that feature is enabled. The professional workspace at `/app` requires sign-in. Those operations sit outside this canonical public GET-read contract, so this page does not copy them as public examples. Settings can save a default jurisdiction for a signed-in reviewer. That preference is not an API credential. See [the professional workspace](https://onehealthatlas.org/docs/professional-workspace). Task-oriented requests, pagination, geography, and citation are in the [developer guides](https://onehealthatlas.org/docs/develop). Start with the [quickstart](https://onehealthatlas.org/docs/develop/quickstart). ## Examples from the public contract [#examples-from-the-public-contract] These requests use measure and county identifiers published for the current production release. County FIPS codes are five characters, with any leading zero preserved. `case_count_floor_2023` is a privacy-protected case floor in `cases`, not a complete incidence count and not a diagnosis. ```sh curl -fsS 'https://api.onehealthatlas.org/v1/indicators?page_size=10' curl -fsS 'https://api.onehealthatlas.org/v1/measures?indicator_id=human_disease_burden&page_size=10' curl -fsS 'https://api.onehealthatlas.org/v1/measures/case_count_floor_2023' curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=08001&year=2023' ``` Compare two counties by repeating `geography_id`. Use `year` or a complete `start_date` and `end_date` pair. The published county observations for this release are the annual 2023 period. ```sh curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=08001&geography_id=08003&year=2023&page_size=1' ``` If `meta.next_page_token` is present, send it back as `page_token` with every other query parameter unchanged. Stop when the token is null. Tokens are opaque and bound to that query and release. A changed or rejected token means you start again at the first page. A page token is not a citation. Follow `source_id` and `methodology_id` on an observation when you need publisher, vintage, and method limitations: ```sh curl -fsS 'https://api.onehealthatlas.org/v1/sources/human' curl -fsS 'https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1' ``` Read `value_state` with `value` and `unit`. The public states are `OBSERVED`, `ZERO`, `MISSING`, `SUPPRESSED`, `UNAVAILABLE`, `NO_COUNTY_LINKED_RECORD`, and `NO_RECORDS`. `MISSING`, `UNAVAILABLE`, and `NO_COUNTY_LINKED_RECORD` are gaps. `NO_RECORDS` retains CDC's `No records` and does not establish biological absence. `SUPPRESSED` is a privacy-protected observation: the value was withheld, and the workspace shows **Suppressed** rather than a number. Do not replace a gap or a suppressed observation with zero. A published `ZERO` stays a real zero. The same rule is explained for reviewers in [evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty). ## Limits and errors [#limits-and-errors] The observation query needs one measure, `geography_type=county`, one or more five-digit county FIPS codes, and either `year` or both dates. The service rejects unsupported filters, strata, sorting, and aggregation instead of ignoring them. Problem `code` values include `RESOURCE_NOT_FOUND`, `INVALID_REQUEST`, `UNSUPPORTED_FILTER`, and `UNSUPPORTED_STRATIFICATION`. Keep `request_id` if you need support. `429` and `503` responses include `Retry-After` when the service supplies it. The header is a number of seconds. The public OpenAPI document does not publish a numeric quota or concurrency cap, so this guide does not state one. Wait for `Retry-After`, then retry the same request. Discovery collections use a short public cache. Stable detail responses may include an `ETag`; send `If-None-Match` to receive `304` when the representation is unchanged. The [OpenAPI schema](https://api.onehealthatlas.org/openapi.json) is the authority for parameters, status codes, and schema fields. The [REST API](https://onehealthatlas.org/docs/develop/rest) guide explains pagination, problem codes, and version fields. ## Reproduce a result [#reproduce-a-result] Save the request URL, measure id, county FIPS codes, period, `release_id`, `semantic_version`, methodology id and version, source id, lineage source id, dataset id, source vintage, and limitations. These routes read the current release. The same URL can change after a later release. A saved response, or a checksum of that response, is the record of what you retrieved. A practical attribution names Atlas, the public API V1, the measure id, county FIPS, period, release id, semantic version, retrieval date, and the upstream publisher and dataset from the source resource you received. Replace every example identifier with the values in your response. ## Canonical evidence for API and MCP consumers [#canonical-evidence-for-api-and-mcp-consumers] Public REST reads return governed Atlas resources. Indicators, measures, observations, sources, and methodologies are that contract for current-release evidence. Clients are intended to use those resources rather than a schema that changes with each upstream source. The [OpenAPI schema](https://api.onehealthatlas.org/openapi.json) remains authoritative for HTTP fields. The generated [API reference](https://onehealthatlas.org/docs/api-reference) is rendered from the pinned public contract. MCP tool definitions stay in the [Atlas MCP repository](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp) and its tests. The released evidence tools return the same canonical evidence and provenance, including source identity and value state, rather than a schema that changes with each source. [Sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence) describes that design, the open-data boundary, and the clinical connections that are not released. [Provenance and evidence](https://onehealthatlas.org/docs/develop/provenance) lists the fields to keep with a value. ## MCP [#mcp] The MCP server is owned by the [Atlas MCP repository](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp). [ADR 0003](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9/docs/adr/0003-public-evidence-tools.md) accepts three anonymous read-only evidence tools and supersedes the historical smoke-only exposure constraint for that bounded surface. The [production receipt](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/pull/21#issuecomment-6116902766) records deployment of SHA `d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9` and official-SDK discovery of exactly six tools; that receipt is historical. On 2026-10-18, `tools/list` at `https://mcp.onehealthatlas.org/mcp` returned exactly four tools. Client setup for that endpoint is in [MCP clients](https://onehealthatlas.org/docs/develop/mcp-clients). This guide does not copy tool schemas. | Tool | What the contract allows | | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `atlas_discover_indicators` | Published indicators and their associated measures. Discovery states published definitions. It is not county availability. | | `atlas_get_county_profile` | Published observations for one exact five-digit county FIPS and one to three explicit measure-period selections. An empty selection is not a missing row, a zero, biological absence, or proof of county identity. | | `atlas_get_evidence_provenance` | A published source or methodology for the expected current release. It does not resolve an arbitrary observation ID or a historical release. | | `atlas_resolve_geographies` | County identity only, from the CDC/ATSDR SVI 2022 county source. Identity does not establish observations, evidence adequacy, or comparability, and it is not a current legal-boundary file. | | `server_status`, `atlas_smoke_test` | Not in the current production tool list. A call is an unknown-tool error. `GET /healthz` reports process health and does not read evidence. | The [public evidence tool contract](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9/docs/public-evidence-tools.md) is authoritative for arguments, bounds, and error codes. This page does not copy those schemas. Evidence tools keep canonical API value states, units, denominators, source identity, and limitations. They do not score, diagnose, compare scientifically, write, or accept private data or a caller-supplied URL. They are not a live EHR, TEFCA, patient-level, PHI, or production clinical-laboratory connection. The [2026-09-26 development record](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/e897207640919a9d6464233ade885ed5d9df8227/docs/operations/digitalocean-mcp.md) accepted `server_status` and `atlas_smoke_test` in [`server.py`](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/e897207640919a9d6464233ade885ed5d9df8227/src/atlas_lyme_mcp/server.py). That smoke-only receipt is historical. It is not the current production tool list. REST remains the HTTP contract for the same canonical resources. OpenAPI remains authoritative for HTTP schemas. MCP does not replace that document. ## API keys [#api-keys] Do not send an API key, bearer token, or Settings secret on the public read routes. They are not authenticated that way. The professional workspace Settings page does not generate, show, copy, revoke, or regenerate a user API key. Planned key-management controls, including any future one-time secret display, are outside this release. Do not store a guessed credential in the browser or in a docs example. Signed-in product features use the account session inside Atlas. That session is not a public API key and is not a substitute for the anonymous `/v1` reads above. # API reference (https://onehealthatlas.org/docs/api-reference) > Generated from the pinned public Atlas OpenAPI contract, with spec version, source, and the raw schema. This page is generated from the public OpenAPI contract. It is not a second hand-maintained endpoint catalog. Tags, operation IDs, parameters, schemas, examples, and errors are rendered from that contract by the native OpenAPI reference. ## Spec version and source [#spec-version-and-source] | Label | Value | | ------------------- | ------------------------------------------------------------------ | | OpenAPI version | `3.1.0` | | Application version | `0.1.0` | | HTTP contract | `/v1` | | Source repository | `Caraway-Labs/one-health-lyme-gap-atlas-api` | | Source commit | `d0472707cfc2badae714a797ec54c83d4f7ad79b` | | Source file | `openapi.json` | | Checksum | `c0a4e2ea4f15a543c3fc1e7705e2e4691cbc7e3ace9910d159b3814d3c049d6a` | Application version `0.1.0` identifies the OpenAPI `info.version` field. The HTTP contract is `/v1`. Those identifiers are different. This reference build is identified by the source commit and checksum. Raw spec: [OpenAPI schema](https://api.onehealthatlas.org/openapi.json). Pinned source: [Caraway-Labs/one-health-lyme-gap-atlas-api@d0472707cfc2badae714a797ec54c83d4f7ad79b](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-api/blob/d0472707cfc2badae714a797ec54c83d4f7ad79b/openapi.json). ## Servers [#servers] * `https://api.onehealthatlas.org` (Production) ## External documentation [#external-documentation] [Atlas documentation and developer guides](https://onehealthatlas.org/docs) **Governed Atlas analytics, metadata, and provenance** Read-only structured data from the One Health Lyme Gap Atlas. Ordinary public reads are anonymous and require no API key. ## Interpretation and reproducibility [#interpretation-and-reproducibility] V1 (`/v1`) is the HTTP contract version; the application version is separate. Read source, methodology, semantic/release versions, and limitations together. Surveillance floors and gap scores are not diagnoses, individual risk estimates, or causal claims. Null, zero, suppressed values, and no linked records have distinct meanings. Response time is not publisher freshness. ## Queries and errors [#queries-and-errors] Canonical collections use `data`, `meta`, and `links`; details use `data`. Pagination defaults to 100 items (maximum 500). Send opaque `next_page_token` as `page_token` with the same filters; null means exhaustion. Tokens bind to query/release and may expire on restart. Current-release observations require one measure, 1–500 county FIPS IDs, and a year or complete inclusive date range. The default pre-execution logical-result ceiling is 10,000, not truncation. Only the annual 2023 period is currently published; no strata are supported. Errors use RFC 9457 `application/problem+json` with `request_id` for support. Canonical errors carry stable `code` values; legacy Atlas routes retain their existing error semantics (including 422 validation). Respect `Retry-After` on 429/503. Canonical metadata/observations cache for 60 seconds; supported detail resources return ETags and 304 on matching `If-None-Match`. See each operation for legacy cache and export behavior. ## Contract consumers [#contract-consumers] Fumadocs, `/docs`, and `/redoc` consume the canonical public `openapi.json` at `/openapi.json`. Internal product operations are not part of this contract. Existing operation IDs remain stable for generated clients. Breaking public changes require an approved migration and deprecation plan; optional additive fields may appear within V1. Only separately approved ML outputs may be published. Internal conversational AI, literature retrieval, account, and feedback product routes are excluded. ## Operations [#operations] ### Canonical Evidence [#canonical-evidence] #### discovery [#discovery] Current-release indicators and measurable variables. * [`GET /v1/indicators`](https://onehealthatlas.org/docs/api-reference/discovery/indicators_v1_indicators_get) — Discover indicators — `indicators_v1_indicators_get` * [`GET /v1/indicators/{indicator_id}`](https://onehealthatlas.org/docs/api-reference/discovery/indicator_v1_indicators__indicator_id__get) — Get an indicator — `indicator_v1_indicators__indicator_id__get` * [`GET /v1/measures`](https://onehealthatlas.org/docs/api-reference/discovery/measures_v1_measures_get) — Discover measures — `measures_v1_measures_get` * [`GET /v1/measures/{measure_id}`](https://onehealthatlas.org/docs/api-reference/discovery/measure_v1_measures__measure_id__get) — Get a measure — `measure_v1_measures__measure_id__get` #### observations [#observations] Bounded county observations with explicit value states. * [`GET /v1/observations`](https://onehealthatlas.org/docs/api-reference/observations/observations_v1_observations_get) — Query county observations — `observations_v1_observations_get` #### provenance [#provenance] Governed source and methodology identities and versions. * [`GET /v1/methodologies/{methodology_id}`](https://onehealthatlas.org/docs/api-reference/provenance/methodology_v1_methodologies__methodology_id__get) — Get a methodology — `methodology_v1_methodologies__methodology_id__get` * [`GET /v1/sources`](https://onehealthatlas.org/docs/api-reference/provenance/sources_v1_sources_get) — Discover sources — `sources_v1_sources_get` * [`GET /v1/sources/{source_id}`](https://onehealthatlas.org/docs/api-reference/provenance/source_v1_sources__source_id__get) — Get a source — `source_v1_sources__source_id__get` #### geographies [#geographies] Typed geography identity; delivery is not yet available. * [`GET /v1/geographies/{geography_type}/{geography_id}`](https://onehealthatlas.org/docs/api-reference/geographies/geography_v1_geographies__geography_type___geography_id__get) — Get geography identity (delivery pending) — `geography_v1_geographies__geography_type___geography_id__get` Delivery pending at the last production check, 18 October 2026. Production API, 18 October 2026. This is not a live health indicator. * [`GET /v1/geographies/{geography_type}/{geography_id}/availability`](https://onehealthatlas.org/docs/api-reference/geographies/canonicalGeographyAvailability) — Check canonical county geography publication availability — `canonicalGeographyAvailability` ### Atlas Analytics/Reports [#atlas-analyticsreports] #### atlas [#atlas] Existing release analytics and separate display geometry. * [`GET /v1/atlas/geometry`](https://onehealthatlas.org/docs/api-reference/atlas/geometry_v1_atlas_geometry_get) — Get county display geometry — `geometry_v1_atlas_geometry_get` * [`GET /v1/atlas/metadata`](https://onehealthatlas.org/docs/api-reference/atlas/metadata_v1_atlas_metadata_get) — Get Atlas release metadata — `metadata_v1_atlas_metadata_get` * [`GET /v1/atlas/ranking.csv`](https://onehealthatlas.org/docs/api-reference/atlas/ranking_csv_v1_atlas_ranking_csv_get) — Download filtered county rankings — `ranking_csv_v1_atlas_ranking_csv_get` * [`GET /v1/atlas/scores`](https://onehealthatlas.org/docs/api-reference/atlas/scores_v1_atlas_scores_get) — Get county gap scores — `scores_v1_atlas_scores_get` #### counties [#counties] Existing county details and versioned PDF reports. * [`GET /v1/counties/{fips}`](https://onehealthatlas.org/docs/api-reference/counties/county_v1_counties__fips__get) — Get county analytics and provenance — `county_v1_counties__fips__get` * [`GET /v1/counties/{fips}/report.pdf`](https://onehealthatlas.org/docs/api-reference/counties/county_report_pdf_v1_counties__fips__report_pdf_get) — Download a county report — `county_report_pdf_v1_counties__fips__report_pdf_get` * [`GET /v1/counties/{fips}/tier1-surveillance-priority`](https://onehealthatlas.org/docs/api-reference/counties/county_tier1_surveillance_priority_get) — Get persisted Tier 1 model-assisted surveillance review priority — `county_tier1_surveillance_priority_get` * [`GET /v1/counties/{fips}/tier1-surveillance-priority/availability`](https://onehealthatlas.org/docs/api-reference/counties/county_tier1_surveillance_priority_availability_get) — Get Tier 1 result availability and persisted data — `county_tier1_surveillance_priority_availability_get` #### states [#states] Existing state PDF reports. * [`GET /v1/states/{state}/report.pdf`](https://onehealthatlas.org/docs/api-reference/states/state_report_pdf_v1_states__state__report_pdf_get) — Download a state report — `state_report_pdf_v1_states__state__report_pdf_get` * [`GET /v1/states/{state}/review`](https://onehealthatlas.org/docs/api-reference/states/state_review_v1_states__state__review_get) — Review a state's county evidence — `state_review_v1_states__state__review_get` Component schemas: [Schemas](https://onehealthatlas.org/docs/api-reference/schemas) (50). # Atlas (https://onehealthatlas.org/docs/api-reference/atlas) > Existing release analytics and separate display geometry. Generated from the public OpenAPI contract. Existing release analytics and separate display geometry. ## Get county display geometry [#geometry_v1_atlas_geometry_get] `GET /v1/atlas/geometry` Operation ID: `geometry_v1_atlas_geometry_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/atlas/geometry_v1_atlas_geometry_get). ## Get Atlas release metadata [#metadata_v1_atlas_metadata_get] `GET /v1/atlas/metadata` Operation ID: `metadata_v1_atlas_metadata_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/atlas/metadata_v1_atlas_metadata_get). ## Download filtered county rankings [#ranking_csv_v1_atlas_ranking_csv_get] `GET /v1/atlas/ranking.csv` Operation ID: `ranking_csv_v1_atlas_ranking_csv_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/atlas/ranking_csv_v1_atlas_ranking_csv_get). ## Get county gap scores [#scores_v1_atlas_scores_get] `GET /v1/atlas/scores` Operation ID: `scores_v1_atlas_scores_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/atlas/scores_v1_atlas_scores_get). # Get county display geometry (https://onehealthatlas.org/docs/api-reference/atlas/geometry_v1_atlas_geometry_get) > Existing generalized CDC/ATSDR SVI 2022 display geometry in EPSG:4326, identified by stable five-digit county FIPS. This resource never returns internal 2025 TIGER/Line analysis polygons used for raster aggregation. ## GET /v1/atlas/geometry Operation ID: `geometry_v1_atlas_geometry_get`. Get county display geometry Existing generalized CDC/ATSDR SVI 2022 display geometry in EPSG:4326, identified by stable five-digit county FIPS. This resource never returns internal 2025 TIGER/Line analysis polygons used for raster aggregation. ### Parameters #### dataset_version query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | ### Responses #### 200 Display GeoJSON, EPSG:4326; immutable TTL 31536000; ETag. - Media type: `application/geo+json` - Response schema: `object` #### 304 Matching If-None-Match; empty body. #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/atlas/geometry", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/atlas/geometry", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/atlas/geometry", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/atlas/geometry", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Get Atlas release metadata (https://onehealthatlas.org/docs/api-reference/atlas/metadata_v1_atlas_metadata_get) > Release metadata, source freshness and methodology; dataset_version selects an existing release. Cached publicly for 300 seconds with ETag. ETag is informational here; this route does not implement conditional 304. ## GET /v1/atlas/metadata Operation ID: `metadata_v1_atlas_metadata_get`. Get Atlas release metadata Release metadata, source freshness and methodology; dataset_version selects an existing release. Cached publicly for 300 seconds with ETag. ETag is informational here; this route does not implement conditional 304. ### Parameters #### dataset_version query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | ### Responses #### 200 Successful Response - Media type: `application/json` - Response schema: `AtlasMetadata` #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/atlas/metadata", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/atlas/metadata", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/atlas/metadata", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/atlas/metadata", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Download filtered county rankings (https://onehealthatlas.org/docs/api-reference/atlas/ranking_csv_v1_atlas_ranking_csv_get) > Filtered CSV attachment for current county rankings. Existing state, text and evidence filters and score settings apply; no pagination. This route does not declare a public cache TTL. ## GET /v1/atlas/ranking.csv Operation ID: `ranking_csv_v1_atlas_ranking_csv_get`. Download filtered county rankings Filtered CSV attachment for current county rankings. Existing state, text and evidence filters and score settings apply; no pagination. This route does not declare a public cache TTL. ### Parameters #### state query, optional. | Constraint | Value | | --- | --- | | Schema | `string` | | Default | `ALL` | | Pattern | `^(ALL\|[A-Z]{2})$` | #### q query, optional. | Constraint | Value | | --- | --- | | Schema | `string` | | Default | `` | | Maximum length | `100` | #### evidence query, optional. | Constraint | Value | | --- | --- | | Schema | `string` | | Default | `all` | | Enum | `all, ecological, human, complete` | #### ecological_share query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `65` | | Minimum | `40` | | Maximum | `85` | | Multiple of | `5` | #### low_incidence_breakpoint query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `10` | | Minimum | `5` | | Maximum | `25` | #### missing_human_weakness query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `75` | | Minimum | `40` | | Maximum | `90` | | Multiple of | `5` | ### Responses #### 200 CSV attachment. - Media type: `text/csv` - Response schema: `string` #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/atlas/ranking.csv", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/atlas/ranking.csv", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/atlas/ranking.csv", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/atlas/ranking.csv", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Get county gap scores (https://onehealthatlas.org/docs/api-reference/atlas/scores_v1_atlas_scores_get) > Existing surveillance-gap scores and settings for an optional dataset_version. Scores are not individual risk estimates or diagnoses. Public cache TTL 300 seconds with informational ETag; no conditional 304. ## GET /v1/atlas/scores Operation ID: `scores_v1_atlas_scores_get`. Get county gap scores Existing surveillance-gap scores and settings for an optional dataset_version. Scores are not individual risk estimates or diagnoses. Public cache TTL 300 seconds with informational ETag; no conditional 304. ### Parameters #### dataset_version query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | #### ecological_share query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `65` | | Minimum | `40` | | Maximum | `85` | | Multiple of | `5` | #### low_incidence_breakpoint query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `10` | | Minimum | `5` | | Maximum | `25` | #### missing_human_weakness query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `75` | | Minimum | `40` | | Maximum | `90` | | Multiple of | `5` | ### Responses #### 200 Successful Response - Media type: `application/json` - Response schema: `ScoreCollection` #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/atlas/scores", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/atlas/scores", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/atlas/scores", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/atlas/scores", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Counties (https://onehealthatlas.org/docs/api-reference/counties) > Existing county details and versioned PDF reports. Generated from the public OpenAPI contract. Existing county details and versioned PDF reports. ## Get county analytics and provenance [#county_v1_counties__fips__get] `GET /v1/counties/{fips}` Operation ID: `county_v1_counties__fips__get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/counties/county_v1_counties__fips__get). ## Download a county report [#county_report_pdf_v1_counties__fips__report_pdf_get] `GET /v1/counties/{fips}/report.pdf` Operation ID: `county_report_pdf_v1_counties__fips__report_pdf_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/counties/county_report_pdf_v1_counties__fips__report_pdf_get). ### Template selection [#template-selection] Choose `template` on `GET /v1/counties/{fips}/report.pdf`. The default is `county-v1`. Use a county FIPS in the lower 48 states or the District of Columbia. A scoring PDF is a review-priority report. An evidence PDF repeats canonical observations, lineage, value states, and limitations. Neither report is a diagnosis, an individual risk estimate, or a causal claim. The same selector rules, with the requests checked against the published API, are in the [workflow guides](https://onehealthatlas.org/docs/develop/workflows#download-a-county-report). ### county-v1 scoring `county-v1` is the scoring selector. `dataset_version` is optional. These score settings are optional and bind the scoring inputs: | Parameter | Default | Bounds | | -------------------------- | ------- | -------------------- | | `ecological_share` | 65 | 40–85, multiple of 5 | | `low_incidence_breakpoint` | 10 | 5–25 | | `missing_human_weakness` | 75 | 40–90, multiple of 5 | `period_start`, `period_end`, and `measure_id` are forbidden on `county-v1`. Sending one of them returns HTTP `422`. Checked on 18 October 2026 for FIPS `36061`: ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "Observation context requires county-v2.", "instance": "/v1/counties/36061/report.pdf", "request_id": "example-request-id", "errors": null } ``` An unknown registered-pattern template returns HTTP `422` with detail `The requested county report template is not available.` A template outside `^[a-z]+-v\d+$` returns HTTP `422` with detail `One or more request values are invalid.` A successful county-v1 response uses `Cache-Control: public, max-age=300, must-revalidate`. `ETag` with `If-None-Match` can return `304`. ```sh curl -fsS 'https://api.onehealthatlas.org/v1/counties/36061/report.pdf?template=county-v1' ``` ### county-v2 evidence `county-v2` is the evidence selector. It requires `dataset_version`, `period_start`, `period_end`, and `measure_id`. Pass the observation `release_id` as `dataset_version`. `period_start` and `period_end` are the exact inclusive dates. `measure_id` accepts 1–20 distinct ids, repeated or comma-separated. A missing release, period, or measure list, a duplicate measure id, more than 20 ids, or a reversed period returns HTTP `422`. Checked on 18 October 2026: ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "county-v2 requires release, exact period and distinct measures.", "instance": "/v1/counties/36061/report.pdf", "request_id": "example-request-id", "errors": null } ``` An unknown measure returns HTTP `404` `RESOURCE_NOT_FOUND`. The contract also returns HTTP `503` when provenance is missing or mismatched, and HTTP `413` when the report exceeds resource limits. Score settings are the county-v1 inputs above. A checked county-v2 request that also sent `ecological_share=65` still returned HTTP `200` and `Cache-Control: no-store`. A successful county-v2 response uses `Cache-Control: no-store`. The service revalidates authoritative context before a cache response or `304`. `ETag` is still present. Replace `RELEASE_ID` with the observation `release_id`: ```sh curl -fsS 'https://api.onehealthatlas.org/v1/counties/36061/report.pdf?template=county-v2&dataset_version=RELEASE_ID&period_start=2023-01-01&period_end=2023-12-31&measure_id=case_count_floor_2023' ``` The same checked requests are in the [workflow guides](https://onehealthatlas.org/docs/develop/workflows#download-a-county-report). ## Get persisted Tier 1 model-assisted surveillance review priority [#county_tier1_surveillance_priority_get] `GET /v1/counties/{fips}/tier1-surveillance-priority` Operation ID: `county_tier1_surveillance_priority_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/counties/county_tier1_surveillance_priority_get). ## Get Tier 1 result availability and persisted data [#county_tier1_surveillance_priority_availability_get] `GET /v1/counties/{fips}/tier1-surveillance-priority/availability` Operation ID: `county_tier1_surveillance_priority_availability_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/counties/county_tier1_surveillance_priority_availability_get). # Download a county report (https://onehealthatlas.org/docs/api-reference/counties/county_report_pdf_v1_counties__fips__report_pdf_get) > PDF attachment using the immutable county-v1 registered template by default. Optional dataset_version and score settings bind report inputs. Opt-in county-v2 requires dataset_version, period_start, period_end and repeated measure_id (1–20, repeated or comma-separated); reads canonical evidence, lineage, value states and limitations. Missing or mismatched provenance returns 503; unknown observations return 404. V1 rejects observation selectors with 422. V2 responses use no-store and revalidate authoritative context before cache/304. ETag/If-None-Match supports 304; V1 public cache TTL 300 seconds with revalidation. Unknown templates return 422; resource limits 413; renderer failure/timeout 503. ## GET /v1/counties/{fips}/report.pdf Operation ID: `county_report_pdf_v1_counties__fips__report_pdf_get`. Download a county report PDF attachment using the immutable county-v1 registered template by default. Optional dataset_version and score settings bind report inputs. Opt-in county-v2 requires dataset_version, period_start, period_end and repeated measure_id (1–20, repeated or comma-separated); reads canonical evidence, lineage, value states and limitations. Missing or mismatched provenance returns 503; unknown observations return 404. V1 rejects observation selectors with 422. V2 responses use no-store and revalidate authoritative context before cache/304. ETag/If-None-Match supports 304; V1 public cache TTL 300 seconds with revalidation. Unknown templates return 422; resource limits 413; renderer failure/timeout 503. ### Parameters #### fips path, required. | Constraint | Value | | --- | --- | | Schema | `string` | | Pattern | `^\d{5}$` | #### dataset_version query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | #### period_start query, optional. Exact inclusive observation start for county-v2. | Constraint | Value | | --- | --- | | Schema | `string \| null` | | Format | `date` | #### period_end query, optional. Exact inclusive observation end for county-v2. | Constraint | Value | | --- | --- | | Schema | `string \| null` | | Format | `date` | #### measure_id query, optional. 1–20 measure IDs; repeated or comma-separated for county-v2. | Constraint | Value | | --- | --- | | Schema | `array of string` | | Maximum items | `20` | #### template query, optional. | Constraint | Value | | --- | --- | | Schema | `string` | | Default | `county-v1` | | Pattern | `^[a-z]+-v\d+$` | #### ecological_share query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `65` | | Minimum | `40` | | Maximum | `85` | | Multiple of | `5` | #### low_incidence_breakpoint query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `10` | | Minimum | `5` | | Maximum | `25` | #### missing_human_weakness query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `75` | | Minimum | `40` | | Maximum | `90` | | Multiple of | `5` | ### Responses #### 200 PDF attachment. - Media type: `application/pdf` - Response schema: `string` #### 304 Matching If-None-Match; empty body. #### 400 Narrow the observation period. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "Narrow the observation period.", "instance": "/v1/counties/{fips}/report.pdf", "request_id": "example-request-id", "code": "QUERY_TOO_BROAD" } ``` #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/counties/{fips}/report.pdf", "request_id": "example-request-id" } ``` #### 413 The report exceeds configured resource limits. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "The report exceeds configured resource limits.", "instance": "/v1/counties/{fips}/report.pdf", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/counties/{fips}/report.pdf", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/counties/{fips}/report.pdf", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/counties/{fips}/report.pdf", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Get Tier 1 result availability and persisted data (https://onehealthatlas.org/docs/api-reference/counties/county_tier1_surveillance_priority_availability_get) > Additive availability contract for current supported county geographies. A successful lookup returns AVAILABLE with the exact persisted result, or UNAVAILABLE with reason NO_PUBLISHED_MODEL and null data after the current geography release and Tier 1 projection have both been read successfully. geography_release_id identifies the release used to validate the FIPS. This endpoint does not turn null into zero or synthesize model output. NOT_ESTIMABLE is a persisted result state and is distinct from no published model result. Malformed FIPS returns 422; an identity outside the current geography release returns typed 404; dependency or malformed-data failures return 503. Public cache TTL 60 seconds. ## GET /v1/counties/{fips}/tier1-surveillance-priority/availability Operation ID: `county_tier1_surveillance_priority_availability_get`. Get Tier 1 result availability and persisted data Additive availability contract for current supported county geographies. A successful lookup returns AVAILABLE with the exact persisted result, or UNAVAILABLE with reason NO_PUBLISHED_MODEL and null data after the current geography release and Tier 1 projection have both been read successfully. geography_release_id identifies the release used to validate the FIPS. This endpoint does not turn null into zero or synthesize model output. NOT_ESTIMABLE is a persisted result state and is distinct from no published model result. Malformed FIPS returns 422; an identity outside the current geography release returns typed 404; dependency or malformed-data failures return 503. Public cache TTL 60 seconds. ### Parameters #### fips path, required. | Constraint | Value | | --- | --- | | Schema | `string` | | Pattern | `^\d{5}$` | ### Responses #### 200 Successful Response - Media type: `application/json` - Response schema: `Tier1CountyPriorityAvailability` #### 404 County is not in the current geography release. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County is not in the current geography release.", "instance": "/v1/counties/{fips}/tier1-surveillance-priority/availability", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/counties/{fips}/tier1-surveillance-priority/availability", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/counties/{fips}/tier1-surveillance-priority/availability", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/counties/{fips}/tier1-surveillance-priority/availability", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Get persisted Tier 1 model-assisted surveillance review priority (https://onehealthatlas.org/docs/api-reference/counties/county_tier1_surveillance_priority_get) > Returns the approved persisted county result from the current Tier 1 batch. This is surveillance review priority, not Lyme disease risk, predicted incidence, probability, clinical risk, or diagnosis. LOW is a scored tier; evidence sufficiency is separate. Percentile is relative to the scored batch and population. A county without a persisted result returns 404; an unavailable current view or malformed result returns 503. Public cache TTL 60 seconds; generated_at_utc is the model batch time, not request time. ## GET /v1/counties/{fips}/tier1-surveillance-priority Operation ID: `county_tier1_surveillance_priority_get`. Get persisted Tier 1 model-assisted surveillance review priority Returns the approved persisted county result from the current Tier 1 batch. This is surveillance review priority, not Lyme disease risk, predicted incidence, probability, clinical risk, or diagnosis. LOW is a scored tier; evidence sufficiency is separate. Percentile is relative to the scored batch and population. A county without a persisted result returns 404; an unavailable current view or malformed result returns 503. Public cache TTL 60 seconds; generated_at_utc is the model batch time, not request time. ### Parameters #### fips path, required. | Constraint | Value | | --- | --- | | Schema | `string` | | Pattern | `^\d{5}$` | ### Responses #### 200 Successful Response - Media type: `application/json` - Response schema: `Tier1CountyPriority` #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/counties/{fips}/tier1-surveillance-priority", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/counties/{fips}/tier1-surveillance-priority", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/counties/{fips}/tier1-surveillance-priority", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/counties/{fips}/tier1-surveillance-priority", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Get county analytics and provenance (https://onehealthatlas.org/docs/api-reference/counties/county_v1_counties__fips__get) > Five-digit county FIPS with leading zeros retained. Includes release/source metadata and limitations. Optional dataset_version and score settings retain existing meanings. Public cache TTL 300 seconds with informational ETag; no conditional 304. ## GET /v1/counties/{fips} Operation ID: `county_v1_counties__fips__get`. Get county analytics and provenance Five-digit county FIPS with leading zeros retained. Includes release/source metadata and limitations. Optional dataset_version and score settings retain existing meanings. Public cache TTL 300 seconds with informational ETag; no conditional 304. ### Parameters #### fips path, required. | Constraint | Value | | --- | --- | | Schema | `string` | | Pattern | `^\d{5}$` | #### dataset_version query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | #### ecological_share query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `65` | | Minimum | `40` | | Maximum | `85` | | Multiple of | `5` | #### low_incidence_breakpoint query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `10` | | Minimum | `5` | | Maximum | `25` | #### missing_human_weakness query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `75` | | Minimum | `40` | | Maximum | `90` | | Multiple of | `5` | ### Responses #### 200 Successful Response - Media type: `application/json` - Response schema: `CountyDetail` #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/counties/{fips}", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/counties/{fips}", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/counties/{fips}", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/counties/{fips}", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Discovery (https://onehealthatlas.org/docs/api-reference/discovery) > Current-release indicators and measurable variables. Generated from the public OpenAPI contract. Current-release indicators and measurable variables. ## Discover indicators [#indicators_v1_indicators_get] `GET /v1/indicators` Operation ID: `indicators_v1_indicators_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/discovery/indicators_v1_indicators_get). ## Get an indicator [#indicator_v1_indicators__indicator_id__get] `GET /v1/indicators/{indicator_id}` Operation ID: `indicator_v1_indicators__indicator_id__get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/discovery/indicator_v1_indicators__indicator_id__get). ## Discover measures [#measures_v1_measures_get] `GET /v1/measures` Operation ID: `measures_v1_measures_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/discovery/measures_v1_measures_get). ## Get a measure [#measure_v1_measures__measure_id__get] `GET /v1/measures/{measure_id}` Operation ID: `measure_v1_measures__measure_id__get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/discovery/measure_v1_measures__measure_id__get). # Get an indicator (https://onehealthatlas.org/docs/api-reference/discovery/indicator_v1_indicators__indicator_id__get) > Resolve the exact governed public resource ID in the current release. Unknown IDs return 404 RESOURCE_NOT_FOUND. Preserve versions and limitations; null metadata is not inferred. Cache-Control: public, max-age=60, must-revalidate; ETag with matching If-None-Match returns an empty 304. ## GET /v1/indicators/{indicator_id} Operation ID: `indicator_v1_indicators__indicator_id__get`. Get an indicator Resolve the exact governed public resource ID in the current release. Unknown IDs return 404 RESOURCE_NOT_FOUND. Preserve versions and limitations; null metadata is not inferred. Cache-Control: public, max-age=60, must-revalidate; ETag with matching If-None-Match returns an empty 304. ### Parameters #### indicator_id path, required. | Constraint | Value | | --- | --- | | Schema | `string` | ### Responses #### 200 Successful current-release resource. - Media type: `application/json` - Response schema: `ResourceEnvelope_Indicator_` #### 304 Not modified. ETag matches If-None-Match; empty response body. #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/indicators/{indicator_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/indicators/{indicator_id}", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/indicators/{indicator_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/indicators/{indicator_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/indicators/{indicator_id}", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/indicators/{indicator_id}", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Discover indicators (https://onehealthatlas.org/docs/api-reference/discovery/indicators_v1_indicators_get) > Current-release discovery with optional documented filters. page_size defaults to 100 (maximum 500); reuse opaque page_token with the same filters and release. A null next_page_token ends traversal. Cache-Control: public, max-age=60, must-revalidate. ## GET /v1/indicators Operation ID: `indicators_v1_indicators_get`. Discover indicators Current-release discovery with optional documented filters. page_size defaults to 100 (maximum 500); reuse opaque page_token with the same filters and release. A null next_page_token ends traversal. Cache-Control: public, max-age=60, must-revalidate. ### Parameters #### indicator_id query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | #### page_size query, optional. Items per page; defaults to 100, configured maximum at most 500. | Constraint | Value | | --- | --- | | Schema | `integer \| null` | | Default | `100` | | Minimum | `1` | | Maximum | `500` | Example: ```json 100 ``` #### page_token query, optional. Opaque next_page_token; retain query filters and release. | Constraint | Value | | --- | --- | | Schema | `string \| null` | ### Responses #### 200 Successful current-release resource. - Media type: `application/json` - Response schema: `CollectionEnvelope_Indicator_` #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/indicators", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/indicators", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/indicators", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/indicators", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/indicators", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/indicators", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Get a measure (https://onehealthatlas.org/docs/api-reference/discovery/measure_v1_measures__measure_id__get) > Resolve the exact governed public resource ID in the current release. Unknown IDs return 404 RESOURCE_NOT_FOUND. Preserve versions and limitations; null metadata is not inferred. Cache-Control: public, max-age=60, must-revalidate; ETag with matching If-None-Match returns an empty 304. ## GET /v1/measures/{measure_id} Operation ID: `measure_v1_measures__measure_id__get`. Get a measure Resolve the exact governed public resource ID in the current release. Unknown IDs return 404 RESOURCE_NOT_FOUND. Preserve versions and limitations; null metadata is not inferred. Cache-Control: public, max-age=60, must-revalidate; ETag with matching If-None-Match returns an empty 304. ### Parameters #### measure_id path, required. | Constraint | Value | | --- | --- | | Schema | `string` | ### Responses #### 200 Successful current-release resource. - Media type: `application/json` - Response schema: `ResourceEnvelope_Measure_` #### 304 Not modified. ETag matches If-None-Match; empty response body. #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/measures/{measure_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/measures/{measure_id}", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/measures/{measure_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/measures/{measure_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/measures/{measure_id}", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/measures/{measure_id}", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Discover measures (https://onehealthatlas.org/docs/api-reference/discovery/measures_v1_measures_get) > Current-release discovery with optional documented filters. page_size defaults to 100 (maximum 500); reuse opaque page_token with the same filters and release. A null next_page_token ends traversal. Cache-Control: public, max-age=60, must-revalidate. ## GET /v1/measures Operation ID: `measures_v1_measures_get`. Discover measures Current-release discovery with optional documented filters. page_size defaults to 100 (maximum 500); reuse opaque page_token with the same filters and release. A null next_page_token ends traversal. Cache-Control: public, max-age=60, must-revalidate. ### Parameters #### measure_id query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | #### indicator_id query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | #### geography_type query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | #### page_size query, optional. Items per page; defaults to 100, configured maximum at most 500. | Constraint | Value | | --- | --- | | Schema | `integer \| null` | | Default | `100` | | Minimum | `1` | | Maximum | `500` | Example: ```json 100 ``` #### page_token query, optional. Opaque next_page_token; retain query filters and release. | Constraint | Value | | --- | --- | | Schema | `string \| null` | ### Responses #### 200 Successful current-release resource. - Media type: `application/json` - Response schema: `CollectionEnvelope_Measure_` #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/measures", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/measures", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/measures", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/measures", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/measures", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/measures", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Geographies (https://onehealthatlas.org/docs/api-reference/geographies) > Typed geography identity; delivery is not yet available. Generated from the public OpenAPI contract. Typed geography identity; delivery is not yet available. ## Get geography identity (delivery pending) [#geography_v1_geographies__geography_type___geography_id__get] `GET /v1/geographies/{geography_type}/{geography_id}` Delivery pending at the last production check, 18 October 2026. Production API, 18 October 2026. This is not a live health indicator. Operation ID: `geography_v1_geographies__geography_type___geography_id__get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/geographies/geography_v1_geographies__geography_type___geography_id__get). ## Check canonical county geography publication availability [#canonicalGeographyAvailability] `GET /v1/geographies/{geography_type}/{geography_id}/availability` Operation ID: `canonicalGeographyAvailability` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/geographies/canonicalGeographyAvailability). # Check canonical county geography publication availability (https://onehealthatlas.org/docs/api-reference/geographies/canonicalGeographyAvailability) > Additive county-only operation. Confirms membership and release from the governed county directory before returning UNAVAILABLE/CANONICAL_GEOGRAPHY_UNPUBLISHED with null data. The canonical resource is identity metadata, not a polygon. No geometry is returned or inferred. State availability is unsupported (400). Malformed county IDs return 400; confirmed absent identities return 404. Unavailable, empty, duplicate or inconsistent directory authority remains 503. The directory uses the existing bounded snapshot cache, checked against a fresh current-release lookup; a mismatch remains 503. Responses use Cache-Control: no-store. The existing canonical resource route and county/map routes are unchanged. ## GET /v1/geographies/{geography_type}/{geography_id}/availability Operation ID: `canonicalGeographyAvailability`. Check canonical county geography publication availability Additive county-only operation. Confirms membership and release from the governed county directory before returning UNAVAILABLE/CANONICAL_GEOGRAPHY_UNPUBLISHED with null data. The canonical resource is identity metadata, not a polygon. No geometry is returned or inferred. State availability is unsupported (400). Malformed county IDs return 400; confirmed absent identities return 404. Unavailable, empty, duplicate or inconsistent directory authority remains 503. The directory uses the existing bounded snapshot cache, checked against a fresh current-release lookup; a mismatch remains 503. Responses use Cache-Control: no-store. The existing canonical resource route and county/map routes are unchanged. ### Parameters #### geography_type path, required. | Constraint | Value | | --- | --- | | Schema | `GeographyType` | #### geography_id path, required. | Constraint | Value | | --- | --- | | Schema | `string` | ### Responses #### 200 Confirmed current county identity; canonical publication is pending. - Media type: `application/json` - Response schema: `CanonicalGeographyAvailability` ##### Confirmed county identity; canonical geography publication pending ```json { "availability": "UNAVAILABLE", "reason": "CANONICAL_GEOGRAPHY_UNPUBLISHED", "data": null, "release_id": "example-release", "limitations": [ "Illustrative checked county directory; no geometry is delivered." ] } ``` #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}/availability", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}/availability", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}/availability", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}/availability", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}/availability", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}/availability", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Get geography identity (delivery pending) (https://onehealthatlas.org/docs/api-reference/geographies/geography_v1_geographies__geography_type___geography_id__get) > Validated county/state FIPS identity; currently returns 503 CANONICAL_DATA_UNAVAILABLE. No geometry is returned. Delivery pending at the last production check, 18 October 2026. Production API, 18 October 2026. This is not a live health indicator. ## GET /v1/geographies/{geography_type}/{geography_id} Operation ID: `geography_v1_geographies__geography_type___geography_id__get`. Get geography identity (delivery pending) Validated county/state FIPS identity; currently returns 503 CANONICAL_DATA_UNAVAILABLE. No geometry is returned. ### Parameters #### geography_type path, required. | Constraint | Value | | --- | --- | | Schema | `GeographyType` | #### geography_id path, required. | Constraint | Value | | --- | --- | | Schema | `string` | ### Responses #### 200 Successful current-release resource. - Media type: `application/json` - Response schema: `ResourceEnvelope_Geography_` #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/geographies/{geography_type}/{geography_id}", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Canonical data delivery is not yet available. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Canonical data delivery is not yet available.", "instance": "/v1/geographies/{geography_type}/{geography_id}", "request_id": "example-request-id", "code": "CANONICAL_DATA_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Observations (https://onehealthatlas.org/docs/api-reference/observations) > Bounded county observations with explicit value states. Generated from the public OpenAPI contract. Bounded county observations with explicit value states. ## Query county observations [#observations_v1_observations_get] `GET /v1/observations` Operation ID: `observations_v1_observations_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/observations/observations_v1_observations_get). # Query county observations (https://onehealthatlas.org/docs/api-reference/observations/observations_v1_observations_get) > Current published county observations only. Ordered by measure ID, county FIPS, period start, and observation ID. Opaque page tokens bind to filters and release. Annual surveillance uses 2023. Separately enabled, reviewed January 2025 environmental measures use labeled daily periods, carry environmental_context coverage, and have no supported strata. Environmental context is descriptive weather, with no causal, disease-risk or ML claim. Surveillance context is optional and requires an admitted Data delivery; normalized_state preserves Data semantics and the publisher value remains value. Separately enabled CDC status uses start_date=end_date=2025-12-31 and CUMULATIVE grain; scapularis_status and burgdorferi_status require exact Data record admission. Annual year and other date ranges return 400 UNSUPPORTED_FILTER before data access. Missing context does not establish absence or temporal comparability. County SVI/population/insurance context requires vintage_year=2022 and retains ACS 2018-2022 periods. RUCC requires vintage_year=2023 and returns categorical codes/labels with null period dates. These measures reject annual/day filters; absent rows are unavailable evidence, never zero. A measure and bounded county/time selection are required; no user sorting or aggregation. After successful release/measure/query reads, an initially empty non-CDC selection returns 200 with meta.availability=UNAVAILABLE and reason=NO_PUBLISHED_RESULTS. This does not establish source coverage or biological absence. Exhausted continuation pages remain AVAILABLE. CDC admission and operational errors remain non-2xx. Known unavailable collections use Cache-Control: no-store. ## GET /v1/observations Operation ID: `observations_v1_observations_get`. Query county observations Current published county observations only. Ordered by measure ID, county FIPS, period start, and observation ID. Opaque page tokens bind to filters and release. Annual surveillance uses 2023. Separately enabled, reviewed January 2025 environmental measures use labeled daily periods, carry environmental_context coverage, and have no supported strata. Environmental context is descriptive weather, with no causal, disease-risk or ML claim. Surveillance context is optional and requires an admitted Data delivery; normalized_state preserves Data semantics and the publisher value remains value. Separately enabled CDC status uses start_date=end_date=2025-12-31 and CUMULATIVE grain; scapularis_status and burgdorferi_status require exact Data record admission. Annual year and other date ranges return 400 UNSUPPORTED_FILTER before data access. Missing context does not establish absence or temporal comparability. County SVI/population/insurance context requires vintage_year=2022 and retains ACS 2018-2022 periods. RUCC requires vintage_year=2023 and returns categorical codes/labels with null period dates. These measures reject annual/day filters; absent rows are unavailable evidence, never zero. A measure and bounded county/time selection are required; no user sorting or aggregation. After successful release/measure/query reads, an initially empty non-CDC selection returns 200 with meta.availability=UNAVAILABLE and reason=NO_PUBLISHED_RESULTS. This does not establish source coverage or biological absence. Exhausted continuation pages remain AVAILABLE. CDC admission and operational errors remain non-2xx. Known unavailable collections use Cache-Control: no-store. ### Parameters #### measure_id query, required. Exact discovery measure ID. | Constraint | Value | | --- | --- | | Schema | `string` | | Minimum length | `1` | Example: ```json "case_count_floor_2023" ``` #### geography_type query, required. | Constraint | Value | | --- | --- | | Schema | `GeographyType` | #### geography_id query, required. Repeat for 1-500 county FIPS strings; preserve leading zeros. | Constraint | Value | | --- | --- | | Schema | `array of string` | | Minimum items | `1` | | Maximum items | `500` | Example: ```json [ "08001" ] ``` #### vintage_year query, optional. Required for county context: 2022 for SVI/ACS, 2023 for RUCC. Excludes year/date filters. | Constraint | Value | | --- | --- | | Schema | `integer \| null` | | Minimum | `1900` | | Maximum | `2100` | #### year query, optional. Annual year or complete date range, not both. CDC cumulative status rejects year; use start_date=end_date=2025-12-31. | Constraint | Value | | --- | --- | | Schema | `integer \| null` | | Minimum | `1900` | | Maximum | `2100` | Example: ```json 2023 ``` #### start_date query, optional. Inclusive period start; requires end_date and excludes year. | Constraint | Value | | --- | --- | | Schema | `string \| null` | | Format | `date` | Example: ```json "2023-01-01" ``` #### end_date query, optional. Inclusive period end; requires start_date and excludes year. | Constraint | Value | | --- | --- | | Schema | `string \| null` | | Format | `date` | Example: ```json "2023-12-31" ``` #### stratification query, optional. Current release has no strata; unsupported selections fail explicitly. | Constraint | Value | | --- | --- | | Schema | `array of string` | #### page_size query, optional. Items per page; defaults to 100, configured maximum at most 500. | Constraint | Value | | --- | --- | | Schema | `integer \| null` | | Default | `100` | | Minimum | `1` | | Maximum | `500` | Example: ```json 100 ``` #### page_token query, optional. Opaque next_page_token; retain query filters and release. | Constraint | Value | | --- | --- | | Schema | `string \| null` | ### Responses #### 200 Bounded current-release observations. - Media type: `application/json` - Response schema: `CollectionEnvelope_CountyContextObservation_ | CollectionEnvelope_Observation_` ##### Empty continuation page; not an unavailable selection ```json { "data": [], "meta": { "next_page_token": null, "response_at": "2026-01-01T00:00:00Z", "availability": "AVAILABLE", "release_id": "example-release", "limitations": [] }, "links": { "self": null } } ``` ##### Synthetic available published observation example ```json { "data": [ { "observation_id": "example-observation", "measure_id": "case_count_floor_2023", "geography": { "geography_type": "county", "geography_id": "08001" }, "period_start": "2023-01-01", "period_end": "2023-12-31", "temporal_grain": "year", "value": 12, "value_state": "OBSERVED", "unit": "cases", "denominator": null, "source_id": "human", "methodology_id": null, "methodology_version": "example-transform-v1", "semantic_version": "example-semantic-v1", "release_id": "example-release", "provenance_ref": "example-observation", "limitations": [ "Synthetic documentation example; no measured value is asserted." ], "evidence": { "resource_type": "observation", "resource_id": "example-observation" } } ], "meta": { "next_page_token": null, "response_at": "2026-01-01T00:00:00Z", "availability": "AVAILABLE", "release_id": "example-release", "limitations": [] }, "links": { "self": null } } ``` ##### Successful initial query with no published results; not negative evidence ```json { "data": [], "meta": { "next_page_token": null, "response_at": "2026-01-01T00:00:00Z", "availability": "UNAVAILABLE", "reason": "NO_PUBLISHED_RESULTS", "release_id": "example-release", "limitations": [ "No published observations match this selection in the checked release. This does not establish biological absence, source coverage, or geography membership." ] }, "links": { "self": null } } ``` ##### Synthetic missing-value example; not a published county result ```json { "data": [ { "observation_id": "example-observation", "measure_id": "case_count_floor_2023", "geography": { "geography_type": "county", "geography_id": "08001" }, "period_start": "2023-01-01", "period_end": "2023-12-31", "temporal_grain": "year", "value": null, "value_state": "MISSING", "unit": "cases", "denominator": null, "source_id": "human", "methodology_id": null, "methodology_version": "example-transform-v1", "semantic_version": "example-semantic-v1", "release_id": "example-release", "provenance_ref": "example-observation", "limitations": [ "Synthetic documentation example; no measured value is asserted." ], "evidence": { "resource_type": "observation", "resource_id": "example-observation" } } ], "meta": { "next_page_token": null, "response_at": "2026-01-01T00:00:00Z" }, "links": { "self": null } } ``` #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/observations", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/observations", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/observations", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/observations", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/observations", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/observations", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Provenance (https://onehealthatlas.org/docs/api-reference/provenance) > Governed source and methodology identities and versions. Generated from the public OpenAPI contract. Governed source and methodology identities and versions. ## Get a methodology [#methodology_v1_methodologies__methodology_id__get] `GET /v1/methodologies/{methodology_id}` Operation ID: `methodology_v1_methodologies__methodology_id__get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/provenance/methodology_v1_methodologies__methodology_id__get). ## Discover sources [#sources_v1_sources_get] `GET /v1/sources` Operation ID: `sources_v1_sources_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/provenance/sources_v1_sources_get). ## Get a source [#source_v1_sources__source_id__get] `GET /v1/sources/{source_id}` Operation ID: `source_v1_sources__source_id__get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/provenance/source_v1_sources__source_id__get). # Get a methodology (https://onehealthatlas.org/docs/api-reference/provenance/methodology_v1_methodologies__methodology_id__get) > Resolve the exact governed public resource ID in the current release. Unknown IDs return 404 RESOURCE_NOT_FOUND. Preserve versions and limitations; null metadata is not inferred. Cache-Control: public, max-age=60, must-revalidate; ETag with matching If-None-Match returns an empty 304. ## GET /v1/methodologies/{methodology_id} Operation ID: `methodology_v1_methodologies__methodology_id__get`. Get a methodology Resolve the exact governed public resource ID in the current release. Unknown IDs return 404 RESOURCE_NOT_FOUND. Preserve versions and limitations; null metadata is not inferred. Cache-Control: public, max-age=60, must-revalidate; ETag with matching If-None-Match returns an empty 304. ### Parameters #### methodology_id path, required. | Constraint | Value | | --- | --- | | Schema | `string` | ### Responses #### 200 Successful current-release resource. - Media type: `application/json` - Response schema: `ResourceEnvelope_Methodology_` #### 304 Not modified. ETag matches If-None-Match; empty response body. #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/methodologies/{methodology_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/methodologies/{methodology_id}", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/methodologies/{methodology_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/methodologies/{methodology_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/methodologies/{methodology_id}", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/methodologies/{methodology_id}", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Get a source (https://onehealthatlas.org/docs/api-reference/provenance/source_v1_sources__source_id__get) > Resolve the exact governed public resource ID in the current release. Unknown IDs return 404 RESOURCE_NOT_FOUND. Preserve versions and limitations; null metadata is not inferred. Cache-Control: public, max-age=60, must-revalidate; ETag with matching If-None-Match returns an empty 304. ## GET /v1/sources/{source_id} Operation ID: `source_v1_sources__source_id__get`. Get a source Resolve the exact governed public resource ID in the current release. Unknown IDs return 404 RESOURCE_NOT_FOUND. Preserve versions and limitations; null metadata is not inferred. Cache-Control: public, max-age=60, must-revalidate; ETag with matching If-None-Match returns an empty 304. ### Parameters #### source_id path, required. | Constraint | Value | | --- | --- | | Schema | `string` | ### Responses #### 200 Successful current-release resource. - Media type: `application/json` - Response schema: `ResourceEnvelope_Source_` #### 304 Not modified. ETag matches If-None-Match; empty response body. #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/sources/{source_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/sources/{source_id}", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/sources/{source_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/sources/{source_id}", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/sources/{source_id}", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/sources/{source_id}", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Discover sources (https://onehealthatlas.org/docs/api-reference/provenance/sources_v1_sources_get) > Current-release discovery with optional documented filters. page_size defaults to 100 (maximum 500); reuse opaque page_token with the same filters and release. A null next_page_token ends traversal. Cache-Control: public, max-age=60, must-revalidate. ## GET /v1/sources Operation ID: `sources_v1_sources_get`. Discover sources Current-release discovery with optional documented filters. page_size defaults to 100 (maximum 500); reuse opaque page_token with the same filters and release. A null next_page_token ends traversal. Cache-Control: public, max-age=60, must-revalidate. ### Parameters #### page_size query, optional. Items per page; defaults to 100, configured maximum at most 500. | Constraint | Value | | --- | --- | | Schema | `integer \| null` | | Default | `100` | | Minimum | `1` | | Maximum | `500` | Example: ```json 100 ``` #### page_token query, optional. Opaque next_page_token; retain query filters and release. | Constraint | Value | | --- | --- | | Schema | `string \| null` | ### Responses #### 200 Successful current-release resource. - Media type: `application/json` - Response schema: `CollectionEnvelope_Source_` #### 400 INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-400", "title": "Request failed", "status": 400, "detail": "INVALID_REQUEST, UNSUPPORTED_FILTER, UNSUPPORTED_STRATIFICATION, or QUERY_TOO_BROAD; application/problem+json", "instance": "/v1/sources", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 404 RESOURCE_NOT_FOUND; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "RESOURCE_NOT_FOUND; application/problem+json", "instance": "/v1/sources", "request_id": "example-request-id", "code": "RESOURCE_NOT_FOUND" } ``` #### 413 GET request body rejected; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "GET request body rejected; application/problem+json", "instance": "/v1/sources", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 414 Query string too long; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-414", "title": "Request failed", "status": 414, "detail": "Query string too long; application/problem+json", "instance": "/v1/sources", "request_id": "example-request-id", "code": "INVALID_REQUEST" } ``` #### 429 Rate limited; Retry-After; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limited; Retry-After; application/problem+json", "instance": "/v1/sources", "request_id": "example-request-id", "code": "RATE_LIMITED" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Service unavailable; application/problem+json - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Service unavailable; application/problem+json", "instance": "/v1/sources", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Schemas (https://onehealthatlas.org/docs/api-reference/schemas) > Component schema names and descriptions from the pinned public Atlas OpenAPI contract. These component schema descriptions are indexed from the public OpenAPI contract. Operation pages render the schema with the native OpenAPI reference. ## ProblemDetails [#schema-problemdetails] RFC 9457 error. Stable codes are included when the response contract defines one. * `type` * `title` * `status` * `detail` * `instance` * `request_id` * `code` * `errors` ## AtlasMetadata [#schema-atlasmetadata] * `release_id` * `schema_version` * `generated_at` * `loaded_at` * `scope` * `bundle_sha256` * `score_defaults` * `methodology_version` * `limitations` * `sources` * `states` ## SourceMetadata [#schema-sourcemetadata] * `key` * `label` * `vintage` * `url` * `note` ## ScoreCollection [#schema-scorecollection] * `release_id` * `methodology_version` * `settings` * `counties` ## CountyScoreSummary [#schema-countyscoresummary] * `fips` * `county` * `state` * `state_name` * `in_contiguous_tick_scope` * `human_status` * `tick_status` * `burgdorferi_status` * `evidence_completeness` * `score` * `priority` * `color` ## Score [#schema-score] * `score` * `human_weakness` * `ecological` * `community` * `tick_signal` * `pathogen_signal` * `svi_signal` * `access_signal` * `rural_signal` ## CountyDetail [#schema-countydetail] * `fips` * `county` * `state` * `state_name` * `in_contiguous_tick_scope` * `human_status` * `tick_status` * `burgdorferi_status` * `evidence_completeness` * `score` * `priority` * `color` * `population` * `case_count_floor_2023` * `incidence_floor_2023` * `state_unallocated_records_2023` * `scapularis_status` * `pacificus_status` * `svi_percentile` * `uninsured_percentile` * `uninsured_percent` * `rucc_2023` * `release` ## Tier1CountyPriority [#schema-tier1countypriority] Model-assisted surveillance review priority; never disease or clinical risk. Five-digit county FIPS for this persisted result. HIGH, MEDIUM, or LOW model-assisted surveillance review priority under the named tier policy; not disease risk. Null for NOT\_ESTIMABLE. Within-batch relative position among scored counties for this model and inference batch (0-100). Not a probability or comparable across batches, model versions, populations, or tier policies without a separate validation. Null for NOT\_ESTIMABLE. Model-native anomaly score; not a probability, incidence estimate, or clinical/disease risk. Its scale is model-specific and is not comparable across versions without validation. Null for NOT\_ESTIMABLE. Input-data sufficiency state, not calibrated model confidence. NOT\_ESTIMABLE is an abstention with null tier, percentile, and score; SUFFICIENT and INSUFFICIENT both require tier, percentile, and score. Version of the model that generated this result. Governed source release for this batch. ML source commit for reproducibility. Inference batch identity defining the percentile comparison population. Version of the policy assigning review tiers from scored results. UTC batch generation time, not the request time or source observation date. * `county_fips` * `priority_tier` * `priority_percentile` * `raw_model_score` * `evidence_sufficiency` * `model_version` * `release_id` * `source_commit` * `prediction_batch_version` * `tier_policy_version` * `generated_at_utc` * `reasons` * `limitation_ref` ## PriorityReason [#schema-priorityreason] * `code` * `text` ## Tier1CountyPriorityAvailability [#schema-tier1countypriorityavailability] Availability lookup that separates confirmed absence from request failure. Whether a persisted Tier 1 result exists for this supported current geography. Current governed geography release used to validate the requested FIPS. Stable reason when no persisted result is published; null when data is available. The exact persisted Tier 1 result, or null when none is published. * `availability` * `geography_release_id` * `reason` * `data` ## GeographyType [#schema-geographytype] This schema does not declare a description. ## ResourceEnvelope\_Geography\_ [#schema-resourceenvelope-geography] * `data` ## Geography [#schema-geography] County/state identity metadata; geometry is a separate display resource. * `geography` * `label` * `parent` ## GeographyIdentity [#schema-geographyidentity] Stable FIPS join identity, independent of display or analysis polygons. FIPS string with leading zeros: five digits for counties, two for states. * `geography_type` * `geography_id` ## CanonicalGeographyAvailability [#schema-canonicalgeographyavailability] No canonical geography resource or geometry is fabricated. Governed county directory release used to confirm identity. Publication and representation boundaries, not scientific absence. * `availability` * `reason` * `data` * `release_id` * `limitations` ## CollectionEnvelope\_Indicator\_ [#schema-collectionenvelope-indicator] * `data` * `meta` * `links` ## Indicator [#schema-indicator] Governed semantic contract version, separate from HTTP V1 and application version. Governed current-release relationship version. Governed interpretation limitations; preserve alongside values and versions. * `indicator_id` * `label` * `definition` * `measure_ids` * `semantic_version` * `release_version` * `domain` * `category` * `limitations` * `standards_mappings` ## StandardsMapping [#schema-standardsmapping] * `standard` * `version` * `target` * `relationship` * `mapping_reference` ## CollectionMeta [#schema-collectionmeta] Opaque query/release-bound continuation. Null means exhaustion; tokens may expire on restart. UTC response construction time; not source freshness or observation time. Observation selection availability, not biological presence. Omitted on other collections. An exhausted continuation remains AVAILABLE. No published rows after a successful initial non-CDC query; otherwise omitted. Current governed release actually read for this query. Selection availability caveats; observations only. * `next_page_token` * `response_at` * `availability` * `reason` * `release_id` * `limitations` ## CollectionLinks [#schema-collectionlinks] * `self` ## ResourceEnvelope\_Indicator\_ [#schema-resourceenvelope-indicator] * `data` ## CollectionEnvelope\_Measure\_ [#schema-collectionenvelope-measure] * `data` * `meta` * `links` ## Measure [#schema-measure] Governed semantic contract version, separate from HTTP V1 and application version. Governed current-release relationship version. Governed denominator; null means it is not supplied and must not be inferred. Exact governed methodology resource ID; null when not governed. Governed interpretation limitations; preserve alongside values and versions. * `measure_id` * `indicator_id` * `label` * `definition` * `semantic_version` * `release_version` * `measure_type` * `unit` * `denominator` * `geography_types` * `temporal_grains` * `geography_semantics` * `temporal_semantics` * `allowed_value_states` * `allowed_strata` * `missingness_semantics` * `methodology_id` * `methodology` * `source_ids` * `limitations` * `standards_mappings` ## ValueState [#schema-valuestate] Public V1 states, including the governed county status added by API #54. ## ResourceEnvelope\_Measure\_ [#schema-resourceenvelope-measure] * `data` ## ResourceEnvelope\_Methodology\_ [#schema-resourceenvelope-methodology] * `data` ## Methodology [#schema-methodology] Exact governed methodology resource ID; null when not governed. Governed interpretation limitations; preserve alongside values and versions. Governed semantic contract version, separate from HTTP V1 and application version. Governed current-release relationship version. * `methodology_id` * `measure_id` * `version` * `description` * `limitations` * `semantic_version` * `release_version` ## CollectionEnvelope\_CountyContextObservation\_ [#schema-collectionenvelope-countycontextobservation] * `data` * `meta` * `links` ## CountyContextObservation [#schema-countycontextobservation] Reviewed consumer-safe metadata revision; not private lineage. Stable observation identity and compact provenance reference. Integer population/category or exact nonzero decimal text; ZERO is integer 0. OBSERVED is nonzero; ZERO is numeric zero; MISSING/SUPPRESSED/UNAVAILABLE require null; NO\_COUNTY\_LINKED\_RECORD retains the literal no\_county\_linked\_record; NO\_RECORDS retains CDC's No records. Neither establishes biological absence. Governed denominator; null means it is not supplied and must not be inferred. Public source resource key; distinct from lineage\_source\_id and dataset\_id. Exact governed methodology resource ID; null when not governed. Transformation version, distinct from methodology resource version. Governed semantic contract version, separate from HTTP V1 and application version. Governed release identity for reproducibility. Structured observation provenance identity; not a literature citation. Publisher timestamp when governed; null is not inferred freshness. Atlas acquisition time when governed; distinct from source publication and processing. Atlas processing time when governed; distinct from response time. Governed interpretation limitations; preserve alongside values and versions. Present only for reviewed environmental context. DECIMAL quantities may use exact numeric strings; native DOUBLE remains a JSON number. Only supplied through an admitted Data release/bundle and supported slice. Omitted or null carries no evidence-state, comparability or lag claim. Comparison is case-definition scope only; alignment is descriptive, not causal. ACS reference-period start; null for RUCC vintage. ACS reference-period end; null for RUCC vintage. * `metadata_revision_id` * `observation_id` * `measure_id` * `geography` * `temporal_grain` * `value` * `value_state` * `unit` * `denominator` * `strata` * `source_id` * `lineage_source_id` * `dataset_id` * `methodology_id` * `methodology` * `release_methodology_version` * `methodology_version` * `semantic_version` * `release_id` * `provenance_ref` * `source_label` * `source_vintage` * `source_url` * `source_published_at` * `atlas_acquired_at` * `atlas_processed_at` * `limitations` * `evidence` * `environmental_context` * `surveillance_context` * `period_start` * `period_end` * `county_context` ## EvidenceReference [#schema-evidencereference] Public source resource key; distinct from lineage\_source\_id and dataset\_id. Structured observation provenance identity; not a literature citation. Governed semantic contract version, separate from HTTP V1 and application version. Transformation version, distinct from methodology resource version. Governed release identity for reproducibility. * `resource_type` * `resource_id` * `source_id` * `provenance_ref` * `semantic_version` * `methodology_version` * `release_id` * `uri` ## EnvironmentalContext [#schema-environmentalcontext] Coverage independent of value state; numeric strings preserve exact DECIMAL. Publisher labeled 24-hour period, not a midnight calendar day. Monthly source-supported/legal county area; separate from daily completeness. Daily valid/source-supported area; completeness threshold 0.95. Upstream modification metadata; never original publication or first availability. Analysis geometry identity only; no polygons. * `coverage_status` * `source_time_present` * `day_convention` * `expected_area_m2` * `intersected_area_m2` * `source_supported_area_m2` * `valid_area_m2` * `source_coverage_fraction` * `valid_fraction_of_supported_area` * `upstream_date_modified` * `weight_version` * `geometry_version` * `metadata_revision_id` ## SurveillanceContext [#schema-surveillancecontext] * `evidence` * `methodology_comparison` * `temporal_alignment` ## SurveillanceEvidenceContext [#schema-surveillanceevidencecontext] Data-projector evidence, never an API classification. Data-owned county evidence state, projected without classification. Null means the older companion did not supply normalization; unknown supports no biological absence conclusion. Original publisher value remains Observation.value. * `contract_version` * `normalized_state` * `state` * `reason_codes` * `evidence_tier` * `observation_key` * `revision_id` * `value_state` * `source_rule_id` * `limitations` * `evidence_revision_id` ## MethodologyComparisonContext [#schema-methodologycomparisoncontext] Public ID of the comparison's left input. * `contract_version` * `comparison_state` * `reason_codes` * `methodology_era_ids` * `jurisdiction_class` * `references` * `limitations` * `left_observation_id` ## TemporalAlignmentContext [#schema-temporalalignmentcontext] * `contract_version` * `method_id` * `method_version` * `source_id` * `measure_id` * `aggregation_rule` * `coverage_denominator` * `decision_cutoff` * `disposition` * `reason_codes` * `limitations` * `observation_window` * `target_window` * `lag` * `coverage` * `reference_period` ## TemporalWindowContext [#schema-temporalwindowcontext] * `start` * `end_exclusive` * `calendar` * `timezone` ## TemporalLagContext [#schema-temporallagcontext] * `kind` * `anchor` * `offset_days` * `window_days` * `season_id` ## TemporalCoverageContext [#schema-temporalcoveragecontext] * `expected` * `observed` * `unit` * `partial_allowed` ## TemporalReferencePeriodContext [#schema-temporalreferenceperiodcontext] * `id` * `start` * `end_exclusive` * `source_vintage` ## CountyContext [#schema-countycontext] Source product/classification vintage, not an annual date. Authoritative category label; null for quantities. * `contract_version` * `vintage_year` * `source_field` * `value_type` * `category_label` * `definition` * `allowed_value_states` * `metadata_methodology_version` ## CollectionEnvelope\_Observation\_ [#schema-collectionenvelope-observation] * `data` * `meta` * `links` ## Observation [#schema-observation] Reviewed consumer-safe metadata revision; not private lineage. Stable observation identity and compact provenance reference. Read with value\_state and unit; null never means zero. OBSERVED is nonzero; ZERO is numeric zero; MISSING/SUPPRESSED/UNAVAILABLE require null; NO\_COUNTY\_LINKED\_RECORD retains the literal no\_county\_linked\_record; NO\_RECORDS retains CDC's No records. Neither establishes biological absence. Governed denominator; null means it is not supplied and must not be inferred. Public source resource key; distinct from lineage\_source\_id and dataset\_id. Exact governed methodology resource ID; null when not governed. Transformation version, distinct from methodology resource version. Governed semantic contract version, separate from HTTP V1 and application version. Governed release identity for reproducibility. Structured observation provenance identity; not a literature citation. Publisher timestamp when governed; null is not inferred freshness. Atlas acquisition time when governed; distinct from source publication and processing. Atlas processing time when governed; distinct from response time. Governed interpretation limitations; preserve alongside values and versions. Present only for reviewed environmental context. DECIMAL quantities may use exact numeric strings; native DOUBLE remains a JSON number. Only supplied through an admitted Data release/bundle and supported slice. Omitted or null carries no evidence-state, comparability or lag claim. Comparison is case-definition scope only; alignment is descriptive, not causal. Inclusive start of the governed observation period. Inclusive end of the governed observation period. * `metadata_revision_id` * `observation_id` * `measure_id` * `geography` * `temporal_grain` * `value` * `value_state` * `unit` * `denominator` * `strata` * `source_id` * `lineage_source_id` * `dataset_id` * `methodology_id` * `methodology` * `release_methodology_version` * `methodology_version` * `semantic_version` * `release_id` * `provenance_ref` * `source_label` * `source_vintage` * `source_url` * `source_published_at` * `atlas_acquired_at` * `atlas_processed_at` * `limitations` * `evidence` * `environmental_context` * `surveillance_context` * `period_start` * `period_end` ## CollectionEnvelope\_Source\_ [#schema-collectionenvelope-source] * `data` * `meta` * `links` ## Source [#schema-source] Public source resource key; distinct from lineage\_source\_id and dataset\_id. Governed semantic contract version, separate from HTTP V1 and application version. Governed current-release relationship version. Atlas acquisition time when governed; distinct from source publication and processing. Governed publisher update time; null when unavailable. Governed source retrieval time; null when unavailable. Governed interpretation limitations; preserve alongside values and versions. * `source_id` * `label` * `publisher` * `lineage_source_id` * `dataset_id` * `semantic_version` * `release_version` * `source_url` * `source_vintage` * `source_version` * `published_at` * `atlas_acquired_at` * `upstream_updated_at` * `source_retrieved_at` * `limitations` ## ResourceEnvelope\_Source\_ [#schema-resourceenvelope-source] * `data` ## StateReview [#schema-statereview] * `requested_state` * `methodology_id` * `methodology_version` * `configuration_sha256` * `data_release_version` * `evaluated_at` * `requested_observation_context` * `effective_observation_context` * `result_state` * `review_candidates` * `data_gaps` * `coverage` * `limitations` ## Candidate [#schema-candidate] * `county_fips` * `county_name` * `county_url` * `reason_codes` * `reason_text` * `evidence_families` * `evidence_references` * `completeness` * `limitations` * `freshness_comparability` * `suggested_next_check` ## PublicReviewEvidenceReference [#schema-publicreviewevidencereference] * `family` * `source_product` * `source_version` * `public_record_ref` * `county_fips` * `release_id` * `source_as_of` * `retrieved_at` * `target` * `status` * `limitations` ## DataGap [#schema-datagap] * `county_fips` * `code` * `detail` ## ReviewCoverage [#schema-reviewcoverage] * `assessed_counties` * `eligible_counties` * `abstained_counties` * `evaluated_counties` * `rule_coverage` # States (https://onehealthatlas.org/docs/api-reference/states) > Existing state PDF reports. Generated from the public OpenAPI contract. Existing state PDF reports. ## Download a state report [#state_report_pdf_v1_states__state__report_pdf_get] `GET /v1/states/{state}/report.pdf` Operation ID: `state_report_pdf_v1_states__state__report_pdf_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/states/state_report_pdf_v1_states__state__report_pdf_get). ## Review a state's county evidence [#state_review_v1_states__state__review_get] `GET /v1/states/{state}/review` Operation ID: `state_review_v1_states__state__review_get` [Parameters, responses, and schema](https://onehealthatlas.org/docs/api-reference/states/state_review_v1_states__state__review_get). # Download a state report (https://onehealthatlas.org/docs/api-reference/states/state_report_pdf_v1_states__state__report_pdf_get) > PDF attachment using the immutable state-v1 registered template by default. State is a two-letter code. Optional dataset_version and score settings bind report inputs. ETag/If-None-Match supports 304; public cache TTL 300 seconds with revalidation. Unknown templates return 422; resource limits 413; renderer failure/timeout 503. ## GET /v1/states/{state}/report.pdf Operation ID: `state_report_pdf_v1_states__state__report_pdf_get`. Download a state report PDF attachment using the immutable state-v1 registered template by default. State is a two-letter code. Optional dataset_version and score settings bind report inputs. ETag/If-None-Match supports 304; public cache TTL 300 seconds with revalidation. Unknown templates return 422; resource limits 413; renderer failure/timeout 503. ### Parameters #### state path, required. | Constraint | Value | | --- | --- | | Schema | `string` | | Pattern | `^[A-Z]{2}$` | #### dataset_version query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | #### template query, optional. | Constraint | Value | | --- | --- | | Schema | `string` | | Default | `state-v1` | | Pattern | `^[a-z]+-v\d+$` | #### ecological_share query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `65` | | Minimum | `40` | | Maximum | `85` | | Multiple of | `5` | #### low_incidence_breakpoint query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `10` | | Minimum | `5` | | Maximum | `25` | #### missing_human_weakness query, optional. | Constraint | Value | | --- | --- | | Schema | `integer` | | Default | `75` | | Minimum | `40` | | Maximum | `90` | | Multiple of | `5` | ### Responses #### 200 PDF attachment. - Media type: `application/pdf` - Response schema: `string` #### 304 Matching If-None-Match; empty body. #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/states/{state}/report.pdf", "request_id": "example-request-id" } ``` #### 413 The report exceeds configured resource limits. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-413", "title": "Request failed", "status": 413, "detail": "The report exceeds configured resource limits.", "instance": "/v1/states/{state}/report.pdf", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/states/{state}/report.pdf", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/states/{state}/report.pdf", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/states/{state}/report.pdf", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # Review a state's county evidence (https://onehealthatlas.org/docs/api-reference/states/state_review_v1_states__state__review_get) > Versioned county Review result. Current rules are disabled. Lineage gaps are separate. Public cache TTL is 60 seconds. ## GET /v1/states/{state}/review Operation ID: `state_review_v1_states__state__review_get`. Review a state's county evidence Versioned county Review result. Current rules are disabled. Lineage gaps are separate. Public cache TTL is 60 seconds. ### Parameters #### state path, required. | Constraint | Value | | --- | --- | | Schema | `string` | | Pattern | `^[A-Z]{2}$` | #### observation_context query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | | Maximum length | `80` | #### dataset_version query, optional. | Constraint | Value | | --- | --- | | Schema | `string \| null` | ### Responses #### 200 Successful Response - Media type: `application/json` - Response schema: `StateReview` #### 404 County or dataset release not found. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Request failed", "status": 404, "detail": "County or dataset release not found.", "instance": "/v1/states/{state}/review", "request_id": "example-request-id" } ``` #### 422 One or more request values are invalid. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "One or more request values are invalid.", "instance": "/v1/states/{state}/review", "request_id": "example-request-id" } ``` #### 429 Rate limit exceeded. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-429", "title": "Request failed", "status": 429, "detail": "Rate limit exceeded.", "instance": "/v1/states/{state}/review", "request_id": "example-request-id" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. #### 503 Atlas data service is unavailable. - Media type: `application/problem+json` - Response schema: `ProblemDetails` ##### Synthetic error example ```json { "type": "https://onehealthatlas.org/problems/http-503", "title": "Request failed", "status": 503, "detail": "Atlas data service is unavailable.", "instance": "/v1/states/{state}/review", "request_id": "example-request-id", "code": "SERVICE_UNAVAILABLE" } ``` - Header `Retry-After`: Seconds before retry when supplied by the service. # The Atlas decision-support workflow (https://onehealthatlas.org/docs/atlas-workflow) > Follow Atlas Lyme from fragmented One Health evidence to a focused epidemiological investigation question. Atlas is organized around a decision-support path: `DATA → SIGNALS → CONTEXT → INTERPRETATION → INVESTIGATION → PUBLIC-HEALTH ACTION` Each step answers a different question. Moving through the steps helps prevent a visually prominent value from being mistaken for a complete conclusion. ## 1. Data — what is available? [#1-data--what-is-available] Atlas brings together public evidence that may include human disease, ticks and vectors, pathogens, climate, habitat, population, and scientific literature. Start by checking what the current release actually contains: source, geography, time period, update context, and limitations. A later governed source is intended to enter through a source-specific adapter and still be read as canonical Atlas evidence, with that source's provenance attached. See [sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence). Data availability is not the same thing as disease absence. A missing, suppressed, stale, or incomparable value must remain visibly different from a measured zero. ## 2. Signals — what stands out? [#2-signals--what-stands-out] The application can surface geographic patterns, ranked counties, review-priority scores, and other analytical signals. A signal is a way to focus attention across many places or measures. It is not a final epidemiological conclusion. When a signal is based on multiple inputs, review the inputs and the methodology version that produced it. Do not infer that a higher score is a probability, incidence rate, individual risk, or disease-burden estimate unless the evidence and method explicitly say so. ## 3. Context — what else should be considered? [#3-context--what-else-should-be-considered] Use the available One Health context to understand what may be relevant to the signal: vector or pathogen evidence, environmental conditions, population context, and related scientific evidence. Context can make a question more specific, but association or co-occurrence alone does not establish causation. ## 4. Interpretation — what does the evidence support? [#4-interpretation--what-does-the-evidence-support] Before writing an interpretation, check: * Does the source cover the same geography and time period? * Is the release current enough for this question? * Are the measures comparable in definition, denominator, and method? * Are any values missing, suppressed, sparse, stale, or unavailable? * What does the methodology permit you to say, and what does it not permit? The safest interpretation is often conditional: “This area is worth reviewing because these available signals align,” followed by the evidence and limitations that a reviewer should verify. ## 5. Investigation — what should happen next? [#5-investigation--what-should-happen-next] Turn the interpretation into a bounded question. For example: * Which surveillance or laboratory records should be reviewed next? * Is additional vector or pathogen sampling warranted? * Does local environmental or population context change the priority for follow-up? * Which source or time period would reduce the most uncertainty? Record the selected geography, release or vintage, methodology, evidence consulted, and unresolved limitations so another reviewer can reproduce the starting point. ## 6. Public-health action — what is appropriate? [#6-public-health-action--what-is-appropriate] Atlas can help a team decide what deserves investigation. It does not authorize an intervention or make a public-health decision automatically. Action belongs to the responsible epidemiologists, agencies, and partners who can incorporate local knowledge, additional data, operational constraints, and applicable policy. ## A repeatable review pattern [#a-repeatable-review-pattern] For a defensible review, use this short loop: 1. **Select** a supported geography or question in [Atlas Explorer](https://onehealthatlas.org/explore). 2. **Scan** the signal and the equivalent table or text summary. 3. **Inspect** evidence, provenance, methodology, and limitations. 4. **Compare** only measures that are sufficiently aligned in definition, geography, and time. 5. **State uncertainty** and distinguish missing evidence from a measured zero. 6. **Write** the investigation question and the next evidence needed. 7. **Share** the supported URL or export with the review context intact. For the detailed boundaries behind this workflow, see [What is Atlas Lyme?](https://onehealthatlas.org/docs/what-is-atlas) and [Who is Atlas for?](https://onehealthatlas.org/docs/who-is-atlas-for). ## Where the signed-in workspace places each step [#where-the-signed-in-workspace-places-each-step] In the signed-in workspace, that path uses the six destinations: 1. **Atlas Explorer** holds the operating picture for the United States or one state, plus county evidence and suggested follow-up on the same address. 2. **Compare** holds two counties. It does not rank them. 3. **Ask Atlas** is the dedicated page for reviewed-literature questions when that service is enabled. It does not open a side panel. 4. **Feed**, **Settings**, and **Docs** stay their own destinations. Feed does not yet list items. Settings stores a default jurisdiction. Docs opens in a new tab and leaves the workspace URL on the original tab. Share the workspace URL for the page you mean to hand off. Read [the professional workspace](https://onehealthatlas.org/docs/professional-workspace) for addresses, evidence states, and older bookmarks. # Current capabilities (https://onehealthatlas.org/docs/current-capabilities) > See what Atlas Lyme supports in the current public release and how each capability contributes to evidence-aware investigation. This page describes the current public Atlas experience. Use it to choose a supported workflow and to avoid treating a planned or experimental idea as a released capability. ## Capability status [#capability-status] Atlas uses four status labels: * **Available now** — verified in the current public release and appropriate to document as user behavior. * **Planned** — part of the product direction, but not available to rely on today. * **Experimental/demo** — available only in a constrained, feature-gated, or validation context; do not treat it as a production commitment. * **Not supported** — outside the current product promise or deliberately excluded from the public experience. ## What you can do today [#what-you-can-do-today] | Capability | Status | How it supports investigation | Important boundary | | ------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Front Porch | Available now | Read the public introduction at `/` without a sign-in. | It does not show county scores, a map of results, or a comparison. | | Atlas Explorer | Available now | Sign in and start from the United States or one state. Read the map and county list together, then open county evidence and suggested follow-up on the same address. | A review-priority signal is not a diagnosis, disease-burden estimate, or individual risk estimate. National scope is a bounded picture, not a ranking of every U.S. county. | | Compare two counties | Available now | Open Compare for two counties from the same release and read each measure's unit, period, and availability. | The page does not rank a winner. It does not compare five counties. | | Inspect evidence and provenance | Available now | Open county evidence and **Inspect provenance** before deciding what to review next. | Check source, geography, time or vintage, release, method version, freshness, completeness, uncertainty, and limitations. | | Share a workspace address | Available now | Share an Atlas Explorer or Compare URL that keeps scope, county, compare, release, period, and Explorer mode. | Record the release and method with the URL. A URL does not guarantee that a future release will contain identical data. | | County PDF | Available now | From county evidence, export a county PDF when Atlas can verify that the file matches the displayed county, observations, sources, period, and caveats. | If that check fails, the PDF is unavailable. That is not a claim that the report contains none of a period. | ## Authenticated professional workspace [#authenticated-professional-workspace] These routes require sign-in. The [professional workspace](https://onehealthatlas.org/docs/professional-workspace) guide describes each destination. Older public bookmarks open Atlas Explorer after sign-in. They do not keep a separate public map. | Capability | Status | How it supports investigation | Important boundary | | ------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Atlas Explorer at [/explore](https://onehealthatlas.org/explore) | Available now | Start from the United States or one state, and read the map and county list. Open county evidence or suggested follow-up on that address. | National scope is a bounded picture. It is not a ranking of every U.S. county. A saved default applies only when the address has no scope and no county. On a state picture with no county, Atlas Explorer selects the first published review candidate and writes it into the address. A county that is present but does not validate opens with `selection=required` and is not replaced. | | Compare at [/compare](https://onehealthatlas.org/compare) | Available now | Compare two counties on aligned measures, with unit, period, and availability on each value. | This page does not rank a winner. | | Settings at [/app/settings](https://onehealthatlas.org/app/settings) | Available now | Save United States or a state as the next Atlas Explorer start, plus optional role, organization, and job title. Sign out, export, and removal use the account controls on the same page. | Optional fields can stay empty. The default does not change evidence values or block other geographies. | | Docs from the workspace | Available now | Open this reference in a new tab from the workspace navigation. | The original workspace tab keeps its URL. Docs is not in-page help. | | Ask Atlas at [/askatlas](https://onehealthatlas.org/askatlas) | Experimental/demo | Atlas Explorer and Compare open this dedicated page. It requests reviewed literature when that service is enabled. Explorer and Compare can pass a validated page reference and a return link. | Feature-gated. The reference is not sent as a county or comparison request. With the service off, the page says Ask Atlas is unavailable and the other pages stay usable. There is no side panel, no Structured mode, and no Both mode. History stays in this browser. | | Feed at [/app/feed](https://onehealthatlas.org/app/feed) | Planned | The destination is in the navigation. | It does not yet provide feed items or alerts. | | Data Provenance at [/data-provenance](https://onehealthatlas.org/data-provenance) | Available now | Read the current release source catalog, a conceptual lineage, and links to the methodology guides. | The page does not replace provenance beside a result, and it does not add sources that the release did not return. | | Evidence brief | Experimental/demo | A direct `plan=evidence-brief` address still opens that brief and returns to county evidence. | It is not a workspace destination. Surveillance planning is not released. | | API keys in Settings | Not supported | Public API reads do not use a key. | Settings does not generate or revoke a key. See [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access) and the [developer quickstart](https://onehealthatlas.org/docs/develop/quickstart). | ## Capabilities that are not current promises [#capabilities-that-are-not-current-promises] | Capability | Status | What this means for you | | -------------------------------------------------------------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Historical release trends | Not supported | The public explorer currently exposes one active release. A generated date is release metadata, not the date of disease observations. | | Guaranteed outbreak prediction or automated public-health action | Not supported | Atlas surfaces signals and investigation candidates. It does not predict with certainty or act on behalf of an authority. | | Clinical diagnosis or person-level exposure risk | Not supported | Atlas is a population-level public-health decision-support experience, not a clinical or individual-risk tool. | | Additional clinical, laboratory, jurisdictional, or other governed sources | Planned | Atlas is designed to adapt future sources into the same evidence model. The current release stays open-data-first. See [Sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence). | | Live EHR, TEFCA, patient-level, PHI, or production clinical-laboratory ingestion | Not supported | Naming a future standard is not a connection. No live EHR or production clinical-laboratory feed is part of this release. | | AI-generated findings treated as authoritative | Experimental/demo | AI-enabled experiences must remain grounded in approved evidence, show limitations, and retain human review. Do not use an AI suggestion as a finding by itself. | | Alerts, private feeds, or account-based evidence access | Not supported | The Front Porch remains usable without sign-in. A workspace account does not unlock different governed evidence, change a score, or authorize an interpretation. Feed does not list items, and alerts are not released. | | Separate public map, five-county comparison, or Investigation Workspace | Not supported | Older `/overview`, `/geographic_explorer`, and `/investigate` bookmarks open Atlas Explorer after sign-in. They do not restore a separate public analytical page. | ## Where to start [#where-to-start] * Sign in and open [Atlas Explorer](https://onehealthatlas.org/explore) for the map, county list, county evidence, and suggested follow-up. * Open [Compare](https://onehealthatlas.org/compare) for two counties. * Read the [professional workspace](https://onehealthatlas.org/docs/professional-workspace) guide for Atlas Explorer, Compare, Ask Atlas, Feed, Settings, and Docs. * Follow the [investigation workflows](https://onehealthatlas.org/docs/investigation-workflows) for question-to-next-step guidance. * Read [evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty) and the methodology context beside the result before relying on a signal. Keep the [AI Ethics commitments](https://onehealthatlas.org/ai-ethics) nearby for AI-enabled or experimental experiences. * Read [sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence) before treating a future source, file format, or clinical standard as available. * Read [AI-enabled decision intelligence](https://onehealthatlas.org/docs/ai-enabled-decision-intelligence) for the status of AI-assisted and future capabilities, or use the [FAQ and troubleshooting guide](https://onehealthatlas.org/docs/faq-and-troubleshooting) for common questions. The current release is a situational-awareness foundation. When a question depends on a feed, model, alert, historical comparison, or export that is not listed as available now, treat it as an open product or data dependency and do not infer the answer from the interface. # Developer overview (https://onehealthatlas.org/docs/develop) > 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 [#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-map] | Guide | Use it when you need to | | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | [Quickstart](https://onehealthatlas.org/docs/develop/quickstart) | Complete one current-release county observation read | | [REST API](https://onehealthatlas.org/docs/develop/rest) | Page a collection, handle errors, and tell versions apart | | [Geography](https://onehealthatlas.org/docs/develop/geography) | Identify a county, see when identity delivery is pending, and request display polygons | | [Indicators, measures, and observations](https://onehealthatlas.org/docs/develop/resources) | Choose a measure and read `value` with `value_state` | | [Provenance and evidence](https://onehealthatlas.org/docs/develop/provenance) | Cite source, methodology, release, and freshness fields | | [Workflow guides](https://onehealthatlas.org/docs/develop/workflows) | Query one county, compare counties, read environmental context, choose a county PDF template, and reproduce a result | | [Observation queries](https://onehealthatlas.org/docs/develop/observation-queries) | Choose a checked slice, including land cover, and see which temporal parameters that slice accepts | | [Tier 1 availability](https://onehealthatlas.org/docs/develop/tier1-availability) | Choose availability or the persisted priority read, and keep abstention, no published model, and an unknown FIPS apart | | [MCP clients](https://onehealthatlas.org/docs/develop/mcp-clients) | Connect Claude Desktop, Cursor, or a custom client, and copy the interpretation guardrails | | [OpenAPI, GitHub, and support](https://onehealthatlas.org/docs/develop/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](https://onehealthatlas.org/docs/evidence-and-uncertainty). MCP status stays on [API, MCP, and access](https://onehealthatlas.org/docs/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](https://onehealthatlas.org/docs/sources-and-canonical-evidence). ## Where the reference lives [#where-the-reference-lives] The authoritative document is the public [OpenAPI schema](https://api.onehealthatlas.org/openapi.json). The [Swagger reference](https://api.onehealthatlas.org/docs) and [ReDoc reference](https://api.onehealthatlas.org/redoc) render that same document. The generated reference for that contract is the [API reference](https://onehealthatlas.org/docs/api-reference), with pages for [discovery](https://onehealthatlas.org/docs/api-reference/discovery), [observations](https://onehealthatlas.org/docs/api-reference/observations), [provenance](https://onehealthatlas.org/docs/api-reference/provenance), [geographies](https://onehealthatlas.org/docs/api-reference/geographies), [atlas](https://onehealthatlas.org/docs/api-reference/atlas), [counties](https://onehealthatlas.org/docs/api-reference/counties), [states](https://onehealthatlas.org/docs/api-reference/states), and [schemas](https://onehealthatlas.org/docs/api-reference/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 [#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 [#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 [#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](https://onehealthatlas.org/docs/develop/rest). `GET /v1/geographies/{geography_type}/{geography_id}` is declared, and its description says delivery currently returns `503` with `CANONICAL_DATA_UNAVAILABLE` and no geometry. That route does not return polygons. `GET /v1/atlas/geometry` is the display-geometry route. See [Geography](https://onehealthatlas.org/docs/develop/geography). The observations operation describes separately enabled January 2025 environmental measures that carry `environmental_context`. On 18 October 2026 the measures catalog included those daily ids. The checked slice queries, including annual land cover, and the parameters they reject are in [Observation queries](https://onehealthatlas.org/docs/develop/observation-queries). `surveillance_context` is optional and requires an admitted Data delivery. See [Workflow guides](https://onehealthatlas.org/docs/develop/workflows). # Geography (https://onehealthatlas.org/docs/develop/geography) > Identify Atlas counties by FIPS, stay within the lower 48 and DC, and request display polygons while identity delivery is pending. Atlas joins public records on geography identity. Identity is a type plus an id. It is independent of map polygons. ## Identity [#identity] `GeographyIdentity` has two required fields: | Field | Values | | ---------------- | -------------------------------------------------------------------------------- | | `geography_type` | `county` or `state` | | `geography_id` | FIPS string with leading zeros. Five digits for a county. Two digits for a state | `GeographyType` does not include tracts, ZCTAs, or other units. `geography_type=tract` on the observations query returned HTTP 400 `INVALID_REQUEST`. These guides use the lower 48 states and the District of Columbia. Keep FIPS in a string so a leading zero survives JSON and CSV. | Example id | Place | Role in these guides | | ---------- | ------------------------------------ | ----------------------------------------------------------------------- | | `36061` | New York County, New York | Quickstart observation | | `08001` | Adams County, Colorado | Comparison row that can be `MISSING` while another county is `OBSERVED` | | `09110` | Capitol Planning Region, Connecticut | Selected land-cover geography named by that measure | | `51013` | Arlington County, Virginia | The other selected land-cover geography named by that measure | `09110` is a Connecticut planning-region geography. The land-cover measure limitations say it has no historical Connecticut county crosswalk. Use the FIPS the measure names. Do not rewrite it to an older county id. ## Observations are county queries [#observations-are-county-queries] `GET /v1/observations` requires `geography_type=county` and 1 to 500 `geography_id` values. Repeat the parameter once per county. The service orders rows by measure id, county FIPS, period start, and observation id. It does not accept a caller sort. A five-digit id that matches no row can still return HTTP 200 and `data: []`. That happened for `geography_id=99999` with `case_count_floor_2023` and `year=2023`. Empty is a successful query with no observation. ## Geography resource delivery is unavailable [#geography-resource-delivery-is-unavailable] The public contract declares: ```text GET /v1/geographies/{geography_type}/{geography_id} ``` Delivery pending at the last production check, 18 October 2026. Production API, 18 October 2026. This is not a live health indicator. The operation summary is "Get geography identity (delivery pending)". The description says the route validates a county or state FIPS and currently returns `503` `CANONICAL_DATA_UNAVAILABLE`. No geometry is returned. The success schema exists on the operation for a later delivery. Callers do not receive a `Geography` label or parent from this route today. A request to `/v1/geographies/county/08001` on 18 October 2026 returned an HTML error page. The origin status was `503`. The client status line was `504`. There was no `Geography` JSON body and no `Retry-After` header on that response. Treat geography identity delivery as unavailable. Do not parse the HTML page as a resource, and do not invent a label from the FIPS. The badge records that production check. It is not a live health indicator. The same operation still declares the canonical problem statuses, including `400`, `404` `RESOURCE_NOT_FOUND`, `429` with `Retry-After`, `413`, `414`, and `503` with `Retry-After`. ## Polygons are a different resource [#polygons-are-a-different-resource] The geography identity route does not return a polygon. When you need a county outline, call the display-geometry route: ```text GET /v1/atlas/geometry ``` ``` curl -fsS 'https://api.onehealthatlas.org/v1/atlas/geometry' ``` On 18 October 2026 that request returned HTTP 200 `application/geo+json`. The response used `Cache-Control: public, max-age=31536000, immutable` and an `ETag`. The body was a GeoJSON FeatureCollection of 3,144 features. Each feature carried `fips` and a polygon. `36061` and `11001` were in the collection. That count is a national display inventory. These guides still use the lower 48 states and the District of Columbia. The operation is [Get county display geometry](https://onehealthatlas.org/docs/api-reference/atlas#geometry_v1_atlas_geometry_get). The contract describes that response as display GeoJSON, EPSG:4326, with an immutable cache and an `ETag`. It is a generalized display boundary for maps. It is not the FIPS join key and it is not the analysis geometry used to build measures. `environmental_context.geometry_version`, when that object is present, names analysis geometry and still contains no polygons. County analytics, including `in_contiguous_tick_scope`, are on `GET /v1/counties/{fips}` together with release metadata. That route is separate from `GET /v1/observations`. Its `404` body can omit `code`. Score query parameters on that route belong to the legacy county operation; they are not observation filters. ## State ids [#state-ids] `state` is a legal `geography_type` for geography identity. The observations query documented here asks for county FIPS. The measure `state_unallocated_records_2023` uses state geography semantics and keeps records that are not assigned to a county. Read that measure's own definition before treating it as a county total. County-linked values and state-unallocated records stay separate. # MCP clients (https://onehealthatlas.org/docs/develop/mcp-clients) > Connect Claude Desktop, Cursor, or a custom client to production Atlas MCP, and copy the interpretation guardrails agents must keep. Production Atlas MCP is one anonymous Streamable HTTP endpoint. These recipes use that endpoint. They do not add a second tool schema. Arguments, bounds, and error codes stay in the [public evidence tool contract](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/main/docs/public-evidence-tools.md). Scientific reading stays in [evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty). Checked against `https://mcp.onehealthatlas.org` on 2026-10-18. ## Transport and auth [#transport-and-auth] | Item | Supported | What was checked | | -------------- | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Endpoint | `https://mcp.onehealthatlas.org/mcp` | `initialize` and `tools/list` returned HTTP 200 | | Transport | Streamable HTTP, stateless JSON | POST responses were `application/json`. Initialize did not return `Mcp-Session-Id`. Later requests still send `notifications/initialized` and `MCP-Protocol-Version` | | Accept header | `application/json` and `text/event-stream` | Both values were sent on the successful POST requests | | Protocol | `2025-06-18` | The server returned `protocolVersion` `2025-06-18` and `serverInfo` `atlas-lyme-mcp` `0.1.0` | | Auth | None | The same initialize succeeded with no credential header and again when a non-credential token was sent. Do not send an API key, OAuth client, or Settings secret | | Process health | `GET https://mcp.onehealthatlas.org/healthz` | HTTP 200 and `{"status":"ok"}`. This route is not an MCP tool | `GET /mcp` stays open as `text/event-stream`. Tool calls are POST requests. `GET /sse` and `POST /messages` returned HTTP 404, so legacy SSE is not a published transport. Production does not publish a stdio endpoint. `tools/list` returned exactly four tools: `atlas_discover_indicators`, `atlas_get_county_profile`, `atlas_get_evidence_provenance`, and `atlas_resolve_geographies`. `resources/list` and `prompts/list` returned empty arrays. `server_status` and `atlas_smoke_test` returned `isError: true` with text `Unknown tool: server_status` and `Unknown tool: atlas_smoke_test`. The September 2026 smoke-only receipt is historical. [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access) keeps that boundary. ## Claude Desktop [#claude-desktop] Use a custom connector. Claude Desktop's `claude_desktop_config.json` is for local stdio servers. Do not add this URL there, and do not select SSE. For Free, Pro, and Max, open **Customize**, then **Connectors**, then **Add custom connector**. Team and Enterprise owners add the same connector under **Organization settings**, then **Connectors**, before members connect it. Free accounts are limited to one custom connector. | Field | Value | | --------------------- | ------------------------------------ | | Name | One Health Lyme Gap Atlas | | Remote MCP server URL | `https://mcp.onehealthatlas.org/mcp` | | Authentication | No sign in | | Request headers | None | Claude connects to a custom connector from Anthropic's cloud, including from Claude Desktop. The server must stay reachable on the public internet. An administrator who pushes managed MCP servers can use this entry. `transport` `http` is Streamable HTTP. Leave out `oauth`, `headers`, and `headersHelper`. ```json { "name": "one-health-lyme-gap-atlas", "transport": "http", "url": "https://mcp.onehealthatlas.org/mcp" } ``` ## Cursor [#cursor] Add this server to the user file `~/.cursor/mcp.json`, or to a project `.cursor/mcp.json` when the project should share it. Keep any servers already in the file. `type` `http` is the Streamable HTTP value Cursor's CLI accepts. Do not set `sse` or `streamable-http`. Do not add `headers` or an `auth` object. ```json { "mcpServers": { "one-health-lyme-gap-atlas": { "type": "http", "url": "https://mcp.onehealthatlas.org/mcp" } } } ``` Reload MCP, then confirm the four tool names above. `atlas_resolve_geographies` with `{"geographies":[{"county_fips":"01001"}]}` is an identity check. A resolved county is not evidence that an observation exists. ## Custom client [#custom-client] Send one JSON-RPC message per POST. Do not send a credential. The checked initialize response did not include `Mcp-Session-Id`. If a response includes that header, send it on every later request. After `initialize` succeeds, send `notifications/initialized` before any other request. That notification has no `id`. On 2026-10-18 the server returned HTTP 202 and an empty body. Include `MCP-Protocol-Version: 2025-06-18` on that notification and on every later request. The value is the protocol version negotiated by `initialize`. ```sh curl -fsS \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -X POST 'https://mcp.onehealthatlas.org/mcp' \ --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"example","version":"0.0.0"}}}' ``` ```sh curl -fsS \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-06-18' \ -X POST 'https://mcp.onehealthatlas.org/mcp' \ --data '{"jsonrpc":"2.0","method":"notifications/initialized"}' ``` ```sh curl -fsS \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2025-06-18' \ -X POST 'https://mcp.onehealthatlas.org/mcp' \ --data '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' ``` The owning repository's check client is `python -m atlas_lyme_mcp.check_client` with `MCP_URL=https://mcp.onehealthatlas.org/mcp`. It is not required for a REST read. ## Interpretation guardrails [#interpretation-guardrails] Copy this block into the agent instructions that call these tools. It restates the published evidence rules. It does not add a score, a diagnosis, or a completeness claim. ```text Atlas interpretation guardrails: - Missing is not zero. MISSING, UNAVAILABLE, SUPPRESSED, NO_COUNTY_LINKED_RECORD, an empty selection, and a failed request are not a published zero. A published ZERO stays a real zero. NO_RECORDS does not establish biological absence. - A gap or a review priority is not risk or a diagnosis. A priority score is not individual risk, a disease-burden estimate, or proof of causation. County identity is not evidence that an observation exists, and discovery is not county availability. - Cite the release id, methodology id and version, semantic version, source vintage, and limitations from the response you received. Do not invent a release id when it is null. A successful call does not mean every page was retrieved. ``` Keep the same fields a REST client keeps. [Provenance and evidence](https://onehealthatlas.org/docs/develop/provenance) names them. Replace example identifiers with the values in the tool result. # Observation queries (https://onehealthatlas.org/docs/develop/observation-queries) > Checked observation slices, including annual land cover, and the temporal parameters each slice accepts or rejects. These are the checked observation slices for the current public contract, including annual land cover. Each tab is one slice. The choice is stored in this browser. A heading link opens that slice. The matrix under the tabs is the supported and rejected temporal parameters, checked against `https://api.onehealthatlas.org` on 18 October 2026. The release id on the successful rows was `governed-2026-10-15-january-climate-prod`. County examples use FIPS `36061` (New York County, New York). Atlas product geography for these guides is the lower 48 states and the District of Columbia. Preserve leading zeros. Discover ids before you copy one. `GET /v1/measures?page_size=100` on that date returned 25 measures and `next_page_token` null. A later release can add or remove ids. Read `temporal_semantics` on the measure you selected. The generated parameter list stays on [Observations](https://onehealthatlas.org/docs/api-reference/observations). The machine-readable document is the [OpenAPI schema](https://api.onehealthatlas.org/openapi.json). ## Checked requests [#checked-requests] ### Annual surveillance ### Annual surveillance [#annual-surveillance] Published human surveillance in this check is the 2023 case-count floor, measure `case_count_floor_2023`. It is a privacy-protected floor in `cases`. It is not a diagnosis, a complete incidence count, or an individual risk estimate. ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=36061&year=2023' ``` That request returned HTTP 200 and one row: `temporal_grain` `YEAR`, period 2023-01-01 through 2023-12-31, `value_state` `OBSERVED`, a numeric `value`, `unit` `cases`, and null `environmental_context` and `surveillance_context`. Read the number from your response. The same county and measure with `start_date` 2023-01-01 and `end_date` 2023-12-31, and no `year`, returned the same kind of row. Sending `year` together with both dates returned HTTP 400 `INVALID_REQUEST` and detail `Use year or a date range, not both.` Omitting the period returned HTTP 400 `INVALID_REQUEST` and detail `Supply a year or both start_date and end_date.` `year` 2022 returned HTTP 200, `data` empty, meta `availability` `UNAVAILABLE`, and `reason` `NO_PUBLISHED_RESULTS`. That empty page is not a 2022 surveillance slice and not a zero. `vintage_year` returned HTTP 400 `UNSUPPORTED_FILTER` and detail `This measure does not support vintage_year.` A stratification value of age returned HTTP 400 `UNSUPPORTED_STRATIFICATION` and detail `This release has no governed strata.` ### Cumulative vector and pathogen ### Cumulative vector and pathogen [#cumulative-vector-and-pathogen] The checked vector measure is `scapularis_status`. The checked pathogen measure is `burgdorferi_status`. The catalog also lists `pacificus_status`. This page does not treat that third id as checked. Both checked measures use one cumulative day, `start_date` and `end_date` 2025-12-31. `temporal_grain` on the rows was `CUMULATIVE`. That day is not an annual collection event. ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=scapularis_status&geography_type=county&geography_id=36061&start_date=2025-12-31&end_date=2025-12-31' ``` The scapularis request returned HTTP 200 and one row: publisher value Established, `value_state` `OBSERVED`, `unit` `status`, source id tick, and `surveillance_context.evidence.normalized_state` `established`. The same dates for `burgdorferi_status` returned HTTP 200, publisher value No records, `value_state` `NO_RECORDS`, source id pathogen, and `normalized_state` `unknown`. `No records` does not establish absence. County status does not establish abundance, prevalence, or individual risk. `year` 2025 on `scapularis_status` returned HTTP 400 `UNSUPPORTED_FILTER` and detail `CDC status is cumulative as published; omit year and use start_date=end_date=2025-12-31.` A range from 2025-01-01 through 2025-12-31 returned the same code and detail. `vintage_year` returned HTTP 400 `UNSUPPORTED_FILTER` and detail `This measure does not support vintage_year.` Missing dates returned HTTP 400 `INVALID_REQUEST` and detail `Supply a year or both start_date and end_date.` A stratification value of species returned HTTP 400 `UNSUPPORTED_STRATIFICATION`. ### January 2025 environment ### January 2025 environment [#january-2025-environment] The checked measure is `nclimgrid_tavg_county_day` on indicator `climate_temperature`. The catalog also lists `nclimgrid_tmax_county_day`, `nclimgrid_tmin_county_day`, and `nclimgrid_prcp_county_day`. Those three ids were not the checked observation. The measure limitation says this is January 2025 descriptive weather context only, with no Lyme causal, risk, or ML claim. `environmental_context` is coverage for that weather value. It is not a disease model. ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=nclimgrid_tavg_county_day&geography_type=county&geography_id=36061&start_date=2025-01-17&end_date=2025-01-17' ``` That request returned HTTP 200 and one row: temporal grain DAY, period 2025-01-17 through 2025-01-17, `value_state` `OBSERVED`, unit degree Celsius, and `environmental_context.coverage_status` `COMPLETE`. The day convention on that object says the labeled 24-hour period ends in the early morning and is not a midnight calendar day. Read the temperature from your response. `year` 2025 returned HTTP 200 and 31 rows, each with temporal grain DAY, from 2025-01-01 through 2025-01-31. It did not return one annual aggregate. The January window with `start_date` 2025-01-01 and `end_date` 2025-01-31 also returned 31 rows. 2025-02-01 through 2025-02-01 returned HTTP 200, `data` empty, meta `availability` `UNAVAILABLE`, and `reason` `NO_PUBLISHED_RESULTS`. February is not a published environmental slice. `vintage_year` returned HTTP 400 `UNSUPPORTED_FILTER` and detail `This measure does not support vintage_year.` Missing dates returned HTTP 400 `INVALID_REQUEST`. A stratification value of age returned HTTP 400 `UNSUPPORTED_STRATIFICATION`. ### Land cover ### Land cover [#land-cover] The checked measure is `nlcd_forest_area_share_county_year` on indicator `land_cover_context`. The measure resource says the unit is `fraction`, the temporal semantics are 2025, and missingness keeps a true zero as zero while an unselected county has no observation. Its limitation names selected 2025 TIGER geographies 09110 and 51013 only. This is land-cover context. It is not the January weather series, and it is not a 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=36061&year=2025' ``` FIPS 36061 is outside those selected geographies. On 18 October 2026 that request returned HTTP 200, `data` empty, meta `availability` `UNAVAILABLE`, and `reason` `NO_PUBLISHED_RESULTS`. The inclusive 2025 range, without `year`, returned the same empty page. `year` 2023 also returned that empty page. An empty page is not a zero share. A selected geography is a different request. See [Workflow guides](https://onehealthatlas.org/docs/develop/workflows). `vintage_year` returned HTTP 400 `UNSUPPORTED_FILTER` and detail `This measure does not support vintage_year.` Sending `year` together with both dates returned HTTP 400 `INVALID_REQUEST` and detail `Use year or a date range, not both.` Omitting the period returned HTTP 400 `INVALID_REQUEST` and detail `Supply a year or both start_date and end_date.` A stratification value of class returned HTTP 400 `UNSUPPORTED_STRATIFICATION`. ### 2022 SVI and ACS ### 2022 SVI and ACS [#2022-svi-and-acs] County SVI, population, and insurance context require `vintage_year` 2022. The checked measure is `svi_percentile_2022`. The same vintage also returned HTTP 200 for `population_2022` and `uninsured_percent_2022`. The period on those rows is the ACS window 2018-01-01 through 2022-12-31, `temporal_grain` `PERIOD`. That window is not five annual observations. A percentile rank is not a percentage of people, and it is not individual risk. ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=svi_percentile_2022&geography_type=county&geography_id=36061&vintage_year=2022' ``` The SVI request returned HTTP 200 and one row: `value_state` `OBSERVED`, unit percentile, `county_context.vintage_year` 2022, `county_context.source_field` `RPL_THEMES`, and `category_label` null. `environmental_context` and `surveillance_context` were null. `year` 2022, the ACS dates as `start_date` and `end_date`, and a request with no time parameter each returned HTTP 400 `INVALID_REQUEST` and detail `Supply vintage_year for county context.` `vintage_year` 2023 returned HTTP 400 `UNSUPPORTED_FILTER` and detail `Unsupported county context time selection.` A stratification value of age returned HTTP 400 `UNSUPPORTED_STRATIFICATION`. An absent row is unavailable evidence. It is not zero. ### 2023 RUCC ### 2023 RUCC [#2023-rucc] Rural-urban classification requires `vintage_year` 2023 and measure `rucc_2023`. The code is a category for that vintage. It is not an annual rate, an ordered distance, or individual risk. Period dates on the checked row were null. ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=rucc_2023&geography_type=county&geography_id=36061&vintage_year=2023' ``` That request returned HTTP 200 and one row: `temporal_grain` `VINTAGE_YEAR`, `value` 1, `value_state` `OBSERVED`, `unit` `code`, `county_context.vintage_year` 2023, `county_context.source_field` `RUCC_2023`, and `category_label` `Metro: area population at least 1 million`. The row limitations say codes 1 through 9 are vintage-specific categories. Do not substitute an older vintage. `year` 2023 and the 2023 calendar dates as `start_date` and `end_date` each returned HTTP 400 `INVALID_REQUEST` and detail `Supply vintage_year for county context.` `vintage_year` 2022 returned HTTP 400 `UNSUPPORTED_FILTER` and detail `Unsupported county context time selection.` A stratification value of age returned HTTP 400 `UNSUPPORTED_STRATIFICATION`. An absent row is unavailable evidence. It is not zero. ## Temporal parameters [#temporal-parameters] Supported means the checked request returned HTTP 200 and a row, or, where noted, HTTP 200 and an explicit empty page. Rejected means HTTP 400 before a row. Empty `data` is not zero and does not establish absence. | Slice | `year` | `start_date` and `end_date` | `vintage_year` | `stratification` | | ------------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | -------------------------------------- | | Annual surveillance | Supported for 2023. 2022 was HTTP 200 and an empty page | Supported for 2023-01-01 through 2023-12-31. Both `year` and the dates together are rejected | Rejected. `UNSUPPORTED_FILTER` | Rejected. `UNSUPPORTED_STRATIFICATION` | | Cumulative vector and pathogen | Rejected. `UNSUPPORTED_FILTER` | Supported only when both dates are 2025-12-31. A wider 2025 range was rejected | Rejected. `UNSUPPORTED_FILTER` | Rejected. `UNSUPPORTED_STRATIFICATION` | | January 2025 environment | Supported for 2025 as 31 daily January rows, not one annual value | Supported for one January day and for 1 January through 31 January. 1 February was HTTP 200 and an empty page | Rejected. `UNSUPPORTED_FILTER` | Rejected. `UNSUPPORTED_STRATIFICATION` | | Land cover | Accepted for 2025 and for 2023. Both were HTTP 200 and an empty page for FIPS 36061 | Accepted for 2025-01-01 through 2025-12-31 as an empty page for this county. Both `year` and the dates together are rejected | Rejected. `UNSUPPORTED_FILTER` | Rejected. `UNSUPPORTED_STRATIFICATION` | | 2022 SVI and ACS | Rejected. `INVALID_REQUEST` | Rejected. `INVALID_REQUEST` | Required. 2022 is supported. 2023 is rejected | Rejected. `UNSUPPORTED_STRATIFICATION` | | 2023 RUCC | Rejected. `INVALID_REQUEST` | Rejected. `INVALID_REQUEST` | Required. 2023 is supported. 2022 is rejected | Rejected. `UNSUPPORTED_STRATIFICATION` | There is no caller sort and no aggregation. `sort`, `aggregation`, and an unknown parameter are `UNSUPPORTED_FILTER` on the observations operation. See [Indicators, measures, and observations](https://onehealthatlas.org/docs/develop/resources). ## Slices the contract does not support [#slices-the-contract-does-not-support] These are not additional slices. Do not fill them in from another measure. * An annual surveillance year other than 2023. The checked 2022 request was an empty page with `NO_PUBLISHED_RESULTS`. * A CDC `year`, or any CDC date range other than both dates equal to 2025-12-31. * An environmental day outside January 2025. `year` 2025 does not mean a full calendar year. * `vintage_year` on annual surveillance, cumulative status, or the January environmental measures. * `year` or a date range on SVI, ACS, or RUCC context. Those measures reject annual and day filters. * A vintage other than 2022 for SVI and ACS, or other than 2023 for RUCC. * Any `stratification`. The checked release has no governed strata. * Counties outside the lower 48 and the District of Columbia. The environmental measure limitation says coverage outside the contiguous set is unavailable. These guides do not add a request for that coverage. The January environment tab is weather. The land-cover tab is the annual series, and an unselected county stays an empty page. # Provenance and evidence (https://onehealthatlas.org/docs/develop/provenance) > Read source, methodology, release, freshness, and value-state fields together before citing an Atlas observation. An observation is reproducible only when the value, the value state, and the provenance fields from that same response stay together. Response time is not publisher freshness. A null timestamp is unknown. Do not fill it in. ## Fields that travel with the value [#fields-that-travel-with-the-value] From the observation you received, keep: | Field | Role | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `observation_id` | Stable observation identity and compact provenance reference | | `measure_id` | Exact measure | | `geography` | `geography_type` and `geography_id` | | `period_start`, `period_end`, `temporal_grain` | Inclusive governed period and grain | | `value`, `value_state`, `unit`, `denominator` | The result. Read them as a set | | `source_id` | Public source resource key | | `lineage_source_id`, `dataset_id` | Lineage and dataset ids. They are distinct from `source_id` | | `methodology_id` | Methodology resource id. Null when the row has no governed methodology id | | `methodology_version` | Transformation version | | `release_methodology_version` | Release methodology version when present | | `semantic_version` | Semantic contract version for the row | | `release_id` | Release identity | | `provenance_ref` | Structured provenance identity. The schema says this is not a literature citation | | `source_vintage`, `source_label`, `source_url` | Publisher context copied onto the row when governed | | `source_published_at`, `atlas_acquired_at`, `atlas_processed_at` | Observation timestamps when governed. Null is not inferred freshness. These fields are not the deprecated Source timestamps | | `limitations` | Interpretation limits. Preserve the list | | `evidence` | `resource_type` and `resource_id`, plus optional source, provenance, version, release, and uri fields | | `surveillance_context` | Optional. Supplied only through an admitted Data release and supported slice. Omitted or null carries no evidence-state, comparability, or lag claim. `normalized_state` preserves Data semantics, and the publisher value remains `value` | `evidence.resource_type` on the contract's synthetic observation example is `observation`, and `resource_id` repeats the observation id. `provenance_ref` on a checked case-floor row was the same string as `observation_id`. That equality is not a second citation format. It is the provenance identity returned for that row. ## Cite from discovery [#cite-from-discovery] Discover the source and the measure, observe one county row, then resolve the ids that row actually returned. A null on the measure is not a null on the observation. ### Discover ``` curl -fsS 'https://api.onehealthatlas.org/v1/sources?page_size=100' ``` ``` curl -fsS 'https://api.onehealthatlas.org/v1/measures/case_count_floor_2023' ``` ### Observe ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=08001&year=2023' ``` ### Resolve ``` curl -fsS 'https://api.onehealthatlas.org/v1/sources/human' ``` ``` curl -fsS 'https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1' ``` ## Null value and limitations [#null-value-and-limitations] `value` null is not zero. `MISSING`, `SUPPRESSED`, and `UNAVAILABLE` require a null `value`. Preserve `limitations` with that value. Open a row for the schema sentence. | Field | Type | Required | Description | | --- | --- | --- | --- | | `atlas_acquired_at` | date-time \| null | no | Atlas acquisition time when governed; distinct from source publication and processing. | | `atlas_processed_at` | date-time \| null | no | Atlas processing time when governed; distinct from response time. | | `denominator` | string \| null | yes | Governed denominator; null means it is not supplied and must not be inferred. | | `limitations` | string[] | yes | Governed interpretation limitations; preserve alongside values and versions. | | `methodology_id` | string \| null | yes | Exact governed methodology resource ID; null when not governed. | | `source_published_at` | date-time \| null | no | Publisher timestamp when governed; null is not inferred freshness. | | `value` | number \| string \| null | yes | Read with value_state and unit; null never means zero. | | `value_state` | ValueState | yes | OBSERVED is nonzero; ZERO is numeric zero; MISSING/SUPPRESSED/UNAVAILABLE require null; NO_COUNTY_LINKED_RECORD retains the literal no_county_linked_record; NO_RECORDS retains CDC's No records. Neither establishes biological absence. | Checked on 18 October 2026. FIPS `08001`, measure `case_count_floor_2023`, and `year=2023` returned `value` null and `value_state` `MISSING`. FIPS `36061` for the same measure and year returned `value_state` `OBSERVED` and a numeric `value`. `limitations` matched on those two rows. `source_published_at` and `atlas_processed_at` were null. Observation `atlas_acquired_at` was present. The blocks below are those checked fields, not a full response body. ```json title="Checked gap observation fields" { "observation_id": "43c0ce4e82c89ba4d75ebca07f97e63d75fdf18a0dae9fed778aa22266c81273", "geography": { "geography_type": "county", "geography_id": "08001" }, "value": null, // [!code highlight] "value_state": "MISSING", // [!code word:MISSING] "source_label": "CDC Lyme surveillance", "source_published_at": null, // [!code highlight] "atlas_acquired_at": "2026-09-07T17:21:14.768948-07:00", "atlas_processed_at": null, // [!code highlight] "methodology_id": "human_confirmed_probable_case_floor_v1", "methodology": "x5j9 confirmed plus probable", "methodology_version": "semantic_county_assembly_v1", "release_methodology_version": "semantic-2.0.0", "release_id": "governed-2026-10-15-january-climate-prod", "provenance_ref": "43c0ce4e82c89ba4d75ebca07f97e63d75fdf18a0dae9fed778aa22266c81273", "limitations": [ "Published surveillance values are privacy-protected floors, not complete incidence estimates.", // [!code highlight] "Privacy-protected floor.", // [!code highlight] "This is a deterministic surveillance follow-up priority release, not a diagnosis, prediction, causal claim, exposure map, or individual risk estimate. Published human values are privacy-protected floors; no records is not absence. Human rows with explicitly unavailable state geography are retained in source provenance but are not allocated to county or state release values. Restricted pathogen source gaps are explicitly unknown source coverage. Selected 2025 TIGER geographies 09110 and 51013 only; unselected counties are not zero. COMPLETE describes valid source-supported area; preserve source coverage fraction. 09110 is Capitol Planning Region, with no historical Connecticut county crosswalk. Official MRLC mosaic lineage, not USGS S3 tiles. Descriptive land-cover context only; no Lyme causal/risk estimate or automatic ML admission." // [!code highlight] ], "evidence": { "resource_type": "observation", "resource_id": "43c0ce4e82c89ba4d75ebca07f97e63d75fdf18a0dae9fed778aa22266c81273", "source_id": "human", "provenance_ref": "43c0ce4e82c89ba4d75ebca07f97e63d75fdf18a0dae9fed778aa22266c81273", "semantic_version": "2.0.0", "methodology_version": "semantic_county_assembly_v1", "release_id": "governed-2026-10-15-january-climate-prod", "uri": null // [!code highlight] } } ``` ```json title="Checked observed value" { "geography": { "geography_type": "county", "geography_id": "36061" }, "value": 1114.0, // [!code highlight] "value_state": "OBSERVED", // [!code word:OBSERVED] "unit": "cases" } ``` ## Source and observation field names [#source-and-observation-field-names] Names that look paired are still different properties. Open a row for the schema sentence, then read the checked resources below. | Field | Schema | Type | Required | Description | | --- | --- | --- | --- | --- | | `source_id` | Observation | Source.source_id | yes | Public source resource key; distinct from lineage_source_id and dataset_id. | | `source_label` | Observation | Source.label | no | Observation field. The source resource field with this value is label. | | `source_published_at` | Observation | Source.published_at | no | Publisher timestamp when governed; null is not inferred freshness. | | `published_at` | Source | date-time \| null | no | Source field. Deprecated. The observation publisher timestamp is source_published_at. | | `atlas_acquired_at` | Observation | Source.atlas_acquired_at | no | Atlas acquisition time when governed; distinct from source publication and processing. Deprecated on Source. Not deprecated on Observation. | | `atlas_processed_at` | Observation | date-time \| null | no | Atlas processing time when governed; distinct from response time. Observation field. Source has no atlas_processed_at. | | `upstream_updated_at` | Source | date-time \| null | no | Governed publisher update time; null when unavailable. | | `source_retrieved_at` | Source | date-time \| null | no | Governed source retrieval time; null when unavailable. | | `lineage_source_id` | Observation | Source.lineage_source_id | no | Same name on Observation and Source. Nullable and not required on Observation. Required string on Source. | | `dataset_id` | Observation | Source.dataset_id | no | Same name on Observation and Source. Nullable and not required on Observation. Required string on Source. | | `release_id` | Observation | Source.release_version | yes | Governed release identity for reproducibility. | | `methodology_id` | Observation | Methodology.methodology_id | yes | Exact governed methodology resource ID; null when not governed. | | `methodology` | Observation | Methodology.description | no | Observation text field. The methodology resource field with this text is description. | | `methodology_version` | Observation | string | yes | Transformation version, distinct from methodology resource version. | | `release_methodology_version` | Observation | Methodology.version | no | Observation field. The methodology resource version is Methodology.version. | | `limitations` | Observation | string[] | yes | Governed interpretation limitations; preserve alongside values and versions. | | `provenance_ref` | Observation | EvidenceReference.provenance_ref | yes | Structured observation provenance identity; not a literature citation. | ```json title="Checked source resource" { "source_id": "human", "label": "CDC Lyme surveillance", // [!code word:label] "publisher": "Centers for Disease Control and Prevention", "lineage_source_id": "cdc_lyme", "dataset_id": "x5j9-wybp", "release_version": "governed-2026-10-15-january-climate-prod", // [!code word:release_version] "source_version": null, // [!code highlight] "published_at": null, // [!code highlight] "atlas_acquired_at": null, // [!code highlight] "upstream_updated_at": null, // [!code highlight] "source_retrieved_at": null, // [!code highlight] "limitations": [ "County-of-residence surveillance. County-linked values are published privacy-protected floors, not complete incidence estimates." // [!code highlight] ] } ``` ```json title="Checked methodology resource" { "methodology_id": "human_confirmed_probable_case_floor_v1", "version": "semantic-2.0.0", // [!code word:version] "description": "x5j9 confirmed plus probable", // [!code word:description] "limitations": [ "Privacy-protected floor." // [!code highlight] ], "release_version": "governed-2026-10-15-january-climate-prod" } ``` ## Source and methodology resources [#source-and-methodology-resources] Resolve `source_id` and `methodology_id` from the observation with the detail routes in [Cite from discovery](#cite-from-discovery). Replace those ids with the ids on your observation. A source resource adds `publisher`, `release_version`, `source_version`, `published_at`, `upstream_updated_at`, and `source_retrieved_at`. On the checked `human` source, `publisher` was present and `published_at`, `atlas_acquired_at`, `upstream_updated_at`, and `source_retrieved_at` were null. Those nulls stay null. The observation field `atlas_acquired_at` is separate. On the checked case-floor rows it was present while the source field was null.
## Deprecated source timestamps [#deprecated-source-timestamps] The [Source](https://onehealthatlas.org/docs/api-reference/schemas#schema-source) schema marks `published_at` and `atlas_acquired_at` deprecated. Those two fields belong to the source resource. An [Observation](https://onehealthatlas.org/docs/api-reference/schemas#schema-observation) keeps a separate set of timestamps, and the contract does not mark that set deprecated. | Object | Field | Contract mark | What it measures | | ----------- | --------------------- | ------------- | ----------------------------------------------------------------- | | Source | `published_at` | Deprecated | Former publisher timestamp on the source resource | | Source | `atlas_acquired_at` | Deprecated | Former Atlas acquisition time on the source resource | | Source | `upstream_updated_at` | Current | Governed publisher update time. Null when unavailable | | Source | `source_retrieved_at` | Current | Governed retrieval time. Null when unavailable | | Observation | `source_published_at` | Current | Publisher timestamp when governed. Null is not inferred freshness | | Observation | `atlas_acquired_at` | Current | When Atlas acquired the observation, when governed | | Observation | `atlas_processed_at` | Current | When Atlas processed the observation, when governed | The name `atlas_acquired_at` appears on both objects. Deprecation applies to the Source field. It does not apply to the observation field. On 18 October 2026, all six sources from `GET /v1/sources` had `published_at`, `atlas_acquired_at`, `upstream_updated_at`, and `source_retrieved_at` null. The `human` source still named its publisher. The same day, `GET /v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=36061&year=2023` returned one row. On that row, `source_published_at` was null, `atlas_acquired_at` was 2026-09-07T17:21:14.768948-07:00, and `atlas_processed_at` was null. Read the timestamp from the object you cite. A null deprecated source field does not clear the observation timestamp. A methodology resource has `methodology_id`, `measure_id`, `version`, `description`, `limitations`, `semantic_version`, and `release_version`. Its `version` is the methodology resource version. The observation's `methodology_version` is the transformation version. Keep both when both are present. Unknown ids return HTTP 404 `RESOURCE_NOT_FOUND`. Supported detail responses include `ETag`. A matching `If-None-Match` returns HTTP 304 and an empty body.
## Freshness [#freshness] | Clock | What it measures | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `period_start` and `period_end` | The governed observation period | | `source_vintage` | Publisher vintage label when present | | `source_published_at` | Publisher timestamp when governed | | `atlas_acquired_at` | When Atlas acquired the observation, when governed. On a Source resource the same field name is deprecated | | `atlas_processed_at` | When Atlas processed the row, when governed | | Source `upstream_updated_at` | Governed publisher update time. Null when unavailable | | Source `source_retrieved_at` | Governed retrieval time. Null when unavailable | | `meta.response_at` | When this HTTP response was built | | `environmental_context.upstream_date_modified` | Upstream modification metadata when environmental context is present. The schema says this is never original publication or first availability | The contract states that response time is not publisher freshness. A generated or response timestamp does not become the surveillance observation date. ## Evidence semantics [#evidence-semantics] `value_state` answers a different question from a low number: * `OBSERVED` is a nonzero value under the measure's unit and limitations. * `ZERO` is a published numeric zero. It remains bounded by the measure's coverage and method. * `MISSING`, `SUPPRESSED`, and `UNAVAILABLE` require a null `value`. `SUPPRESSED` means the value was withheld. `MISSING` and `UNAVAILABLE` are gaps. * `NO_COUNTY_LINKED_RECORD` retains the literal `no_county_linked_record`. The schema says this is not evidence of absence. * `NO_RECORDS` retains CDC's publisher literal `No records`. The schema says this does not establish biological absence. Surveillance floors and gap scores are not diagnoses, individual risk estimates, or causal claims. `environmental_context`, when an observation includes it, is descriptive weather coverage. A null `environmental_context` does not supply that coverage. A null or omitted `surveillance_context` does not establish absence or temporal comparability. The same interpretation for people using the Atlas screens is in [Evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty) and [Releases and methodology labels](https://onehealthatlas.org/docs/releases-and-methodology). ## Source identity survives normalization [#source-identity-survives-normalization] The fields above are the public provenance contract for an observation in the current release. Atlas is designed so a later governed source can pass through a source-specific adapter and a terminology mapping and still arrive as this same observation shape. The mapping can annotate source meaning. It does not replace `source_id`, `lineage_source_id`, `dataset_id`, or `source_vintage` with a generic label. Read `value_state` with `limitations`. `MISSING`, `SUPPRESSED`, and `UNAVAILABLE` stay gaps or withheld values. Uncertainty recorded in `limitations` stays a limitation. Those states are not rewritten into `ZERO`. HTTP fields stay in the [OpenAPI schema](https://api.onehealthatlas.org/openapi.json) and the generated [provenance reference](https://onehealthatlas.org/docs/api-reference/provenance). The released MCP tool atlas\_get\_evidence\_provenance reads a published source or methodology for the expected current release, and atlas\_get\_county\_profile reads county observations for explicit measure-period selections. Both keep this canonical value state, source identity, and limitations. atlas\_resolve\_geographies resolves county identity only and does not establish that an observation exists. Arguments and bounds stay in the [public evidence tool contract](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9/docs/public-evidence-tools.md). The September 2026 smoke-only development receipt is historical. [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access) records the six-tool production surface. [Sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence) separates later source adapters from the open-data release available now. ## States for source and methodology reads [#states-for-source-and-methodology-reads] | State | Result | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Success | HTTP 200 and `data` for the id you asked for | | Empty collection | `GET /v1/sources` can return HTTP 200 and `data: []` when a page is exhausted. Detail routes identify one id, so exhaustion is not their empty state | | Not found | HTTP 404 `RESOURCE_NOT_FOUND` | | Invalid parameters | HTTP 400 `INVALID_REQUEST` for a bad query value. HTTP 413 `INVALID_REQUEST` when a GET request has a body. HTTP 414 `INVALID_REQUEST` when the query string is too long | | 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 `RATE_LIMITED` and `Retry-After` | | Server unavailable | HTTP 503 and `Retry-After` | | Unknown or limited data | Null publisher timestamps and a null observation `methodology_id` stay null. HTTP 304 returns an empty body when the `ETag` matches | # Quickstart (https://onehealthatlas.org/docs/develop/quickstart) > Make one anonymous current-release observation request and read every response state that request can return. This page completes one representative production read: the 2023 published case-count floor for New York County. The measure id `case_count_floor_2023` is the example in the public observations operation and a measure in the current catalog. County FIPS `36061` is in the lower 48. You need an HTTPS client. You do not create an account, API key, or SDK project. The client tabs on this page, the workflow guides, and the REST pagination example share one choice in this browser. That choice is curl, Python httpx, R httr2, or TypeScript fetch, and it remains selected after a reload. ## Request [#request] #### curl ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=36061&year=2023' ``` #### Python ``` import httpx response = httpx.get( "https://api.onehealthatlas.org/v1/observations", params={ "measure_id": "case_count_floor_2023", "geography_type": "county", "geography_id": "36061", "year": "2023", }, timeout=30.0, ) response.raise_for_status() body = response.json() ``` #### R ``` library(httr2) observations <- request("https://api.onehealthatlas.org/v1/observations") |> req_url_query( measure_id = "case_count_floor_2023", geography_type = "county", geography_id = "36061", year = "2023" ) |> req_timeout(30) |> req_perform() observations_body <- resp_body_json(observations) ``` #### TypeScript ``` const url = new URL("https://api.onehealthatlas.org/v1/observations"); url.searchParams.append("measure_id", "case_count_floor_2023"); url.searchParams.append("geography_type", "county"); url.searchParams.append("geography_id", "36061"); url.searchParams.append("year", "2023"); const response = await fetch(url); if (!response.ok) { throw new Error(`Atlas HTTP ${response.status}`); } const body: unknown = await response.json(); ``` `curl -f` hides error bodies. Drop `-f` when you need to read a problem response. A successful body is a collection: | Field | Meaning | | ---------------------- | --------------------------------------------------------------------------- | | `data` | Observation records for this query. An empty array means no row matched. | | `meta.next_page_token` | Opaque continuation. `null` means this query is exhausted. | | `meta.response_at` | UTC time when the service built the response. This is not source freshness. | | `links.self` | Link object field. The contract allows `null`. | On 12 October 2026 this URL returned HTTP 200, one row, `value_state` `OBSERVED`, a numeric `value`, `unit` `cases`, and `environmental_context` null. The number and `release_id` belong to that release. Read them from your response. A later release can change them. Read `value` only together with `value_state` and `unit`. `case_count_floor_2023` is a privacy-protected case floor in `cases`. It is a surveillance floor, not a diagnosis, a complete incidence count, or an individual risk estimate. ## States for this request [#states-for-this-request] Use this table for the quickstart URL and the same query with a different county FIPS, period, or extra parameter. | State | What you receive | What to do | | ------------------------------ | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Success, observed value | HTTP 200, `data` has a row, `value_state` is `OBSERVED`, `value` is numeric | Record the value, unit, period, `release_id`, and `semantic_version` | | Success, explicit zero | HTTP 200 and `value_state` `ZERO` | Keep the zero. The schema defines `ZERO` as numeric zero | | Success, gap or withheld value | HTTP 200 and `value` null with `MISSING`, `SUPPRESSED`, or `UNAVAILABLE` | Leave the value null. Do not substitute zero | | Success, publisher literal | HTTP 200 and `value_state` `NO_COUNTY_LINKED_RECORD` | Keep the literal `no_county_linked_record`. The schema says this is not evidence of absence | | Success, empty collection | HTTP 200, `data` is `[]`, `next_page_token` is null | No row matched. This is not HTTP 404 | | Not found | HTTP 404, `application/problem+json`, `code` `RESOURCE_NOT_FOUND` | The operation declares this code. A missing measure id on `GET /v1/measures/{measure_id}` returned it with detail `Measure not found.` | | Invalid parameters | HTTP 400, `code` `INVALID_REQUEST` | Fix the query. Missing year and dates returns detail `Supply a year or both start_date and end_date.` Sending `year` together with both dates returns detail `Use year or a date range, not both.` `page_size=0` and `geography_type=tract` also return `INVALID_REQUEST`. `tract` includes an `errors` entry because `geography_type` must be `county` or `state` | | Unsupported filter | HTTP 400, `code` `UNSUPPORTED_FILTER`, detail `This query filter is not supported in V1.` | Remove the extra parameter. `sort`, `aggregation`, and unknown query names returned this code | | Unsupported stratification | HTTP 400, `code` `UNSUPPORTED_STRATIFICATION`, detail `This release has no governed strata.` | Omit `stratification`. The current release has no strata | | Query too broad | HTTP 400, `code` `QUERY_TOO_BROAD` | The public overview states a default pre-execution logical-result ceiling of 10,000, and that ceiling is not truncation. Narrow the county list or period and request the first page again | | Request body | HTTP 413, `code` `INVALID_REQUEST` | Canonical GET routes reject a request body | | Overlong query | HTTP 414, `code` `INVALID_REQUEST` | Shorten the query string. This status is separate from HTTP 400 | | Rate limited | HTTP 429, `code` `RATE_LIMITED`, header `Retry-After` | Wait the number of seconds in `Retry-After` when the header is present, then retry the same request. The public document does not publish a numeric quota | | Server unavailable | HTTP 503, header `Retry-After` | Wait when `Retry-After` is present, then retry. Canonical problem bodies use `application/problem+json` | | Conditional detail | HTTP 304, empty body | This applies to supported detail resources after `If-None-Match`, not to this observation collection | `GET /v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=99999&year=2023` returned HTTP 200 with `data: []` on 12 October 2026. An unknown five-digit FIPS can be an empty page. HTTP 404 is the declared not-found status; an empty page means the query succeeded and matched nothing. The same measure for Adams County, FIPS `08001`, and `year=2023` returned HTTP 200 with `value_state` `MISSING` and `value` null on that date. That row is a gap for the published floor. It is still a successful response. ## Follow provenance [#follow-provenance] Take `source_id` and `methodology_id` from the observation you received. For this measure on the checked release those ids were `human` and `human_confirmed_probable_case_floor_v1`. #### curl ``` curl -fsS 'https://api.onehealthatlas.org/v1/sources/human' curl -fsS 'https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1' ``` #### Python ``` import httpx with httpx.Client(timeout=30.0) as client: human = client.get( "https://api.onehealthatlas.org/v1/sources/human", ) human.raise_for_status() human_body = human.json() human_confirmed_probable_case_floor_v1 = client.get( "https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1", ) human_confirmed_probable_case_floor_v1.raise_for_status() human_confirmed_probable_case_floor_v1_body = human_confirmed_probable_case_floor_v1.json() ``` #### R ``` library(httr2) human <- request("https://api.onehealthatlas.org/v1/sources/human") |> req_timeout(30) |> req_perform() human_body <- resp_body_json(human) human_confirmed_probable_case_floor_v1 <- request("https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1") |> req_timeout(30) |> req_perform() human_confirmed_probable_case_floor_v1_body <- resp_body_json(human_confirmed_probable_case_floor_v1) ``` #### TypeScript ``` const humanUrl = new URL("https://api.onehealthatlas.org/v1/sources/human"); const humanResponse = await fetch(humanUrl); if (!humanResponse.ok) { throw new Error(`Atlas HTTP ${humanResponse.status}`); } const humanBody: unknown = await humanResponse.json(); const human_confirmed_probable_case_floor_v1Url = new URL("https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1"); const human_confirmed_probable_case_floor_v1Response = await fetch(human_confirmed_probable_case_floor_v1Url); if (!human_confirmed_probable_case_floor_v1Response.ok) { throw new Error(`Atlas HTTP ${human_confirmed_probable_case_floor_v1Response.status}`); } const human_confirmed_probable_case_floor_v1Body: unknown = await human_confirmed_probable_case_floor_v1Response.json(); ``` Detail routes return `data`. Unknown ids return HTTP 404 `RESOURCE_NOT_FOUND`. A matching `If-None-Match` returns HTTP 304 with an empty body. `GET /v1/sources/human` did that when the previous `ETag` was sent back. Continue with [Indicators, measures, and observations](https://onehealthatlas.org/docs/develop/resources), [Provenance and evidence](https://onehealthatlas.org/docs/develop/provenance), and the [workflow guides](https://onehealthatlas.org/docs/develop/workflows). # Indicators, measures, and observations (https://onehealthatlas.org/docs/develop/resources) > Discover current-release indicators and measures, then query county observations with explicit value states. An indicator groups measures. A measure defines one variable. An observation is that variable for one geography and period, with a value state. Discover ids from the API. Do not hard-code a catalog from this page beyond the examples the contract and the current release identify. ## Discover [#discover] ```sh curl -fsS 'https://api.onehealthatlas.org/v1/indicators?page_size=100' curl -fsS 'https://api.onehealthatlas.org/v1/measures?indicator_id=human_disease_burden&page_size=100' curl -fsS 'https://api.onehealthatlas.org/v1/measures/case_count_floor_2023' ``` Indicator collection filters are optional `indicator_id`, `page_size`, and `page_token`. Measure collection filters are optional `measure_id`, `indicator_id`, `geography_type`, `page_size`, and `page_token`. Unknown path ids return HTTP 404 `RESOURCE_NOT_FOUND`. On 12 October 2026 the indicator collection returned seven indicators and `next_page_token` null at `page_size=20`. The human-disease indicator id was `human_disease_burden`. Its measure ids included `case_count_floor_2023`, `human_status`, `incidence_floor_2023`, and `state_unallocated_records_2023`. A later release can add or remove ids. Page until `next_page_token` is null, then use the ids you received. Required measure fields include `measure_id`, `indicator_id`, `label`, `definition`, and `semantic_version`. Read `unit`, `denominator`, `geography_semantics`, `temporal_semantics`, `missingness_semantics`, `allowed_value_states`, `allowed_strata`, `methodology_id`, `source_ids`, and `limitations` when they are present. A null `denominator` means the contract did not supply one. Do not invent a population denominator. ## Query observations [#query-observations] `GET /v1/observations` requires: | Parameter | Rule | | --------------------------- | ------------------------------------------------------------------ | | `measure_id` | Exact measure id from discovery | | `geography_type` | `county` for this query | | `geography_id` | Repeat for 1 to 500 five-digit county FIPS strings | | `year` | Integer from 1900 through 2100, or omit it and send both dates | | `start_date` and `end_date` | Inclusive dates. Send both, and omit `year` | | `stratification` | Optional. The current release has no strata, and sending one fails | | `page_size` | Optional. 1 to 500. Default 100 | | `page_token` | Optional opaque token from the previous page | The published annual surveillance period for `case_count_floor_2023` is 2023. Land-cover measures in the current catalog use temporal semantics `2025`. Read `temporal_semantics` on the measure you selected. The observations operation also says only the annual 2023 period is the published surveillance period, and that separately enabled series can use other labeled periods. The checked slices, including annual land cover, and the temporal parameters each one rejects are in [Observation queries](https://onehealthatlas.org/docs/develop/observation-queries). ```sh curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=36061&year=2023' ``` The equivalent inclusive range, without `year`, returned the same kind of HTTP 200 row for this county and measure: ```sh curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=36061&start_date=2023-01-01&end_date=2023-12-31' ``` There is no caller sort and no aggregation. `sort=value`, `aggregation=sum`, and an unknown parameter each returned HTTP 400 `UNSUPPORTED_FILTER`. ## Read value\_state [#read-value_state] `value` is a number, a string, or null. The schema says null never means zero. `value_state` is one of: | State | Contract meaning | | ------------------------- | ------------------------------------------------------------------------------------------------ | | `OBSERVED` | Nonzero observed value | | `ZERO` | Numeric zero | | `MISSING` | Gap. `value` is null | | `SUPPRESSED` | Withheld. `value` is null | | `UNAVAILABLE` | Unavailable. `value` is null | | `NO_COUNTY_LINKED_RECORD` | The literal `no_county_linked_record`. The schema says this is not evidence of absence | | `NO_RECORDS` | CDC's publisher literal `No records`. The schema says this does not establish biological absence | `strata` on a checked case-floor row was an empty object. An empty object is not a breakdown. Each observation also carries period, unit, denominator, source, methodology, `semantic_version`, `release_id`, `provenance_ref`, `limitations`, and `evidence`. `environmental_context` is optional and present only for reviewed environmental context. `surveillance_context` is also optional. The schema supplies it only through an admitted Data release and supported slice. Omitted or null carries no evidence-state, comparability, or lag claim. Comparison is case-definition scope only, and alignment is descriptive. When the object is present it has `evidence`, `methodology_comparison`, and `temporal_alignment`. The observations operation says `normalized_state` preserves Data semantics and the publisher value remains `value`. Missing context does not establish absence or temporal comparability. The field list and types are in the generated [schema reference](https://onehealthatlas.org/docs/api-reference/schemas). ## States for the discovery and observation routes [#states-for-the-discovery-and-observation-routes] | State | Discovery | Observations | | ---------------------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Success | HTTP 200 and a `data` array. Detail routes return one resource in `data` | HTTP 200 and a `data` array of observations | | Empty | HTTP 200 and `data: []` when no id matches the filter | HTTP 200 and `data: []` when no observation matches. Checked with FIPS `99999` | | Not found | HTTP 404 `RESOURCE_NOT_FOUND` for an unknown path id | HTTP 404 `RESOURCE_NOT_FOUND` is declared. An unmatched county filter can be an empty page instead | | Invalid parameters | HTTP 400 `INVALID_REQUEST`, including `page_size` below 1 | HTTP 400 `INVALID_REQUEST` for a missing period, for `year` plus a date range, for `page_size` below 1, and for a `geography_type` outside `county` and `state` | | Unsupported filter or strata | HTTP 400 with the declared filter and stratification codes | Checked: `UNSUPPORTED_FILTER` and `UNSUPPORTED_STRATIFICATION` | | Query too broad | Declared as HTTP 400 `QUERY_TOO_BROAD` | Same code. 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` | Same | | Server unavailable | HTTP 503 and `Retry-After` | Same | | Unknown or limited data | Null definition, denominator, methodology, or source list fields stay null | `MISSING`, `SUPPRESSED`, `UNAVAILABLE`, `NO_COUNTY_LINKED_RECORD`, `NO_RECORDS`, a null `environmental_context`, and a null or omitted `surveillance_context` stay as returned | Detail resources also return HTTP 304 with an empty body when `If-None-Match` matches the current `ETag`. # REST API (https://onehealthatlas.org/docs/develop/rest) > Call the anonymous Atlas HTTP contract, page collections, and handle the declared errors, cache headers, and version fields. Public Atlas reads are GET requests to `https://api.onehealthatlas.org`. The contract path prefix is `/v1`. No API key is used. The machine-readable parameters and schemas are in the [OpenAPI schema](https://api.onehealthatlas.org/openapi.json) and the generated [API reference](https://onehealthatlas.org/docs/api-reference). ## Collections and resources [#collections-and-resources] Canonical collections — indicators, measures, observations, and sources — return: ```json { "data": [], "meta": { "next_page_token": null, "response_at": "2026-01-01T00:00:00Z" }, "links": { "self": null } } ``` That JSON is the contract's illustrative empty page. A live indicators page also returned `links.self` null while `data` contained rows, so a null `self` does not mean the page failed. Canonical detail routes — one indicator, measure, source, or methodology — return `data`. Legacy county, state, score, and geometry routes use their own response schemas. Read the operation you called. ## Pagination [#pagination] Collection `page_size` defaults to 100. The minimum is 1 and the maximum is 500. `page_size=0` on the observations query returned HTTP 400 `INVALID_REQUEST` with an `errors` entry that the value must be greater than or equal to 1. `meta.next_page_token` is an opaque string bound to the query and the release. Send it back as `page_token` and keep the other query parameters unchanged. `null` means the collection is exhausted. Tokens can expire on restart. A page token is not a citation and not a release id. Checked on 12 October 2026, `GET /v1/indicators?page_size=2` returned two indicators and a token. Repeating `page_size=2` with that `page_token` returned the next two indicators. Stop when `next_page_token` is null. Checked on 18 October 2026, `GET /v1/observations` with `measure_id` `nclimgrid_tavg_county_day`, `geography_type` `county`, `geography_id` `36061`, `year` 2025, and `page_size` 2 returned two rows, for 2025-01-01 and 2025-01-02, and a `next_page_token`. Repeating those parameters with that token as `page_token` returned 2025-01-03 and 2025-01-04 for the same measure, county, and year. Sending `page_token` alone returned HTTP 400 `INVALID_REQUEST` and detail `One or more request values are invalid.` because `measure_id`, `geography_type`, and `geography_id` were missing. The same token with those three filters and no year returned HTTP 400 `INVALID_REQUEST` and detail `Supply a year or both start_date and end_date.` The client tabs below use the same persisted choice as the quickstart. Copy `meta.next_page_token` into `page_token` and send the original filters again. The token is opaque. Do not invent one. #### curl ``` url='https://api.onehealthatlas.org/v1/observations?measure_id=nclimgrid_tavg_county_day&geography_type=county&geography_id=36061&year=2025&page_size=2' first=$(curl -fsS "$url") token=$(printf '%s' "$first" | python3 -c 'import json,sys,urllib.parse; token=json.load(sys.stdin)["meta"]["next_page_token"]; print("" if token is None else urllib.parse.quote(token, safe=""))') if [ -n "$token" ]; then curl -fsS "$url&page_token=$token" fi ``` #### Python ``` import httpx filters = { "measure_id": "nclimgrid_tavg_county_day", "geography_type": "county", "geography_id": "36061", "year": "2025", "page_size": "2", } with httpx.Client(timeout=30.0) as client: first = client.get("https://api.onehealthatlas.org/v1/observations", params=filters) first.raise_for_status() token = first.json()["meta"]["next_page_token"] if token is not None: continued = client.get( "https://api.onehealthatlas.org/v1/observations", params={**filters, "page_token": token}, ) continued.raise_for_status() page = continued.json() ``` #### R ``` library(httr2) filters <- list( measure_id = "nclimgrid_tavg_county_day", geography_type = "county", geography_id = "36061", year = "2025", page_size = "2" ) first <- request("https://api.onehealthatlas.org/v1/observations") |> req_url_query(!!!filters) |> req_timeout(30) |> req_perform() token <- resp_body_json(first)$meta$next_page_token if (!is.null(token)) { continued <- request("https://api.onehealthatlas.org/v1/observations") |> req_url_query(!!!filters, page_token = token) |> req_timeout(30) |> req_perform() page <- resp_body_json(continued) } ``` #### TypeScript ``` function readNextPageToken(body: unknown): string | null { if (typeof body !== "object" || body === null || !("meta" in body)) { throw new Error("Atlas response is missing meta"); } const { meta } = body; if (typeof meta !== "object" || meta === null || !("next_page_token" in meta)) { throw new Error("Atlas response is missing next_page_token"); } const { next_page_token: nextPageToken } = meta; if (nextPageToken === null) { return null; } if (typeof nextPageToken !== "string") { throw new Error("Atlas next_page_token is not a string"); } return nextPageToken; } const endpoint = "https://api.onehealthatlas.org/v1/observations"; const filters: [string, string][] = [ ["measure_id", "nclimgrid_tavg_county_day"], ["geography_type", "county"], ["geography_id", "36061"], ["year", "2025"], ["page_size", "2"], ]; function atlasUrl(pageToken?: string): URL { const url = new URL(endpoint); for (const [name, value] of filters) { url.searchParams.append(name, value); } if (pageToken !== undefined) { url.searchParams.append("page_token", pageToken); } return url; } const firstResponse = await fetch(atlasUrl()); if (!firstResponse.ok) { throw new Error(`Atlas HTTP ${firstResponse.status}`); } const token = readNextPageToken(await firstResponse.json()); if (token !== null) { const continuedResponse = await fetch(atlasUrl(token)); if (!continuedResponse.ok) { throw new Error(`Atlas HTTP ${continuedResponse.status}`); } const page: unknown = await continuedResponse.json(); } ``` ## Rate limits [#rate-limits] `429` and `503` responses declare a `Retry-After` header. The header description is "Seconds before retry when supplied by the service." The illustrative `429` problem uses `code` `RATE_LIMITED`. The public OpenAPI document does not publish a numeric quota, a concurrency cap, or a fixed `Retry-After` range. When the header is present, wait that many seconds before retrying the same request. When you contact support, keep `request_id`. ## Errors [#errors] Canonical errors use RFC 9457 `application/problem+json`. Required problem fields are `type`, `title`, `status`, `detail`, `instance`, and `request_id`. `code` and `errors` may be present. `errors` is an array of objects when validation details are included. | HTTP status | `code` | When it applies | | ----------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `INVALID_REQUEST` | The query is incomplete or a value fails validation | | 400 | `UNSUPPORTED_FILTER` | The query contains a filter V1 does not accept, including unknown parameters, `sort`, and `aggregation` | | 400 | `UNSUPPORTED_STRATIFICATION` | `stratification` is sent. The current release has no strata | | 400 | `QUERY_TOO_BROAD` | The contract rejects the query as too broad. The public overview states a default pre-execution logical-result ceiling of 10,000, and that ceiling is not truncation | | 404 | `RESOURCE_NOT_FOUND` | The canonical resource id is unknown | | 413 | `INVALID_REQUEST` | A GET request includes a body. Canonical routes reject that body | | 414 | `INVALID_REQUEST` | The query string is too long | | 429 | `RATE_LIMITED` | The service asks you to wait. Read `Retry-After` | | 503 | Declared on the geography route as `CANONICAL_DATA_UNAVAILABLE` | The canonical data service is unavailable. Read `Retry-After` when it is present | Legacy Atlas routes keep their existing statuses, including `422` for invalid values and `404` for a missing county or dataset release. A checked `GET /v1/counties/00000` returned HTTP 404 `application/problem+json` with detail `County or dataset release not found` and no `code` field. Do not require `code` on every problem body. ## Versions [#versions] Keep these identifiers separate: | Identifier | Where it appears | What it names | | ---------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `/v1` | URL path | HTTP contract. Breaking public changes require an approved migration and deprecation plan. Optional additive fields may appear within V1 | | OpenAPI `info.version` | The schema document | Application version of the published document. It is not the HTTP contract | | `semantic_version` | Indicator, measure, observation, source, methodology | Governed semantic contract version | | `release_id` | Observation | Governed release identity for the row you retrieved | | `release_version` | Indicator, measure, source, methodology | Governed current-release relationship version | | `methodology_version` | Observation | Transformation version | | Methodology `version` | Methodology resource | Methodology resource version. It is distinct from `methodology_version` on the observation | These routes read the current release. The same URL can return a different `release_id` after a later release. Save the response, or a checksum of the response, with the request URL when you need a stable record. ## Caching [#caching] Discovery collections declare `Cache-Control: public, max-age=60, must-revalidate`. A checked indicators response used that policy. Supported detail resources return an `ETag`. Send `If-None-Match` with that value to receive HTTP 304 and an empty body when the representation is unchanged. `GET /v1/sources/human` behaved that way. Legacy metadata describes a public cache of 300 seconds and an informational `ETag` that does not implement conditional `304`. Read the operation. `meta.response_at` is the time the response was built. It is not publisher freshness. # OpenAPI, GitHub, and support (https://onehealthatlas.org/docs/develop/support) > Open the public Atlas contract, the GitHub repositories that own it, and the fields to include when you ask for help. These guides explain how to call the public API. The contract itself stays in the owning service. ## OpenAPI [#openapi] | Surface | Status | URL | | -------------------------------- | ------------------------------------ | ----------------------------------------------------------- | | Production API | Available | `https://api.onehealthatlas.org` | | OpenAPI schema | Available | [openapi.json](https://api.onehealthatlas.org/openapi.json) | | Swagger reference | Available | [Swagger reference](https://api.onehealthatlas.org/docs) | | ReDoc reference | Available | [ReDoc reference](https://api.onehealthatlas.org/redoc) | | Generated reference in this site | Rendered from the pinned public spec | [API reference](https://onehealthatlas.org/docs/api-reference) | The generated section uses these paths: | Path | Contents | | ------------------------------------------------ | -------------------------------------------------------- | | [API reference](https://onehealthatlas.org/docs/api-reference) | Document version, source commit, and the operation index | | [Discovery](https://onehealthatlas.org/docs/api-reference/discovery) | Indicators and measures | | [Observations](https://onehealthatlas.org/docs/api-reference/observations) | Observation query | | [Provenance](https://onehealthatlas.org/docs/api-reference/provenance) | Sources and methodologies | | [Geographies](https://onehealthatlas.org/docs/api-reference/geographies) | Geography identity | | [Atlas](https://onehealthatlas.org/docs/api-reference/atlas) | Legacy metadata, scores, geometry, and ranking export | | [Counties](https://onehealthatlas.org/docs/api-reference/counties) | Legacy county analytics and reports | | [States](https://onehealthatlas.org/docs/api-reference/states) | Legacy state review and reports | | [Schemas](https://onehealthatlas.org/docs/api-reference/schemas) | Component schemas, including `ProblemDetails` | Use those pages for parameters, schemas, and the contract's own examples. Use [the developer overview](https://onehealthatlas.org/docs/develop) when you need the task and the meaning of a field. ## Machine-readable docs [#machine-readable-docs] These files are generated from the current documentation source for this deployment. They are not a second copy of the OpenAPI contract. The API reference pages cite the pinned public spec and link the raw schema. | File | Contents | | ------------------------------------------------- | ---------------------------------------- | | [llms.txt](https://onehealthatlas.org/llms.txt) | Index of the current documentation pages | | [llms-full.txt](https://onehealthatlas.org/llms-full.txt) | Every current page in one Markdown file | | [This page as Markdown](https://onehealthatlas.org/docs/develop/support.md) | Processed Markdown for this page | | [This page as MDX](https://onehealthatlas.org/docs/develop/support.mdx) | Current MDX source for this page | Add md to the end of a documentation page URL for processed Markdown. Add mdx for the MDX source. The docs index is [docs.md](https://onehealthatlas.org/docs.md) and [docs.mdx](https://onehealthatlas.org/docs.mdx). `/v1` is the HTTP contract. OpenAPI `info.version` is the application version. They are different identifiers. ## GitHub [#github] | Repository | What it owns | | ---------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | [one-health-lyme-gap-atlas-api](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-api) | The public HTTP contract and `openapi.json` | | [one-health-lyme-gap-atlas-web](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-web) | This documentation site and the Atlas web application | | [one-health-lyme-gap-atlas-mcp](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp) | The MCP server. It is not required for public REST reads | Contract questions belong with the API repository. Guide wording belongs with the web repository. [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access) records the current MCP boundary: bounded anonymous read-only evidence tools, with county identity kept separate from evidence. [MCP clients](https://onehealthatlas.org/docs/develop/mcp-clients) has the production Streamable HTTP recipes. The September 2026 smoke-only receipt is historical. ## Support [#support] Include these items when you report a failed or surprising read: * The full request URL, without an Authorization header. Public reads do not use one. * The HTTP status and `content-type`. * `request_id` from the problem body. * `Retry-After` when the status is `429` or `503`. * For a successful observation, `measure_id`, `geography_id`, period, `value_state`, `release_id`, and `semantic_version`. There is no API key to rotate and no SDK version to report. ## Unavailable in this contract [#unavailable-in-this-contract] | Item | Status | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Numeric rate-limit quota and concurrency cap | Not published in the public OpenAPI document. Honor `Retry-After` | | Geography identity payload | Declared route currently returns `503` `CANONICAL_DATA_UNAVAILABLE` and no geometry. Polygons are `GET /v1/atlas/geometry` | | Daily environmental measure id | Present on 18 October 2026. The checked id is `nclimgrid_tavg_county_day`. Read `environmental_context` when that observation includes it. See [Observation queries](https://onehealthatlas.org/docs/develop/observation-queries) | | API keys, required SDKs, and required MCP tools | Not part of anonymous public reads | | Account, feedback, conversational AI, and literature retrieval | Excluded from the public OpenAPI document | # Tier 1 availability (https://onehealthatlas.org/docs/develop/tier1-availability) > Choose the Tier 1 availability read or the persisted priority read, and keep sufficient, insufficient, abstention, no published model, and an unknown FIPS apart. Two county routes expose the same persisted Tier 1 batch. `GET /v1/counties/{fips}/tier1-surveillance-priority/availability` tells you whether the five-digit FIPS is in the current geography release and whether a model result was published. `GET /v1/counties/{fips}/tier1-surveillance-priority` returns that persisted result alone. This is surveillance review priority, not Lyme disease risk, predicted incidence, probability, clinical risk, or diagnosis. `LOW` is a scored tier. `INSUFFICIENT` is an input-data sufficiency state, not a statement that disease is absent. A null score is not zero, and a missing result is not low priority. The bodies below were retrieved from `https://api.onehealthatlas.org` on 18 October 2026. Parameter tables stay in the [priority reference](https://onehealthatlas.org/docs/api-reference/counties#county_tier1_surveillance_priority_get) and the [availability reference](https://onehealthatlas.org/docs/api-reference/counties#county_tier1_surveillance_priority_availability_get). Reviewers reading a screen, rather than a response, should use [Evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty). ## When to call each route [#when-to-call-each-route] | You need | Call | What a completed read means | | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Membership in the current geography release, and whether a model result was published | `GET /v1/counties/{fips}/tier1-surveillance-priority/availability` | HTTP 200. `AVAILABLE` carries the persisted object in `data`. `UNAVAILABLE` with `NO_PUBLISHED_MODEL` carries `data` null. HTTP 404 means the five-digit FIPS is outside the release | | Only the persisted object, after you already know the county is supported | `GET /v1/counties/{fips}/tier1-surveillance-priority` | HTTP 200 and the priority object. HTTP 404 means no current result was returned. That 404 does not say whether the FIPS failed the geography check | Start with availability when the FIPS comes from outside Atlas, from a user, or from an older county list. Connecticut county codes such as `09001` are five digits and still fail the current release, because the release uses planning-region ids such as `09110`. Use the priority route when you are rendering a result you already located and you only need that object. Both operations declare HTTP 422 for a malformed FIPS, HTTP 429 with `Retry-After` when the service asks you to wait, and HTTP 503 when the read cannot be completed. A 503 is a failed read. It is not `UNAVAILABLE`, and it is not a tier. ## Availability envelope [#availability-envelope] A successful availability response is HTTP 200 `application/json`. Checked responses sent `Cache-Control: public, max-age=60`. The required fields are `availability`, `geography_release_id`, `reason`, and `data`. `geography_release_id` is the geography release that accepted the FIPS. `data.release_id` is the governed source release of the model batch. On this check they differed. Do not treat them as one release. `generated_at_utc` is the batch time. It is not the request time and not the observation date. `priority_percentile` is the within-batch position among scored counties for `prediction_batch_version`. It is not a probability, and it does not compare to another batch. `raw_model_score` is the model-native score. It is not incidence and not a probability. `limitation_ref` is the returned limitation identifier. It is not a docs URL on this site. ## AVAILABLE and sufficient [#available-and-sufficient] `GET /v1/counties/09110/tier1-surveillance-priority/availability` returned HTTP 200 for Capitol Planning Region, Connecticut. ```json { "availability": "AVAILABLE", "geography_release_id": "governed-2026-10-15-january-climate-prod", "reason": null, "data": { "county_fips": "09110", "priority_tier": "HIGH", "priority_percentile": 98.56824689786828, "raw_model_score": 2.0739835966635036, "evidence_sufficiency": "SUFFICIENT", "model_version": "tier1-statistical-reference-v1", "release_id": "governed-2026-09-18-unknown-coverage", "source_commit": "024bbbf74a7da8e54566bd60e8e762d85a51e24f", "prediction_batch_version": "tier1-review-priority-5536b5caad95cf47", "tier_policy_version": "tier1-review-percentile-v1", "generated_at_utc": "2026-10-07T02:14:24Z", "reasons": [ { "code": "PUBLISHED_HUMAN_FLOOR", "text": "Published county-linked human count-floor signal is present; its magnitude is a lower bound." }, { "code": "PATHOGEN_PRESENT", "text": "Publisher reports pathogen Present." } ], "limitation_ref": "docs/contracts/tier1-persisted-output-v1.md" } } ``` | Field | How to read this body | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `availability` | `AVAILABLE`. A persisted result is in `data` | | `reason` | Null. `NO_PUBLISHED_MODEL` is not used when `data` is present | | `geography_release_id` | Geography release that accepted `09110` | | `data.evidence_sufficiency` | `SUFFICIENT`. Selected scoring inputs were sufficient for this contract. That is not calibrated confidence and not clinical certainty | | `data.priority_tier` | `HIGH` under `tier_policy_version`. High review priority is not a disease-risk class | | `data.priority_percentile` and `data.raw_model_score` | Both present, as the contract requires for `SUFFICIENT` and for `INSUFFICIENT` | | `data.reasons` | Returned reason text, at most three objects. The human floor text says the magnitude is a lower bound | The same county on the priority route returned the `data` object and no envelope. The batch fields matched this body. ## AVAILABLE and insufficient [#available-and-insufficient] `GET /v1/counties/01001/tier1-surveillance-priority/availability` returned HTTP 200 for Autauga County, Alabama. The batch identifiers match the sufficient example. The sufficiency state and the tier do not. ```json { "availability": "AVAILABLE", "geography_release_id": "governed-2026-10-15-january-climate-prod", "reason": null, "data": { "county_fips": "01001", "priority_tier": "LOW", "priority_percentile": 30.734966592427615, "raw_model_score": 0.6000441944790827, "evidence_sufficiency": "INSUFFICIENT", "model_version": "tier1-statistical-reference-v1", "release_id": "governed-2026-09-18-unknown-coverage", "source_commit": "024bbbf74a7da8e54566bd60e8e762d85a51e24f", "prediction_batch_version": "tier1-review-priority-5536b5caad95cf47", "tier_policy_version": "tier1-review-percentile-v1", "generated_at_utc": "2026-10-07T02:14:24Z", "reasons": [ { "code": "NO_COUNTY_HUMAN_RECORD", "text": "No county-linked human record is available; the model uses an explicit placeholder." }, { "code": "PATHOGEN_NO_RECORDS", "text": "Publisher reports No records; this is not evidence of absence." } ], "limitation_ref": "docs/contracts/tier1-persisted-output-v1.md" } } ``` | Field | How to read this body | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `availability` and `reason` | Still `AVAILABLE` and null. Insufficient evidence is a published result, not a missing model | | `data.evidence_sufficiency` | `INSUFFICIENT`. The contract still requires `priority_tier`, `priority_percentile`, and `raw_model_score` | | `data.priority_tier` | `LOW`. A low tier is a scored review priority. It is not a safe county and not a zero | | `data.reasons` | The human reason says the model uses a placeholder because no county-linked human record is available. The pathogen reason says no records are not evidence of absence | `GET /v1/counties/01001/tier1-surveillance-priority` returned the inner object only. Checked field for field, it was the same object as `data` above. ```json { "county_fips": "01001", "priority_tier": "LOW", "priority_percentile": 30.734966592427615, "raw_model_score": 0.6000441944790827, "evidence_sufficiency": "INSUFFICIENT", "model_version": "tier1-statistical-reference-v1", "release_id": "governed-2026-09-18-unknown-coverage", "source_commit": "024bbbf74a7da8e54566bd60e8e762d85a51e24f", "prediction_batch_version": "tier1-review-priority-5536b5caad95cf47", "tier_policy_version": "tier1-review-percentile-v1", "generated_at_utc": "2026-10-07T02:14:24Z", "reasons": [ { "code": "NO_COUNTY_HUMAN_RECORD", "text": "No county-linked human record is available; the model uses an explicit placeholder." }, { "code": "PATHOGEN_NO_RECORDS", "text": "Publisher reports No records; this is not evidence of absence." } ], "limitation_ref": "docs/contracts/tier1-persisted-output-v1.md" } ``` ## NOT\_ESTIMABLE abstention [#not_estimable-abstention] `NOT_ESTIMABLE` is a persisted result. It is not `UNAVAILABLE`, and it is not HTTP 404. The published schema requires `availability` `AVAILABLE`, `reason` null, and a `data` object whose `evidence_sufficiency` is `NOT_ESTIMABLE`. On that object, `priority_tier`, `priority_percentile`, and `raw_model_score` are null. `SUFFICIENT` and `INSUFFICIENT` are invalid if any of those three is null. `NOT_ESTIMABLE` is invalid if any of them is present. There is no retrieved abstention payload from this check. On 18 October 2026, `GET /v1/atlas/scores` returned 3,144 counties. This was a national API inventory, not the lower-48-and-DC scope used by these guides. Retain that geography scope when selecting counties; `AVAILABLE` reports a persisted result, not product-scope eligibility. [Geography](https://onehealthatlas.org/docs/develop/geography) states that scope. The scores release id was the same value as `geography_release_id` in the bodies above. Availability for every FIPS in that national inventory returned HTTP 200, `AVAILABLE`, and `reason` null. Of those reads, 651 were `SUFFICIENT` (315 `HIGH` and 336 `MEDIUM`) and 2,493 were `INSUFFICIENT` (292 `MEDIUM` and 2,201 `LOW`). None was `NOT_ESTIMABLE`. Those counts describe this batch. They are not limits on which tier can accompany which sufficiency state. When a later batch returns an abstention, say that the batch did not assign a tier. Do not substitute `LOW`, zero, or "no disease." Keep `model_version`, `release_id`, `prediction_batch_version`, `tier_policy_version`, `generated_at_utc`, and `limitation_ref` from that `data` object. ## UNAVAILABLE and NO\_PUBLISHED\_MODEL [#unavailable-and-no_published_model] `UNAVAILABLE` is a successful determination. The operation returns HTTP 200 after the geography release and the Tier 1 projection have both been read. `reason` is `NO_PUBLISHED_MODEL`, and `data` is null. `geography_release_id` is still present, because the FIPS was accepted. The route does not turn null into zero and does not synthesize a model object. That state is distinct from `NOT_ESTIMABLE`, which is a published `data` object, and from HTTP 404, which means the FIPS was not in the geography release. It is also distinct from HTTP 503, which means the read failed. There is no retrieved `NO_PUBLISHED_MODEL` payload from this check. The same national inventory of 3,144 counties returned no `UNAVAILABLE` body. Do not invent a county to illustrate it. Branch on the four required fields when a later batch returns them, and describe the gap as no published model result. A null `data` value is not low priority. ## Five-digit FIPS outside the release [#five-digit-fips-outside-the-release] `GET /v1/counties/99999/tier1-surveillance-priority/availability` returned HTTP 404 `application/problem+json`. The checked response used a private cache directive. `99999` is five digits, and it is not in the current geography release. The same status and detail were returned for `00000` and for `09001`. ```json { "type": "https://onehealthatlas.org/problems/resource-not-found", "title": "Invalid public query", "status": 404, "detail": "County is not in the current geography release.", "instance": "/v1/counties/99999/tier1-surveillance-priority/availability", "request_id": "91af7989-a353-48e6-af9b-812727c66747", "code": "RESOURCE_NOT_FOUND", "errors": null } ``` | Field | How to read this problem | | ------------------- | ---------------------------------------------------------------------------- | | `status` and `code` | HTTP 404 and `RESOURCE_NOT_FOUND` | | `detail` | The county is not in the current geography release. This is not a model tier | | `instance` | The availability path that was requested | | `request_id` | Identifier for this response. A later call returns a different one | | `errors` | Null on this body. A validation failure can supply an array instead | A path that is not five digits does not reach that geography check. `GET /v1/counties/0911/tier1-surveillance-priority/availability` returned HTTP 422. The problem `detail` was `One or more request values are invalid.` The `errors` array named a string pattern mismatch on `fips` and required five digits. Preserve leading zeros. Send `09110`, not `9110`. The priority route does not answer this geography question. `GET /v1/counties/99999/tier1-surveillance-priority` also returned HTTP 404, with a different problem body and no `code`: ```json { "type": "https://onehealthatlas.org/problems/http-404", "title": "Not found", "status": 404, "detail": "No current Tier 1 county result", "instance": "/v1/counties/99999/tier1-surveillance-priority", "request_id": "c57750de-fca5-4ed2-8bbb-2d45f422cf97", "errors": null } ``` The operation description also uses HTTP 404 when a county has no persisted result. The checked unknown FIPS produced the detail above, and this check did not observe a published county with no model result. Do not read that priority 404 as proof the FIPS failed the geography release, and do not read it as `LOW`. Call availability when you need that distinction. ## States that must stay apart [#states-that-must-stay-apart] | Observed or declared state | Say this | Do not say this | | ------------------------------------------ | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | `AVAILABLE`, `SUFFICIENT`, `HIGH` | The batch assigned a high surveillance review priority and recorded sufficient inputs | The county is high risk, or the percentile is a probability | | `AVAILABLE`, `INSUFFICIENT`, `LOW` | The batch assigned a low review tier and recorded insufficient inputs. The tier was still returned | The county is safe, the placeholder is zero, or no pathogen records means absence | | `AVAILABLE` and `NOT_ESTIMABLE` | The batch abstained. Tier, percentile, and score are null | Abstention is low priority, or abstention means no disease | | `UNAVAILABLE` and `NO_PUBLISHED_MODEL` | The FIPS is in the geography release and no model result is published | Null data is zero, or the county has a low tier | | Availability HTTP 404 `RESOURCE_NOT_FOUND` | This five-digit FIPS is not in the current geography release | The county has no Lyme activity | | Priority HTTP 404 | No current Tier 1 result was returned for that path | The geography check failed, or the county is low priority | | HTTP 422 | The path is not a five-digit FIPS | The county was looked up and found missing | | HTTP 503 | The read failed. Retry with `Retry-After` when it is present, and keep `request_id` | The failure is an evidence tier | # Workflow guides (https://onehealthatlas.org/docs/develop/workflows) > Query one county, compare counties, read environmental context, choose a county PDF template, and cite the observation you actually received. 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. The client tabs share the quickstart choice: curl, Python httpx, R httr2, or TypeScript fetch. ## Query a county [#query-a-county] Goal: retrieve the current-release case-count floor for one county and year. #### curl ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=case_count_floor_2023&geography_type=county&geography_id=36061&year=2023' ``` #### Python ``` import httpx response = httpx.get( "https://api.onehealthatlas.org/v1/observations", params={ "measure_id": "case_count_floor_2023", "geography_type": "county", "geography_id": "36061", "year": "2023", }, timeout=30.0, ) response.raise_for_status() body = response.json() ``` #### R ``` library(httr2) observations <- request("https://api.onehealthatlas.org/v1/observations") |> req_url_query( measure_id = "case_count_floor_2023", geography_type = "county", geography_id = "36061", year = "2023" ) |> req_timeout(30) |> req_perform() observations_body <- resp_body_json(observations) ``` #### TypeScript ``` const url = new URL("https://api.onehealthatlas.org/v1/observations"); url.searchParams.append("measure_id", "case_count_floor_2023"); url.searchParams.append("geography_type", "county"); url.searchParams.append("geography_id", "36061"); url.searchParams.append("year", "2023"); const response = await fetch(url); if (!response.ok) { throw new Error(`Atlas HTTP ${response.status}`); } const body: unknown = await response.json(); ``` Then open `source_id` and `methodology_id` from that body. The checked release used: #### curl ``` curl -fsS 'https://api.onehealthatlas.org/v1/sources/human' curl -fsS 'https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1' ``` #### Python ``` import httpx with httpx.Client(timeout=30.0) as client: human = client.get( "https://api.onehealthatlas.org/v1/sources/human", ) human.raise_for_status() human_body = human.json() human_confirmed_probable_case_floor_v1 = client.get( "https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1", ) human_confirmed_probable_case_floor_v1.raise_for_status() human_confirmed_probable_case_floor_v1_body = human_confirmed_probable_case_floor_v1.json() ``` #### R ``` library(httr2) human <- request("https://api.onehealthatlas.org/v1/sources/human") |> req_timeout(30) |> req_perform() human_body <- resp_body_json(human) human_confirmed_probable_case_floor_v1 <- request("https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1") |> req_timeout(30) |> req_perform() human_confirmed_probable_case_floor_v1_body <- resp_body_json(human_confirmed_probable_case_floor_v1) ``` #### TypeScript ``` const humanUrl = new URL("https://api.onehealthatlas.org/v1/sources/human"); const humanResponse = await fetch(humanUrl); if (!humanResponse.ok) { throw new Error(`Atlas HTTP ${humanResponse.status}`); } const humanBody: unknown = await humanResponse.json(); const human_confirmed_probable_case_floor_v1Url = new URL("https://api.onehealthatlas.org/v1/methodologies/human_confirmed_probable_case_floor_v1"); const human_confirmed_probable_case_floor_v1Response = await fetch(human_confirmed_probable_case_floor_v1Url); if (!human_confirmed_probable_case_floor_v1Response.ok) { throw new Error(`Atlas HTTP ${human_confirmed_probable_case_floor_v1Response.status}`); } const human_confirmed_probable_case_floor_v1Body: unknown = await human_confirmed_probable_case_floor_v1Response.json(); ``` 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 [#compare-geographies] Goal: retrieve the same measure and period for two counties in one request. Repeat `geography_id`. #### curl ``` 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' ``` #### Python ``` import httpx response = httpx.get( "https://api.onehealthatlas.org/v1/observations", params={ "measure_id": "case_count_floor_2023", "geography_type": "county", "geography_id": ["08001", "36061"], "year": "2023", }, timeout=30.0, ) response.raise_for_status() body = response.json() ``` #### R ``` library(httr2) observations <- request("https://api.onehealthatlas.org/v1/observations") |> req_url_query( measure_id = "case_count_floor_2023", geography_type = "county", geography_id = c("08001", "36061"), year = "2023", .multi = "explode" ) |> req_timeout(30) |> req_perform() observations_body <- resp_body_json(observations) ``` #### TypeScript ``` const url = new URL("https://api.onehealthatlas.org/v1/observations"); url.searchParams.append("measure_id", "case_count_floor_2023"); url.searchParams.append("geography_type", "county"); url.searchParams.append("geography_id", "08001"); url.searchParams.append("geography_id", "36061"); url.searchParams.append("year", "2023"); const response = await fetch(url); if (!response.ok) { throw new Error(`Atlas HTTP ${response.status}`); } const body: unknown = await response.json(); ``` 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 [#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. On 12 October 2026, `GET /v1/measures` returned 21 measures and a null `next_page_token`, and none of those ids was a daily weather measure. On 18 October 2026 the catalog includes the January 2025 daily measures. The checked request, and the parameters that request rejects, are in [Observation queries](https://onehealthatlas.org/docs/develop/observation-queries). Do not invent a measure id that discovery did not return. 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 ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=nlcd_forest_area_share_county_year&geography_type=county&geography_id=09110&year=2025' ``` #### Python ``` import httpx response = httpx.get( "https://api.onehealthatlas.org/v1/observations", params={ "measure_id": "nlcd_forest_area_share_county_year", "geography_type": "county", "geography_id": "09110", "year": "2025", }, timeout=30.0, ) response.raise_for_status() body = response.json() ``` #### R ``` library(httr2) observations <- request("https://api.onehealthatlas.org/v1/observations") |> req_url_query( measure_id = "nlcd_forest_area_share_county_year", geography_type = "county", geography_id = "09110", year = "2025" ) |> req_timeout(30) |> req_perform() observations_body <- resp_body_json(observations) ``` #### TypeScript ``` const url = new URL("https://api.onehealthatlas.org/v1/observations"); url.searchParams.append("measure_id", "nlcd_forest_area_share_county_year"); url.searchParams.append("geography_type", "county"); url.searchParams.append("geography_id", "09110"); url.searchParams.append("year", "2025"); const response = await fetch(url); if (!response.ok) { throw new Error(`Atlas HTTP ${response.status}`); } const body: unknown = await response.json(); ``` 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 ``` curl -fsS 'https://api.onehealthatlas.org/v1/observations?measure_id=nlcd_forest_area_share_county_year&geography_type=county&geography_id=08001&year=2025' ``` #### Python ``` import httpx response = httpx.get( "https://api.onehealthatlas.org/v1/observations", params={ "measure_id": "nlcd_forest_area_share_county_year", "geography_type": "county", "geography_id": "08001", "year": "2025", }, timeout=30.0, ) response.raise_for_status() body = response.json() ``` #### R ``` library(httr2) observations <- request("https://api.onehealthatlas.org/v1/observations") |> req_url_query( measure_id = "nlcd_forest_area_share_county_year", geography_type = "county", geography_id = "08001", year = "2025" ) |> req_timeout(30) |> req_perform() observations_body <- resp_body_json(observations) ``` #### TypeScript ``` const url = new URL("https://api.onehealthatlas.org/v1/observations"); url.searchParams.append("measure_id", "nlcd_forest_area_share_county_year"); url.searchParams.append("geography_type", "county"); url.searchParams.append("geography_id", "08001"); url.searchParams.append("year", "2025"); const response = await fetch(url); if (!response.ok) { throw new Error(`Atlas HTTP ${response.status}`); } const body: unknown = await response.json(); ``` 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 [#reproduce-and-cite-an-observation] Goal: store enough of one response to explain the number later, after the current release has moved on. Annotated null rules, limitations, and the discover, observe, and resolve order are in [Provenance and evidence](https://onehealthatlas.org/docs/develop/provenance#cite-from-discovery). 1. Save the request URL. 2. Save the observation fields in [Provenance and evidence](https://onehealthatlas.org/docs/develop/provenance), 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 | ## Download a county report [#download-a-county-report] Goal: download one county PDF with the selector that matches the report you need. The route is `GET /v1/counties/{fips}/report.pdf`. `template` defaults to `county-v1`. Use a county FIPS in the lower 48 states or the District of Columbia. Checked for FIPS `11001`: HTTP `200`. A scoring PDF is a review-priority report. An evidence PDF repeats canonical observations, lineage, value states, and limitations. Neither report is a diagnosis, an individual risk estimate, or a causal claim. Parameter tables stay in the [county report reference](https://onehealthatlas.org/docs/api-reference/counties#county_report_pdf_v1_counties__fips__report_pdf_get). ### county-v1 scoring `county-v1` is the scoring selector. `dataset_version` is optional. These score settings are optional and bind the scoring inputs: | Parameter | Default | Bounds | | -------------------------- | ------- | -------------------- | | `ecological_share` | 65 | 40–85, multiple of 5 | | `low_incidence_breakpoint` | 10 | 5–25 | | `missing_human_weakness` | 75 | 40–90, multiple of 5 | `period_start`, `period_end`, and `measure_id` are forbidden on `county-v1`. Sending one of them returns HTTP `422` and `application/problem+json`. Checked on 18 October 2026 for FIPS `36061` with an observation period: ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "Observation context requires county-v2.", "instance": "/v1/counties/36061/report.pdf", "request_id": "example-request-id", "errors": null } ``` An unknown template that still matches the operation's template pattern returns HTTP `422` with detail `The requested county report template is not available.` A template outside that pattern returns HTTP `422` with detail `One or more request values are invalid.` A successful county-v1 response is `application/pdf` and uses `Cache-Control: public, max-age=300, must-revalidate`. `ETag` with `If-None-Match` can return `304`. #### curl ``` curl -fsS 'https://api.onehealthatlas.org/v1/counties/36061/report.pdf?template=county-v1' ``` #### Python ``` import httpx response = httpx.get( "https://api.onehealthatlas.org/v1/counties/36061/report.pdf", params={ "template": "county-v1", }, timeout=30.0, ) response.raise_for_status() payload = response.content ``` #### R ``` library(httr2) report_pdf <- request("https://api.onehealthatlas.org/v1/counties/36061/report.pdf") |> req_url_query( template = "county-v1" ) |> req_timeout(30) |> req_perform() report_pdf_body <- resp_body_raw(report_pdf) ``` #### TypeScript ``` const url = new URL("https://api.onehealthatlas.org/v1/counties/36061/report.pdf"); url.searchParams.append("template", "county-v1"); const response = await fetch(url); if (!response.ok) { throw new Error(`Atlas HTTP ${response.status}`); } const body: ArrayBuffer = await response.arrayBuffer(); ``` ### county-v2 evidence `county-v2` is the evidence selector. It requires `dataset_version`, `period_start`, `period_end`, and `measure_id`. Pass the observation `release_id` as `dataset_version`. `period_start` and `period_end` are the exact inclusive dates. `measure_id` accepts 1–20 distinct ids, repeated or comma-separated. A missing release, period, or measure list, a duplicate measure id, more than 20 ids, or a reversed period returns HTTP `422`. Checked on 18 October 2026: ```json { "type": "https://onehealthatlas.org/problems/http-422", "title": "Request failed", "status": 422, "detail": "county-v2 requires release, exact period and distinct measures.", "instance": "/v1/counties/36061/report.pdf", "request_id": "example-request-id", "errors": null } ``` A `dataset_version` the service cannot resolve returns HTTP `404` with detail `County or dataset release not found`. An unknown measure returns HTTP `404` `RESOURCE_NOT_FOUND` with detail `Measure has no published county observations.` The contract also returns HTTP `503` when provenance is missing or mismatched, and HTTP `413` when the report exceeds resource limits. Score settings are the county-v1 inputs above. A checked county-v2 request that also sent `ecological_share=65` still returned HTTP `200` and `Cache-Control: no-store`. A successful county-v2 response uses `Cache-Control: no-store`. The service revalidates authoritative context before a cache response or `304`. `ETag` is still present. Replace the release id in this checked URL with the observation `release_id` you are citing: #### curl ``` curl -fsS 'https://api.onehealthatlas.org/v1/counties/36061/report.pdf?template=county-v2&dataset_version=governed-2026-10-15-january-climate-prod&period_start=2023-01-01&period_end=2023-12-31&measure_id=case_count_floor_2023' ``` #### Python ``` import httpx response = httpx.get( "https://api.onehealthatlas.org/v1/counties/36061/report.pdf", params={ "template": "county-v2", "dataset_version": "governed-2026-10-15-january-climate-prod", "period_start": "2023-01-01", "period_end": "2023-12-31", "measure_id": "case_count_floor_2023", }, timeout=30.0, ) response.raise_for_status() payload = response.content ``` #### R ``` library(httr2) report_pdf <- request("https://api.onehealthatlas.org/v1/counties/36061/report.pdf") |> req_url_query( template = "county-v2", dataset_version = "governed-2026-10-15-january-climate-prod", period_start = "2023-01-01", period_end = "2023-12-31", measure_id = "case_count_floor_2023" ) |> req_timeout(30) |> req_perform() report_pdf_body <- resp_body_raw(report_pdf) ``` #### TypeScript ``` const url = new URL("https://api.onehealthatlas.org/v1/counties/36061/report.pdf"); url.searchParams.append("template", "county-v2"); url.searchParams.append("dataset_version", "governed-2026-10-15-january-climate-prod"); url.searchParams.append("period_start", "2023-01-01"); url.searchParams.append("period_end", "2023-12-31"); url.searchParams.append("measure_id", "case_count_floor_2023"); const response = await fetch(url); if (!response.ok) { throw new Error(`Atlas HTTP ${response.status}`); } const body: ArrayBuffer = await response.arrayBuffer(); ``` The published documentation home for these guides is [https://onehealthatlas.org/docs](https://onehealthatlas.org/docs). # Evidence, provenance, and uncertainty (https://onehealthatlas.org/docs/evidence-and-uncertainty) > Learn how to read Atlas Lyme signals, distinguish missing evidence from low observed signal, and decide what remains unknown. Atlas Lyme is designed to help epidemiologists identify areas where available tick/vector and related One Health evidence may warrant review. A signal is the beginning of an investigation question—not a finding that a place is definitively high risk. ## What an Atlas output means [#what-an-atlas-output-means] Use these terms consistently when reading a result: | Term | Meaning | How to use it | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Observed signal** | A value or status reported by an approved source, such as a published county-linked human-surveillance value, tick status, or pathogen detection status. | Describe what the source reported, including its geography and time or vintage. | | **Derived measure** | A value calculated from released inputs, such as a county review score or evidence-completeness percentage. | Use it to focus review. It is not a diagnosis, a complete disease-burden estimate, a confidence interval, or individual risk. | | **Contextual evidence** | Information that helps interpret a result, such as population, access, rurality, habitat, climate, or scientific context. | Treat context as relevant background with its own source, coverage, geography, vintage, and limitations. | | **Modeled output** | An estimate, forecast, classification, or other result produced by a model rather than directly published as an observation. | Require the model version, inputs, validation, uncertainty, and human review before relying on it. The current public explorer does not promise an authoritative modeled outbreak or individual-risk output. | | **Investigation candidate** | A geography or pattern selected for a bounded follow-up question because the available evidence or an evidence gap merits review. | State what should be checked next and what evidence could change the interpretation. | [Atlas Explorer](https://onehealthatlas.org/explore) labels the county review score and evidence completeness as analytical signals. The active release is shown in the application; [current capabilities](https://onehealthatlas.org/docs/current-capabilities) describes the release boundary. ## Start with provenance [#start-with-provenance] Before interpreting a signal, locate and record: * **Source and publisher:** who produced or published the input, and what link or citation identifies it; * **Release and vintage:** the active Atlas release and the source observation, reporting, or publication period; * **Geography:** county, state, sampling location, boundary definition, and any records not allocated to a county; * **Method and version:** the methodology, calculation, or model version used to produce the displayed value; * **Freshness and processing context:** source retrieval, release generation, and data load times when the application provides them; and * **Limitations:** coverage, sample size, representativeness, missingness, suppression, comparability, uncertainty, and known data-quality constraints. The evidence snapshot on [Atlas Explorer](https://onehealthatlas.org/explore) summarizes source periods, scoring methodology, and release processing times in plain language, with exact IDs behind **Inspect provenance**. County evidence adds county-level source context when it is available. Use that page before sharing or acting on a result. A generated date describes the release; it is not necessarily the date of disease observations. See [Releases and methodology labels](https://onehealthatlas.org/docs/releases-and-methodology) for definitions of each label. The list above is the provenance to record for evidence in the current open-data release. Atlas is also designed so a later governed source can be normalized into the same evidence concepts. That normalization keeps the original source and publisher, dataset version or vintage, geography, observation period, transformation, and limitations on the result. A shared model does not make two sources equivalent. Missing, suppressed, unavailable, and uncertain inputs stay visible as the states in the next section. [Sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence) separates that architectural intent from the sources released today. ## Read value states carefully [#read-value-states-carefully] These states answer different questions and must not be collapsed into one another: | State | What it can mean | What you should say | | ----------------------------------- | ---------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | **Observed or published** | A source published a value or status for the stated geography and period. | “This source reports…” and include the source context. | | **Zero** | The source explicitly reported zero for the stated measure and period. | “The published value is zero for this release.” A zero is still bounded by source coverage and method. | | **Missing or no record** | No county-linked row or value is available in the release. | “No county record is available.” Do not call this absence. | | **Suppressed or privacy-protected** | A publisher withheld or transformed a value to protect privacy or meet a reporting rule. | Describe the protection and do not reconstruct a precise count. | | **Unavailable or not reported** | The source, field, geography, or period is not available for this release. | Treat it as an evidence gap, not as zero or no activity. | | **Stale** | The source vintage or retrieval is too old for the question being asked. | Confirm the current source and state the time limitation. | | **Sparse or incomplete** | Coverage, sampling, reporting, or scored inputs are limited. | State what the available records can and cannot support. | | **Disagreement** | Two sources or signals point in different directions. | Preserve both observations, compare their provenance, and make the disagreement the investigation question. | Atlas Explorer uses “No records,” “Unavailable,” and completeness indicators in context. “No records” describes published evidence availability; it does not establish that ticks, pathogens, or disease are absent. The signed-in workspace uses three labels after a successful response: **Available**, **Limited**, and **Unavailable**. Available includes a published zero. Limited means a signal exists and a documented constraint should change how you read it. Unavailable means the governed value is absent or out of scope, and the page shows that word rather than zero. A spinner or a failed request is a loading or error state. It is not the Unavailable evidence label. **Inspect provenance** on a workspace value opens source family, period, and technical identifiers without leaving the page. The deeper interpretation stays in this guide. See [the professional workspace](https://onehealthatlas.org/docs/professional-workspace). ## Low signal is not the same as insufficient surveillance [#low-signal-is-not-the-same-as-insufficient-surveillance] A low observed signal means that a source reported a low value or status under its method and coverage. **Insufficient surveillance** means the available evidence is too incomplete, unrepresentative, outdated, or incomparable to determine whether the underlying activity is low. For example, a county with no county-linked published Lyme case record may have zero cases, suppressed records, unallocated records, a reporting boundary mismatch, or another publication limitation. Atlas does not treat that missing record as zero by default. Likewise, a tick table with no county record does not prove ticks are absent. When evidence is incomplete, use the safer statement: “The current release does not establish this.” Then identify the source or coverage check needed to learn more. ## Why signals may not agree [#why-signals-may-not-agree] One Health inputs can differ in: * collection design and sample size; * geographic boundaries and whether records are allocated to counties; * observation, reporting, and publication periods; * publisher, laboratory, field, or case definitions; * coverage and representativeness of the sampled population or habitat; and * missingness, suppression, processing, and update schedules. Those differences can produce apparent agreement or disagreement without proving that one source caused another or that either source represents every person, tick, or location. Compare provenance first; do not average away a disagreement or describe it as certainty. ## Read the evidence before acting [#read-the-evidence-before-acting] Use this checklist for a county, comparison, or other review candidate: 1. **Name the question.** What decision or follow-up are you trying to inform? 2. **Name the output.** Is it an observed signal, derived measure, contextual input, modeled output, or investigation candidate? 3. **Check the provenance.** Source, publisher, release, vintage, geography, method/version, freshness, and processing context. 4. **Check the value state.** Observed, zero, missing, suppressed, unavailable, stale, sparse, or conflicting? 5. **Check comparability.** Do the geographies, periods, definitions, coverage, and methods support the comparison? 6. **State what remains unknown.** What cannot be concluded from this release? 7. **Choose a bounded next step.** Source validation, local surveillance review, a time-bounded analysis, expert consultation, or no action. 8. **Record the handoff.** Save the URL, release, method, filters, evidence context, question, reviewer, and caveats using the [investigation workflows](https://onehealthatlas.org/docs/investigation-workflows). [Atlas Explorer](https://onehealthatlas.org/explore) provides the map and the county list for the same release. If map geometry is unavailable or a map is not usable, use the county list and text summaries. For AI-enabled or experimental experiences, keep the [AI Ethics commitments](https://onehealthatlas.org/ai-ethics) in view and retain human review. Atlas helps identify what may deserve investigation. It does not provide clinical advice, person-level exposure or disease-risk predictions, causal proof, guaranteed outbreak forecasts, or an automatic public-health decision. # FAQ and troubleshooting (https://onehealthatlas.org/docs/faq-and-troubleshooting) > Get practical answers about Atlas Lyme interpretation, loading, filters, data availability, and the public HelpDocs experience. ## Product and interpretation [#product-and-interpretation] ### What is Atlas Lyme? [#what-is-atlas-lyme] Atlas is an **Epidemiologist Decision Intelligence Platform** for Lyme disease and other tick-borne diseases. It brings fragmented One Health evidence together to help epidemiologists understand what is happening, investigate why, and decide what deserves review. Start with [What is Atlas Lyme?](https://onehealthatlas.org/docs/what-is-atlas), then sign in and open [Atlas Explorer](https://onehealthatlas.org/explore). ### Is the current Atlas score an AI prediction? [#is-the-current-atlas-score-an-ai-prediction] No. The current score is a transparent, adjustable follow-up-priority calculation over released inputs. It is not a predictive model, diagnosis, disease-burden estimate, causal conclusion, or individual-risk prediction. Use [current capabilities](https://onehealthatlas.org/docs/current-capabilities) and [evidence guidance](https://onehealthatlas.org/docs/evidence-and-uncertainty) when interpreting it. ### Does Atlas connect to an electronic health record or a clinical laboratory? [#does-atlas-connect-to-an-electronic-health-record-or-a-clinical-laboratory] No. The current release is open public data. Atlas is designed so a future governed source can be adapted into the same evidence model. That design is not a live EHR connection, a TEFCA connection, patient-level data, or a production clinical-laboratory feed. Read [sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence). ### Does a high score mean that a county is high risk? [#does-a-high-score-mean-that-a-county-is-high-risk] No. It means the released inputs or evidence gaps made the county a candidate for closer review under the displayed methodology. Check the source, vintage, geography, method, completeness, limitations, and uncertainty before deciding what to investigate. ### Why does Atlas show a signal when evidence is missing? [#why-does-atlas-show-a-signal-when-evidence-is-missing] Missing evidence can be part of the reason a question deserves review, but missing is not zero and no record is not absence. A low observed value and insufficient surveillance are different states. Read [evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty) before drawing a conclusion. ### Can Atlas tell me whether an outbreak will happen? [#can-atlas-tell-me-whether-an-outbreak-will-happen] No. Atlas does not guarantee outbreak prediction, causation, individual risk, diagnosis, or automatic public-health action. It helps identify a bounded investigation question. ### What does “AI-enabled” mean today? [#what-does-ai-enabled-mean-today] It describes the product direction: organizing, comparing, synthesizing, or explaining governed evidence with clear sources and limits. The current public score is deterministic. When literature chat is enabled, `/assistant` calls the model-backed literature service on the Atlas API and returns cited evidence. That route is not a local demo. When the feature is off, the assistant reports that the service is unavailable. See [AI-enabled decision intelligence](https://onehealthatlas.org/docs/ai-enabled-decision-intelligence) and the approved [AI Ethics commitments](https://onehealthatlas.org/ai-ethics). ## Using Atlas [#using-atlas] ### The Atlas is loading or says it is temporarily unavailable. What should I do? [#the-atlas-is-loading-or-says-it-is-temporarily-unavailable-what-should-i-do] The public application retrieves the current governed release through the public API. Use **Try again** or refresh once. If the problem continues, record the time, route, and any displayed release or request reference, then return later. Do not treat a loading or error state as evidence about a county. ### No counties match my filters. Did Atlas find no risk? [#no-counties-match-my-filters-did-atlas-find-no-risk] No. The current filters may simply exclude every county. Review the selected state, county name or FIPS search, evidence filter, view, and score controls, then use **Clear filters** if needed. An empty result set is not a public-health conclusion. ### The map is unavailable or difficult to use. Can I still review results? [#the-map-is-unavailable-or-difficult-to-use-can-i-still-review-results] Yes. In [Atlas Explorer](https://onehealthatlas.org/explore), use the county list and the text summaries. The list remains available when the map is not, and a map error says the list is still the non-map path. ### How do I compare counties? [#how-do-i-compare-counties] In [Compare](https://onehealthatlas.org/compare), choose two counties from the same release. [Atlas Explorer](https://onehealthatlas.org/explore) can also open Compare for the county on screen. The comparison is descriptive; document why the counties were selected and do not treat differences as causation or individual risk. Atlas does not offer a five-county comparison page. ### Why is a county’s case value not shown as zero? [#why-is-a-countys-case-value-not-shown-as-zero] The source may have no county-linked record, may have suppressed or unallocated records, or may not report that geography or period. Atlas preserves that distinction rather than converting missing evidence into zero. An explicitly published zero is still bounded by the source and method. ### Why can two signals point in different directions? [#why-can-two-signals-point-in-different-directions] Human, tick, pathogen, environmental, population, and scientific sources can use different boundaries, definitions, sampling designs, periods, publishers, and update schedules. Compare provenance and coverage first; make the disagreement a question for review. Do not average away the difference. ### How do I share what I reviewed? [#how-do-i-share-what-i-reviewed] Use the supported URL handoff or export, and record the active release, methodology version, geography, filters, view, metric, score assumptions, evidence context, limitations, and follow-up question. A URL preserves supported analytical state, but it does not guarantee that a future release will contain identical data. ## HelpDocs and policy [#helpdocs-and-policy] ### How do I find the right documentation page? [#how-do-i-find-the-right-documentation-page] Open the [Atlas documentation home](https://onehealthatlas.org/docs), use the sidebar or search, and choose the page that matches your question: [current capabilities](https://onehealthatlas.org/docs/current-capabilities), [the professional workspace](https://onehealthatlas.org/docs/professional-workspace), [investigation workflows](https://onehealthatlas.org/docs/investigation-workflows), [evidence guidance](https://onehealthatlas.org/docs/evidence-and-uncertainty), or [sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence). **Docs** in the public utility bar and **Docs** in the professional workspace both open this site in a new tab. The analytical page, including its URL, stays in the original tab. A heading link can be reloaded in the documentation tab without changing that workspace tab. ### I am in the professional workspace. Which page should I use? [#i-am-in-the-professional-workspace-which-page-should-i-use] Use [Atlas Explorer](https://onehealthatlas.org/explore) for a national or state picture, county evidence, and suggested follow-up. Use [Compare](https://onehealthatlas.org/compare) for two counties. [Ask Atlas](https://onehealthatlas.org/askatlas) asks reviewed-literature questions when that service is enabled. Saved chats stay in this browser. The request is a message plus optional conversation history. There is no Structured mode and no Both mode. Feed is in the navigation and does not yet list items. Settings saves a default jurisdiction and optional profile details. Older bookmarks open Atlas Explorer after sign-in. See [the professional workspace](https://onehealthatlas.org/docs/professional-workspace). ### Can I create an API key in Settings? [#can-i-create-an-api-key-in-settings] No. Public API reads do not use an API key, and Settings does not generate one. Use [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access), the [developer quickstart](https://onehealthatlas.org/docs/develop/quickstart), and the [OpenAPI schema](https://api.onehealthatlas.org/openapi.json). Production MCP can read bounded public evidence without an API key. The September 2026 smoke-only development receipt is historical. That service is not a live EHR connection. ### Why did my default jurisdiction not change the Review page I already had open? [#why-did-my-default-jurisdiction-not-change-the-review-page-i-already-had-open] A saved United States or state default applies the next time Atlas Explorer opens without `scope` or `county` in the address. An open address that already names a scope or county stays as it is. You can still browse other states and counties. Optional role, organization, and job title can stay empty. ### Where are privacy and AI policy commitments documented? [#where-are-privacy-and-ai-policy-commitments-documented] Use the approved [Privacy page](https://onehealthatlas.org/privacy) for privacy and data-use commitments and [AI Ethics commitments](https://onehealthatlas.org/ai-ethics) for AI status, boundaries, and open decisions. HelpDocs links to those sources and does not replace or expand them. ### Can HelpDocs change a data value or score? [#can-helpdocs-change-a-data-value-or-score] No. HelpDocs explains the released experience; it does not edit source data, change methodology, or authorize an interpretation. Validate a concern against the source and responsible local or state program, and preserve the release and method in your review record. ### What if an AI or analytical explanation conflicts with the evidence panel? [#what-if-an-ai-or-analytical-explanation-conflicts-with-the-evidence-panel] Pause the interpretation. Prefer the governed source and in-product provenance context, record the disagreement, and ask a qualified reviewer to validate it. Treat an unsupported or unavailable explanation as unavailable—not as a reason to fill the gap with confidence. Keep the [AI Ethics commitments](https://onehealthatlas.org/ai-ethics) in view. # Investigation workflows (https://onehealthatlas.org/docs/investigation-workflows) > Use Atlas Lyme to move from a surveillance question to a bounded, evidence-backed investigation next step. Atlas is most useful when it helps turn a broad question into a reviewable next step. The workflows below use the signed-in workspace and keep the evidence checks close to the decision. [Atlas Explorer](https://onehealthatlas.org/explore) holds the operating picture, county evidence, and suggested follow-up. [Compare](https://onehealthatlas.org/compare) holds two counties. The [professional workspace](https://onehealthatlas.org/docs/professional-workspace) guide lists all six destinations. For a capability-by-capability view, see [current capabilities](https://onehealthatlas.org/docs/current-capabilities). For the product's overall model, see [the Atlas decision-support workflow](https://onehealthatlas.org/docs/atlas-workflow). ## 1. Find a geography or signal for review [#1-find-a-geography-or-signal-for-review] **Question:** Where should our team look first, given the available release? 1. Sign in and open [Atlas Explorer](https://onehealthatlas.org/explore). 2. Choose the United States or one state, or select a county by name or FIPS code. 3. Read the map and the county list together. Open county evidence for one county. Suggested follow-up is on that same page. 4. If a map is difficult to use or geometry is unavailable, use the county list and text summaries. The list is the supported non-map path. 5. Record the release, methodology version, geography, and the evidence context that made the signal worth reviewing. **Evidence check:** A rank or score focuses attention. It does not mean that the county has the highest disease burden, that missing evidence means zero, or that a cause has been identified. **Next step:** Form a bounded question such as, “Which source and time period should we validate for this county?” Then use the evidence and methodology context before requesting follow-up analysis or local review. ## 2. Compare a county with surrounding or peer geographies [#2-compare-a-county-with-surrounding-or-peer-geographies] **Question:** Is this signal distinctive enough, or does it appear in other supported counties in the same release? 1. From Atlas Explorer, open [Compare](https://onehealthatlas.org/compare) for the county on screen, or choose the first county on Compare. 2. Choose the second county that is relevant to the review question, such as a nearby county or a documented peer. The page accepts two counties. 3. Review the side-by-side comparison and the source, release, method, and completeness context for both counties. 4. Keep the comparison within the same active release. If the release changes, confirm that both counties still match the question. 5. Record why each county was selected and which displayed signal or evidence difference merits follow-up. **Evidence check:** The comparison is descriptive. Differences in a score or displayed signal are not evidence of causation, a statistical test, or a person-level risk difference. Different reporting practices, geographies, vintages, and missingness can make apparent differences difficult to compare. **Next step:** Choose the smallest defensible follow-up—source validation, local surveillance review, a time-bounded analysis, or expert consultation—and state what evidence would change the interpretation. ## 3. Inspect evidence before deciding what to investigate next [#3-inspect-evidence-before-deciding-what-to-investigate-next] **Question:** What supports this result, and what remains uncertain? 1. Select the geography in [Atlas Explorer](https://onehealthatlas.org/explore) and open county evidence. 2. Open **source, release, and methodology context** in the selected-county evidence panel, and read the relevant methods section in the application. 3. Check the source or publisher, source time or vintage, geography and boundary, active release, methodology version, generated and loaded or retrieved context, completeness, known limitations, and any uncertainty language. 4. Distinguish “no record available” from “zero.” Look for the fields that are present, the fields that are missing, and whether the inputs are comparable before drawing a conclusion. 5. Write the investigation question and the evidence gap together. For example: “The county is a review candidate in release X; validate the human-disease source vintage and vector coverage before interpreting the signal.” **Evidence check:** Atlas combines measures that can have different publishers, schedules, years, and scales. A result is only as interpretable as the provenance and limitations that accompany it. **Next step:** Ask a qualified reviewer to validate the source context and local meaning, then decide whether the question warrants additional analysis, field investigation, coordination, or no action. ## Record and share the review [#record-and-share-the-review] When you share an Atlas result, keep a small review record: * the URL and the date you opened it; * the active release identifier and methodology version; * the selected state, county, or county set; * the view, metric, filters, page, and score assumptions used; * the source, geography, time or vintage, freshness, completeness, uncertainty, and limitations you observed; and * the follow-up question, reviewer, and decision about what happens next. The URL is a useful handoff because it preserves supported analytical state. It is not a substitute for recording the release and evidence context, and it should not be described as reproducing a future result after the underlying release changes. ## In-product help [#in-product-help] * Use [Atlas Explorer](https://onehealthatlas.org/explore) for the county list, county evidence, suggested follow-up, and the county PDF when Atlas can verify it. * Use [Compare](https://onehealthatlas.org/compare) for two counties. The county list remains the non-map path when the map is unavailable. * Keep the [AI Ethics commitments](https://onehealthatlas.org/ai-ethics) nearby when reviewing any AI-enabled or experimental experience. * Return to [current capabilities](https://onehealthatlas.org/docs/current-capabilities) when you need to distinguish a released behavior from a planned or experimental one. Atlas helps identify what may deserve investigation. The epidemiologist and responsible public-health organization remain accountable for interpretation, validation, and action. # Professional workspace (https://onehealthatlas.org/docs/professional-workspace) > Use the signed-in workspace for Atlas Explorer, Compare, Ask Atlas, Feed, Data Provenance, Settings, and Docs. The professional workspace is the signed-in Atlas experience. It has seven destinations: **Atlas Explorer**, **Compare**, **Ask Atlas**, **Feed**, **Data Provenance**, **Settings**, and **Docs**. Atlas Explorer is the map, the county list, expandable county evidence, and suggested follow-up on one address. Compare and Ask Atlas stay dedicated pages. There is no separate Review, Explore, Investigate, or Action destination, and Ask Atlas does not open a side panel. Sign-in is required. A signed-out visit to a workspace address goes to sign-in and comes back to the address you asked for. An older bookmark is then opened as the matching Atlas Explorer state. Reading these docs does not require a sign-in. Use [current capabilities](https://onehealthatlas.org/docs/current-capabilities) for what is released, planned, or experimental. ## Open Docs from the workspace [#open-docs-from-the-workspace] **Docs** is in the workspace navigation. It opens this documentation site in a new browser tab. The workspace tab keeps the page and URL you already had, including supported geography, release, and compare context. Docs always opens at the documentation home. It does not change with the page you were on, and it does not add field-level help inside Atlas Explorer or Compare. Search and the sidebar are how you move through this reference. A heading link stays on that heading after you reload the documentation tab. To resume the review, return to the original workspace tab. Its address still has the context you had before you opened Docs. ## Workspace destinations [#workspace-destinations] | Destination | Address | Status | What you can do | | --------------- | ------------------------------------ | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | Atlas Explorer | [/explore](https://onehealthatlas.org/explore) | Available now | See a national or one-state picture, with the map and county list together. Open county evidence or suggested follow-up on that same address. | | Compare | [/compare](https://onehealthatlas.org/compare) | Available now | Compare two counties on aligned measures. Availability stays visible. The page does not rank a winner. | | Ask Atlas | [/askatlas](https://onehealthatlas.org/askatlas) | Experimental | Ask reviewed-literature questions when that service is enabled. A validated Explorer or Compare reference can be shown and changed, with a return link. | | Feed | [/app/feed](https://onehealthatlas.org/app/feed) | Present, empty | The destination is in the navigation. It does not yet list items, alerts, or a saved-article library. | | Data Provenance | [/data-provenance](https://onehealthatlas.org/data-provenance) | Available now | Read where the current release's evidence comes from, open a source card, and follow Docs for methodology. Provenance beside a result stays on that result. | | Settings | [/app/settings](https://onehealthatlas.org/app/settings) | Available now | Save a default jurisdiction and optional profile details, then use account sign-out, export, and removal. | | Docs | [/docs](https://onehealthatlas.org/docs) | Available now | Open this reference in a new tab from the workspace navigation. | `/app/review`, `/app/compare`, and `/app/assistant` permanently open `/explore`, `/compare`, and `/askatlas`. Supported details on those addresses stay. Older addresses such as `/overview`, `/geographic_explorer`, `/investigate`, `/app/explore`, `/app/investigate`, and `/app/action` are not extra destinations. After sign-in they open Atlas Explorer. A valid county on an old investigation address opens county evidence. A valid county on an old action address opens suggested follow-up. An address with no county opens that scope's picture. On a state picture, Atlas Explorer then selects the first published review candidate and writes that county into the address. An address that names a county which does not validate opens with `selection=required` and does not substitute another county. One saved evidence-brief address, `plan=evidence-brief` on `/app/action`, still opens that brief. It is not a navigation destination. **Return to county evidence** goes back to Atlas Explorer with the county, scope, release, and period that brief was using. Surveillance planning is not a released workflow. The workspace footer links to the public [Privacy page](https://onehealthatlas.org/privacy) and to [AI / Responsible Use](https://onehealthatlas.org/app/ai-responsible-use). AI / Responsible Use explains capability maturity for signed-in readers. It does not replace this guide. Evidence labels stay separate from those maturity labels. ## How context travels [#how-context-travels] Workspace pages share a small set of URL details so a direct link or reload can show the same review: * **scope** — United States or one state; * **county** — one five-digit county FIPS code; * **compare** — up to two county FIPS codes; * **dataset** — the governed release id when the page has one; * **period** — a calendar date when the page supports a period; * **mode** — on Atlas Explorer only. Omitted means the map and list. `evidence` opens county evidence. `follow-up` opens suggested follow-up for that county. Atlas Explorer, Compare, and Ask Atlas keep the details that destination accepts. A validated compare pair stays with the county. It is not dropped when you open county evidence. Feed, Data Provenance, and Settings do not carry this context. Docs does not receive it, because the original workspace tab keeps it. List sort and page position stay on Atlas Explorer browse. They are not copied into county evidence or Compare. ## Atlas Explorer [#atlas-explorer] Atlas Explorer answers where you are looking, whether anything warrants attention, how complete the evidence is, and what to inspect next. * Choose **United States** or one state. National scope orients you by state and a bounded county set. It is not a ranking of every U.S. county. * The map and the county list describe the same release. Use the list when the map is unavailable. * A review-priority signal focuses follow-up. It is not a diagnosis, a disease-burden estimate, or an individual risk. * **View county evidence** expands that county on this address. **Back to map** returns to the map and list. **Compare this county** opens Compare. **Ask Atlas** opens the dedicated Ask Atlas page. * **Suggested follow-up** is a section of the same county view. It reads the review result for that county. It does not start an intervention. A saved default jurisdiction applies only when Atlas Explorer opens without `scope` or `county` in the address. An address that already names a scope or county stays on that place. Changing the default does not rewrite a page you already have open, and it does not hide other states or counties. ### Loading, empty, unavailable, and error [#loading-empty-unavailable-and-error] These are different states. Do not read one as another. * **Loading** means the request has not finished. A loading message is not an evidence label and not a score. * **Empty** means the release returned no row for that question. An empty county list, or a county with no suggested follow-up, says that nothing was returned. Atlas does not invent a county or a next step. * **Available** means governed inputs exist for the claim, including a published zero. * **Limited** means a signal exists, and coverage, suppression, sample size, staleness, or another documented limitation constrains how to read it. * **Unavailable** means the governed value is absent, invalid, or out of scope. Atlas shows Unavailable. It does not show that gap as zero. * **Unknown** stays unknown. An unknown observation period or evidence type is not inferred from a source date. * **Error** means the request failed. Retry does not turn that failure into Unavailable evidence. A failed refresh does not keep showing the previous facts as if they were current. ## Compare [#compare] Compare places two counties side by side. * Choose **First county** and **Second county**. The workspace accepts two counties. * Each measure row keeps that county's unit, period, and availability. Similar values, different values, and withheld comparisons are labeled. A withheld comparison explains why the values were not treated as a simple difference. * The page does not produce a winner, a combined score, or a rank. * **View first county evidence** and **View second county evidence** open that county in Atlas Explorer. **Ask Atlas about this comparison** opens Ask Atlas with the pair as a page reference, not as a request to compare the counties for you. * **Return to Atlas Explorer** or **Return to county evidence** appears when you opened Compare from that place. If the county list is still loading, the selectors say so. If the list fails, Compare says the published counties could not be loaded. If evidence fails, the page says aligned evidence did not load. Those messages are request states. ## Settings [#settings] Settings at [/app/settings](https://onehealthatlas.org/app/settings) stores a profile for future Atlas Explorer sessions. * **Default jurisdiction** is **United States** or one state from the current Atlas state list. * **Role**, **organization**, and **job title** are optional. Leaving them empty does not block Atlas Explorer or the rest of the workspace. Role choices include preferring not to say, general public citizen, and district, state, state-director, and national epidemiologist roles. * **Save profile** confirms the default only after the account profile accepts the same values. If the save cannot be confirmed, the form keeps what you typed and says the save was not confirmed. * The note under the jurisdiction control states that saved defaults apply the next time Atlas Explorer opens without a scope in the URL. * **Sign out** ends this session. **Export** and **Remove all data** are the existing account data-rights actions. Privacy commitments stay on the [Privacy page](https://onehealthatlas.org/privacy). The workspace footer links to that same public page, links to [AI / Responsible Use](https://onehealthatlas.org/app/ai-responsible-use), and includes Privacy settings for the existing browser analytics choice. Opening Privacy leaves the signed-in workspace and does not ask you to sign in again. AI / Responsible Use stays inside the signed-in workspace. Settings does not generate, display, or revoke an API key. It does not manage saved comparisons, saved investigations, or alert subscriptions. Those controls are not in this release. API and MCP access are described in [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access). ## Ask Atlas [#ask-atlas] Atlas Explorer and Compare include an **Ask Atlas** control. It opens the [Ask Atlas page](https://onehealthatlas.org/askatlas). It does not open a side panel or a dialog. When reviewed-literature chat is enabled for that deployment, that page asks the literature service and shows cited evidence or an explicit unavailable-evidence outcome. Explorer and Compare can carry a validated page reference. That reference is labeled on the page, can be changed or cleared, and is not a citation or retrieved surveillance evidence. The return link restores Atlas Explorer or the Compare pair, including the relevant geography, period, and release. An address that does not verify is not shown as evidence. When literature chat is not enabled, the page says Ask Atlas is unavailable and the other workspace pages stay usable. That message is a service state. It does not mean the county's evidence is absent. Ask Atlas does not change filters or maps on its own, and it does not run a workflow for you. It has no Structured mode and no Both mode. Showing a comparison reference does not ask the service to compare counties. A direct link to a conversation that is not saved in this browser says so and lets you start a new chat. History stays in this browser for up to 30 days. It is not a saved research library on Atlas servers. The separate public workspace at [/assistant](https://onehealthatlas.org/assistant) remains available when that route is enabled. It is not the signed-in Ask Atlas page. See [AI-enabled decision intelligence](https://onehealthatlas.org/docs/ai-enabled-decision-intelligence). ## County PDF [#county-pdf] County evidence can offer a county PDF when published measures share one county, release, and observation period, and Atlas can verify that the file matches the county, observations, sources, period, and caveats on screen. If that check cannot be completed, the PDF is unavailable. That is not a statement that the report contains none of a period, and it is not a claim that the county has no evidence. A failed download stays an error and can be tried again. The file is not reused from an earlier attempt. ## Evidence labels [#evidence-labels] Workspace evidence uses three labels after a successful response: * **Available** — governed inputs exist for the claim, including a published zero. * **Limited** — a signal exists, and coverage, suppression, sample size, staleness, or another documented limitation constrains how to read it. * **Unavailable** — the governed value is absent, invalid, or out of scope. Atlas shows Unavailable. It does not show that gap as zero. Loading, empty results, unknown fields, and request failures use their own messages. Read [evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty) before treating a label as a conclusion. # Releases and methodology labels (https://onehealthatlas.org/docs/releases-and-methodology) > Plain-language definitions for Atlas release snapshots, source periods, processing times, and scoring methodology versions. Atlas shows a short **evidence snapshot** on [Atlas Explorer](https://onehealthatlas.org/explore) and [Compare](https://onehealthatlas.org/compare) before technical release identifiers. Technical identifiers sit inside **Inspect provenance**. Use this guide when you need to explain those labels to colleagues or the public. ## Release semantics [#release-semantics] | Label | What it means | | -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Evidence snapshot** | A summary of the active governed release: geography in scope, source periods, and the methodology version behind the county review score. | | **Selected release** | The governed county bundle you are viewing. The readable label may include when Atlas assembled the bundle; that is not a surveillance observation date. | | **Evidence scope** | Which counties or geographies this release includes or excludes, as documented in governed metadata. | | **Source periods** | Observation, reporting, or publication periods for each upstream source (for example, a surveillance table vintage). These describe public inputs—not when Atlas built or loaded the release. | | **Scoring methodology** | The versioned rules that combine released inputs into the county review score. Distinct from source periods and from release assembly time. | | **Release generated** | When Atlas finished building this governed bundle. A processing timestamp, not a case observation date. | | **Release loaded** | When this release became available through the public API the application reads. May differ from generation time. | | **Methodology version (technical ID)** | Stable identifier for scoring rules. Use it to confirm comparisons use the same methodology. When metadata is missing, the app shows **Unavailable** rather than inferring a version. | | **Release ID (technical ID)** | Stable identifier for the county bundle. Use it for reproducible links, exports, and support requests. | Open **Inspect provenance** on Atlas Explorer when you need exact IDs and timestamps. ## How county scoring works [#how-county-scoring-works] The county review score is a **derived follow-up-priority measure**. It highlights where published Lyme surveillance, tick and pathogen evidence, and selected contextual inputs may warrant review together. It is not a diagnosis, individual exposure estimate, proof of underreporting, or forecast of future cases. **Deterministic scoring methodology** applies fixed, inspectable rules to released inputs. **Semantic scoring methodology** follows the same transparency goals with a newer ruleset named in governed metadata. Compare counties within one active release and one methodology version. Keep three time concepts separate: 1. **Source periods** — what upstream publishers reported. 2. **Release generated / loaded** — how and when Atlas processed and delivered the bundle. 3. **Methodology version** — how inputs were combined into scores. If a value is absent or invalid, Atlas shows **Unavailable**. The application does not invent source retrieval dates or hide technical identifiers. For value states, missingness, and uncertainty language, continue with [Evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty). [Sources and canonical evidence](https://onehealthatlas.org/docs/sources-and-canonical-evidence) explains how a future governed source is intended to keep this same source period, method version, and provenance when it is normalized. # Sources and canonical evidence (https://onehealthatlas.org/docs/sources-and-canonical-evidence) > How Atlas is designed to adapt governed sources into one canonical evidence model for the Web product, REST API, and MCP, and which of that design is released. Public-health evidence arrives in different systems, formats, vintages, terminologies, geographies, and publication processes. Atlas is designed so a new governed source can be added without forcing epidemiologists, REST clients, or MCP clients to learn a separate data model for every source. The intended path is: `source system → source-specific adapter → terminology/semantic mapping → canonical Atlas evidence and provenance → REST API / MCP / product workflows` A shared model keeps provenance and uncertainty attached. It is not a claim that two sources measured the same thing, covered the same people or ticks, or can be compared without reading their limitations. ## What is released and what is intent [#what-is-released-and-what-is-intent] Use the same status labels as [current capabilities](https://onehealthatlas.org/docs/current-capabilities). | Capability | Status | What you can rely on | | ----------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Open public evidence in the current release, read through the public product and the public REST API | Available now | Observations, sources, and methodologies use the published `/v1` resources. Start with [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access), the generated [API reference](https://onehealthatlas.org/docs/api-reference), and [evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty). | | Source-specific adapters for additional governed sources, including CSV, XLSX, API, scientific-file, and other governed patterns | Planned | An adapter is written for that source. A file type or API shape is not, by itself, a released source. | | CDC Lyme/TBRD Message Mapping Guide (MMG) and PHIN VADS for surveillance concepts, where a governed mapping uses them | Planned | Selected direction for public-health surveillance semantics. Not evidence that every released source is already mapped, and not a certification. | | USCDI, FHIR R4 / US Core, Bulk FHIR, and LOINC for future authorized clinical or laboratory sources, where those standards apply to that source | Planned | Selected direction for future sources of that kind. Not a released clinical or laboratory feed. | | Live EHR connectivity, TEFCA, patient-level data, PHI, or production clinical-laboratory ingestion | Not supported | The current release does not include these connections. Naming a standard on this page does not grant access, legal authority, certification, or production connectivity. | | Bounded anonymous MCP evidence reads | Available now | Production MCP returns governed public evidence through `atlas_discover_indicators`, `atlas_get_county_profile`, and `atlas_get_evidence_provenance`. `atlas_resolve_geographies` resolves county identity and does not establish that evidence exists. Arguments and limits are in the [public evidence tool contract](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9/docs/public-evidence-tools.md). See [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access). | The current MVP is open-data-first. The public product shows the governed evidence in the current release, and each result still names its source. This page does not publish a second source catalog. `server_status` and `atlas_smoke_test` are not in the current production tool list. A call is an unknown-tool error. The September 2026 development receipt that covered smoke tools only is historical. Client setup is in [MCP clients](https://onehealthatlas.org/docs/develop/mcp-clients). [ADR 0003](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9/docs/adr/0003-public-evidence-tools.md) supersedes that exposure constraint for the bounded evidence tools above. Those tools are not a live EHR, TEFCA, patient-level, PHI, or production clinical-laboratory connection. ## Why this design matters [#why-this-design-matters] Epidemiologists should be able to read a new governed source with the same questions they already use: who published it, which dataset and vintage, which geography and period, which method, and which limitations. API and MCP consumers should be able to keep calling a stable evidence contract when a source is added, instead of binding each integration to that source's native tables. The common contract does not make sources interchangeable. A county value from one publisher can remain missing, suppressed, unavailable, or uncertain after it is normalized. Those states stay visible so a shared shape cannot be mistaken for equal coverage or equal confidence. ## How a source becomes Atlas evidence [#how-a-source-becomes-atlas-evidence] 1. **Source system.** The publisher's own system, file, or feed. Atlas does not require that system to look like today's open-data release. 2. **Source-specific adapter.** A governed adapter reads that source's pattern. Patterns the design allows include CSV, XLSX, an API, a scientific file, and other governed inputs. The adapter is not a universal parser, and it is not permission to collect the source. 3. **Terminology and semantic mapping.** Where a mapping applies, it translates source concepts into stable Atlas concepts. The mapping annotates source meaning. It does not erase the original source identity, version, or limitations. 4. **Canonical Atlas evidence and provenance.** Downstream readers receive governed Atlas observations, sources, and methodologies, with provenance still attached. 5. **REST API, MCP, and product workflows.** The Web product, REST clients, and MCP clients consume that canonical evidence where the public contract supports the abstraction. Transport format and source authorization are separate. A format describes how records are carried. Authorization describes whether Atlas may receive and publish them. Support for a format, or alignment with a named standard, is not access, legal authority, interoperability certification, or a live connection. Bulk FHIR is one example of that split. It is a possible authorized population-scale transport for a future clinical or laboratory source. It is not automatic authority, and it is not a connection Atlas operates today. ## What normalization preserves [#what-normalization-preserves] Heterogeneous source records are normalized into stable Atlas concepts and observations. The public contract does not expose a different downstream model for every source. These facts stay with the evidence: | Preserved fact | What it answers | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Source and publisher | Who produced or published the input | | Dataset, version, and vintage | Which release of that dataset the value came from | | Geography | Which governed county or state the value describes | | Observation period | The inclusive period and grain, distinct from when Atlas loaded the release | | Units and denominators | The measure's unit and any governed denominator. A missing denominator is not invented | | Transformation and method | The methodology and version that produced the Atlas value | | Missing, suppressed, unavailable, and uncertain meaning | Whether a number was published, withheld, absent, or too limited to treat as a confident result | | Quality and limitations | Coverage, comparability, and other governed limits | | Lineage and provenance | How the row traces back to the source record and the Atlas release | Field names and types for the current release are defined by the public OpenAPI contract. Read them in [Provenance and evidence](https://onehealthatlas.org/docs/develop/provenance), the generated [provenance reference](https://onehealthatlas.org/docs/api-reference/provenance), and the generated [schemas](https://onehealthatlas.org/docs/api-reference/schemas). This page does not copy those schemas. Product geography for the developer guides is the lower 48 states and the District of Columbia. See [Geography](https://onehealthatlas.org/docs/develop/geography). ## Missing, suppressed, unavailable, and uncertain [#missing-suppressed-unavailable-and-uncertain] Normalization keeps these states distinct. Do not collapse them into zero, and do not collapse them into one another. | State | What remains true after normalization | | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Observed** | The source published a value or status for the stated geography and period. The public code is `OBSERVED`. | | **Zero** | The source published a numeric zero. The public code is `ZERO`. Coverage and method still bound that zero. | | **Missing** | No governed value was published for that geography and period. The public code is `MISSING`. Missing is not zero and not biological absence. | | **Suppressed** | The publisher withheld the value, including for privacy or a reporting rule. The public code is `SUPPRESSED`. Do not reconstruct a precise count. | | **Unavailable** | The source, field, geography, or period is not available in this release. The public code is `UNAVAILABLE`. Unavailable is an evidence gap. | | **No county-linked record** | No county-linked row is in the release. The public code is `NO_COUNTY_LINKED_RECORD`. The contract treats this as not evidence of absence. | | **Uncertain** | A governed limitation, sparse or incomplete coverage, a stale vintage, or disagreement between sources limits how far the value can be read. Uncertainty stays attached as that limitation. It is not rewritten into a confident number, and it is not an extra public value-state code. | `MISSING`, `SUPPRESSED`, and `UNAVAILABLE` require a null value in the public contract. A null value is not zero. The signed-in workspace shows **Available**, **Limited**, and **Unavailable** after a successful response. **Suppressed** stays visible as suppression. Loading and request failures are not evidence states. The plain-language rules and the workspace labels are in [Evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty). The contract table, in enum order, is in [Indicators, measures, and observations](https://onehealthatlas.org/docs/develop/resources). Release time, source period, and methodology version stay separate in [Releases and methodology labels](https://onehealthatlas.org/docs/releases-and-methodology). ## Standards, where they apply [#standards-where-they-apply] These standards are selected directions for particular kinds of sources. They are not a universal data standard, and they are not a requirement that every Atlas source be FHIR. | Standard | Where it applies | What this page does not claim | | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | CDC Lyme/TBRD Message Mapping Guide (MMG) and the Public Health Information Network Vocabulary Access and Distribution System (PHIN VADS) | Public-health surveillance concepts, for a current or future source whose governed mapping uses them | That every released open-data source is mapped to the MMG, or that naming the MMG certifies the feed | | United States Core Data for Interoperability (USCDI) | A future clinical or laboratory data-element anchor | That clinical data elements are in the current release | | FHIR R4 and US Core | Future authorized clinical or laboratory resource semantics, when that source uses those resources | That every future source must be FHIR, or that Atlas has a live FHIR connection | | Bulk FHIR | A possible authorized population-scale transport | That transport is permission to access a source, or that a Bulk FHIR feed is operating | | LOINC (Logical Observation Identifiers Names and Codes) | Laboratory terminology for a source that already uses LOINC | That current open-data measures are LOINC-coded, or that a laboratory feed is in production | A standards mapping can sit beside the canonical observation as an annotation of source meaning. The observation still carries its own source, dataset, vintage, geography, period, method, value state, and limitations. ## What Web, REST, and MCP consume [#what-web-rest-and-mcp-consume] Where the public contract already presents canonical evidence, consumers are intended to use that governed contract rather than an arbitrary source-specific schema. | Consumer | Authority | Current boundary | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Web product | The released Atlas experience, reading governed evidence and showing provenance beside the result | Open public evidence in the current release. Inspect provenance on the result. The [professional workspace](https://onehealthatlas.org/docs/professional-workspace) and the public Explorer do not add a private clinical feed. | | REST API | The public OpenAPI document. The [API reference](https://onehealthatlas.org/docs/api-reference) is generated from the pinned public contract and links the raw [OpenAPI schema](https://api.onehealthatlas.org/openapi.json) | Anonymous current-release reads of indicators, measures, observations, sources, and methodologies. Legacy county and state analytics remain a separate route family, described in the [developer overview](https://onehealthatlas.org/docs/develop). | | MCP | The [public evidence tool contract](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp/blob/d26ef2b72a2f9203a26ff45a3ad13f0f2ac104c9/docs/public-evidence-tools.md) and its tests in the [Atlas MCP repository](https://github.com/Caraway-Labs/one-health-lyme-gap-atlas-mcp) | Available now for a bounded anonymous read-only surface. `atlas_discover_indicators`, `atlas_get_county_profile`, and `atlas_get_evidence_provenance` return canonical public evidence and provenance. `atlas_resolve_geographies` returns county identity only. A schema that changes with each source is outside this contract. | Semantic and provenance meaning stays with the observation, source, and methodology resources. This site does not maintain a second HTTP schema, a second MCP tool list, or a second semantic contract. ## Where to go next [#where-to-go-next] * [Evidence, provenance, and uncertainty](https://onehealthatlas.org/docs/evidence-and-uncertainty) — how to read a result, including missing evidence and low observed signal. * [Releases and methodology labels](https://onehealthatlas.org/docs/releases-and-methodology) — source period, release processing time, and methodology version. * [Provenance and evidence](https://onehealthatlas.org/docs/develop/provenance) — the fields to keep with a value when you cite an API response. * [API reference: provenance](https://onehealthatlas.org/docs/api-reference/provenance) — generated source and methodology operations. * [API reference: observations](https://onehealthatlas.org/docs/api-reference/observations) — the observation query. * [API, MCP, and access](https://onehealthatlas.org/docs/api-mcp-and-access) — what REST and MCP can do in this release. * [Current capabilities](https://onehealthatlas.org/docs/current-capabilities) — the broader release boundary for the product. # What is Atlas Lyme? (https://onehealthatlas.org/docs/what-is-atlas) > Learn what Atlas Lyme is, what it helps epidemiologists investigate, and where its evidence boundaries apply. Atlas Lyme is an **Epidemiologist Decision Intelligence Platform** for Lyme disease and other tick-borne diseases. It is an AI-enabled, disease-focused public-health platform that brings One Health evidence into a shared place so epidemiologists can recognize patterns, understand context, and decide what deserves investigation. The product vision is: > From fragmented surveillance data to timely, interpretable, evidence-backed public-health action. The North Star is: > A system that identifies what matters, explains why it matters, communicates uncertainty, and helps epidemiologists decide what deserves investigation. ## Why Atlas exists [#why-atlas-exists] Tick-borne disease questions rarely fit inside one dataset. Human disease observations, tick and vector measures, pathogen prevalence, climate, habitat, population context, and scientific evidence may be published by different organizations, on different schedules, at different geographic or time scales. Atlas connects those perspectives while keeping the context needed to interpret them. The goal is less manual joining and searching, earlier recognition of signals worth reviewing, and more defensible public-health conversations. ## What Atlas helps you do [#what-atlas-helps-you-do] Depending on the current release, Atlas can help you: * review geographic patterns and potential areas of concern; * bring human, ecological, environmental, pathogen, and population context into the same investigation; * inspect the evidence behind a signal, including source, release or time period, methodology, and limitations; * compare supported geographies or filter states that another reviewer can reproduce; and * turn a broad surveillance question into a smaller, evidence-backed investigation question. These are decision-support capabilities. Atlas helps organize evidence and focus attention; the epidemiologist remains responsible for interpretation, follow-up, and public-health action. ## What “AI-enabled” means here [#what-ai-enabled-means-here] AI-enabled describes the product direction: Atlas is being built to help people find relevant patterns, connect evidence, summarize context, and ask better follow-up questions. Any AI-assisted experience must remain grounded in approved evidence, show its sources and limitations, and preserve a human review step. The public application does not treat an AI output as an authoritative finding. A generated explanation or suggested investigation path is a prompt for review, not a diagnosis, causal conclusion, or automatic public-health decision. ## What Atlas is not [#what-atlas-is-not] Atlas is not: * a clinical diagnostic tool or a substitute for medical advice; * an individual exposure, infection, or disease-risk predictor; * a direct measure of disease burden merely because a place ranks highly; * proof that a vector, pathogen, environment, or population factor caused an outcome; * a guarantee that an outbreak will or will not occur; or * a replacement for epidemiologists, public-health analysts, local knowledge, or domain experts. The current release is an early public prototype and situational-awareness foundation. A visible signal means “review this question with the available evidence,” not “this place is definitively high risk” or “this place is safe.” ## A public, evidence-first platform [#a-public-evidence-first-platform] Atlas is designed to be useful without requiring an account to explore the public experience. A signed-in profile can store a default jurisdiction for the next Review session. That preference does not change evidence, scores, or which geographies you can open. Public results should be understandable through the map and an equivalent table or text path, with provenance and limitations kept close to the result. To begin, sign in and open [Atlas Explorer](https://onehealthatlas.org/explore). The [professional workspace](https://onehealthatlas.org/docs/professional-workspace) guide names the six destinations. Return to [the decision-support workflow](https://onehealthatlas.org/docs/atlas-workflow) when you want to understand how to review a result. # Who is Atlas for? (https://onehealthatlas.org/docs/who-is-atlas-for) > See which public-health users Atlas Lyme is designed to support and the questions it can help them investigate. Atlas is designed for people who need to move from a broad tick-borne disease surveillance question to a focused, evidence-backed investigation question. ## Primary users [#primary-users] Atlas is primarily for: * epidemiologists and disease-surveillance teams; * public-health analysts who need geographic and One Health context; * researchers investigating relationships among disease, vectors, pathogens, environment, and populations; and * public-health partners who need a common, reviewable starting point for discussion. The product is built around expert review. It does not assume that every user has the same data access, local knowledge, surveillance mandate, or decision authority. ## Questions Atlas can help frame [#questions-atlas-can-help-frame] Use Atlas to help ask: 1. **What is happening, and where?** Find geographic patterns or signals in the available release. 2. **What might help explain it?** Bring relevant vector, pathogen, environmental, population, or scientific context into view. 3. **How strong is the evidence?** Check source, vintage, geography, methodology, completeness, and known limitations. 4. **What deserves a closer look?** Identify an investigation candidate and record the evidence that motivated the question. Atlas is especially useful when several imperfect sources need to be reviewed together. It is less useful when the question requires a clinical diagnosis, a person-level risk assessment, or an answer that the available public data cannot support. ## A typical user session [#a-typical-user-session] A reviewer might: * choose a state or county in [Atlas Explorer](https://onehealthatlas.org/explore); * filter the county list by name, FIPS code, state, or available evidence; * review the ranked list, map, table, and selected-county detail together; * open the evidence and methodology context before interpreting a signal; * adjust supported score assumptions when the interface provides that control; * copy or export a review brief for a team conversation; and * share the URL so another reviewer can reproduce the supported geography and filter state. The exact controls and data coverage depend on the current release. See [current capabilities](https://onehealthatlas.org/docs/current-capabilities) for the status of each documented behavior. ## Who makes the decision? [#who-makes-the-decision] Atlas helps a human reviewer decide what merits investigation. The reviewer and their organization remain responsible for: * validating the source and context; * bringing local surveillance knowledge and other approved evidence; * deciding whether follow-up analysis, field work, or coordination is appropriate; and * communicating any public-health action through the responsible authority. A rank, score, map color, or AI-assisted explanation does not transfer that responsibility to Atlas. ## Access and trust boundaries [#access-and-trust-boundaries] The public Atlas experience is designed to remain usable without signing in. In the professional workspace, a saved default jurisdiction chooses the next Review start when the address has no scope. It does not unlock evidence, change a score, or limit which geographies you can open. For responsible use, pair every important result with its [evidence and provenance context](https://onehealthatlas.org/docs/index#start-with-provenance), and read [the AI Ethics commitments](https://onehealthatlas.org/ai-ethics) for the approved boundaries around AI-assisted experiences.