Atlas documentation
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

GET /v1/atlas/geometry

Operation ID: geometry_v1_atlas_geometry_get

Tag: atlas

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

  • Location: query
  • Required: no

Schema:

{
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "null"
    }
  ],
  "title": "Dataset Version"
}

Responses

200

Display GeoJSON, EPSG:4326; immutable TTL 31536000; ETag.

application/geo+json

Schema:

{
  "type": "object"
}

304

Matching If-None-Match; empty body.

This response does not declare a body.

404

County or dataset release not found.

application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-404",
  "title": "Request failed",
  "status": 404,
  "detail": "County or dataset release not found.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

422

One or more request values are invalid.

application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-422",
  "title": "Request failed",
  "status": 422,
  "detail": "One or more request values are invalid.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

429

Rate limit exceeded.

Headers
Retry-After
  • Required: no
  • Seconds before retry when supplied by the service.
  • Type: string

Schema:

{
  "type": "string"
}
application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-429",
  "title": "Request failed",
  "status": 429,
  "detail": "Rate limit exceeded.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

503

Atlas data service is unavailable.

Headers
Retry-After
  • Required: no
  • Seconds before retry when supplied by the service.
  • Type: string

Schema:

{
  "type": "string"
}
application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-503",
  "title": "Request failed",
  "status": 503,
  "detail": "Atlas data service is unavailable.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

Get Atlas release metadata

GET /v1/atlas/metadata

Operation ID: metadata_v1_atlas_metadata_get

Tag: atlas

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

  • Location: query
  • Required: no

Schema:

{
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "null"
    }
  ],
  "title": "Dataset Version"
}

Responses

200

Successful Response

application/json

Schema: AtlasMetadata (#/components/schemas/AtlasMetadata)

Schema:

{
  "$ref": "#/components/schemas/AtlasMetadata"
}

404

County or dataset release not found.

application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-404",
  "title": "Request failed",
  "status": 404,
  "detail": "County or dataset release not found.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

422

One or more request values are invalid.

application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-422",
  "title": "Request failed",
  "status": 422,
  "detail": "One or more request values are invalid.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

429

Rate limit exceeded.

Headers
Retry-After
  • Required: no
  • Seconds before retry when supplied by the service.
  • Type: string

Schema:

{
  "type": "string"
}
application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-429",
  "title": "Request failed",
  "status": 429,
  "detail": "Rate limit exceeded.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

503

Atlas data service is unavailable.

Headers
Retry-After
  • Required: no
  • Seconds before retry when supplied by the service.
  • Type: string

Schema:

{
  "type": "string"
}
application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-503",
  "title": "Request failed",
  "status": 503,
  "detail": "Atlas data service is unavailable.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

Download filtered county rankings

GET /v1/atlas/ranking.csv

Operation ID: ranking_csv_v1_atlas_ranking_csv_get

Tag: atlas

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

  • Location: query
  • Required: no

Schema:

{
  "type": "string",
  "pattern": "^(ALL|[A-Z]{2})$",
  "default": "ALL",
  "title": "State"
}

q

  • Location: query
  • Required: no

Schema:

{
  "type": "string",
  "maxLength": 100,
  "default": "",
  "title": "Q"
}

evidence

  • Location: query
  • Required: no

Schema:

{
  "enum": [
    "all",
    "ecological",
    "human",
    "complete"
  ],
  "type": "string",
  "default": "all",
  "title": "Evidence"
}

ecological_share

  • Location: query
  • Required: no

Schema:

{
  "type": "integer",
  "multipleOf": 5,
  "maximum": 85,
  "minimum": 40,
  "default": 65,
  "title": "Ecological Share"
}

low_incidence_breakpoint

  • Location: query
  • Required: no

Schema:

{
  "type": "integer",
  "maximum": 25,
  "minimum": 5,
  "default": 10,
  "title": "Low Incidence Breakpoint"
}

missing_human_weakness

  • Location: query
  • Required: no

Schema:

{
  "type": "integer",
  "multipleOf": 5,
  "maximum": 90,
  "minimum": 40,
  "default": 75,
  "title": "Missing Human Weakness"
}

Responses

200

CSV attachment.

text/csv

Schema:

{
  "type": "string"
}

404

County or dataset release not found.

application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-404",
  "title": "Request failed",
  "status": 404,
  "detail": "County or dataset release not found.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

422

One or more request values are invalid.

application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-422",
  "title": "Request failed",
  "status": 422,
  "detail": "One or more request values are invalid.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

429

Rate limit exceeded.

Headers
Retry-After
  • Required: no
  • Seconds before retry when supplied by the service.
  • Type: string

Schema:

{
  "type": "string"
}
application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-429",
  "title": "Request failed",
  "status": 429,
  "detail": "Rate limit exceeded.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

503

Atlas data service is unavailable.

Headers
Retry-After
  • Required: no
  • Seconds before retry when supplied by the service.
  • Type: string

Schema:

{
  "type": "string"
}
application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-503",
  "title": "Request failed",
  "status": 503,
  "detail": "Atlas data service is unavailable.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

Get county gap scores

GET /v1/atlas/scores

Operation ID: scores_v1_atlas_scores_get

Tag: atlas

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

  • Location: query
  • Required: no

Schema:

{
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "null"
    }
  ],
  "title": "Dataset Version"
}

ecological_share

  • Location: query
  • Required: no

Schema:

{
  "type": "integer",
  "multipleOf": 5,
  "maximum": 85,
  "minimum": 40,
  "default": 65,
  "title": "Ecological Share"
}

low_incidence_breakpoint

  • Location: query
  • Required: no

Schema:

{
  "type": "integer",
  "maximum": 25,
  "minimum": 5,
  "default": 10,
  "title": "Low Incidence Breakpoint"
}

missing_human_weakness

  • Location: query
  • Required: no

Schema:

{
  "type": "integer",
  "multipleOf": 5,
  "maximum": 90,
  "minimum": 40,
  "default": 75,
  "title": "Missing Human Weakness"
}

Responses

200

Successful Response

application/json

Schema: ScoreCollection (#/components/schemas/ScoreCollection)

Schema:

{
  "$ref": "#/components/schemas/ScoreCollection"
}

404

County or dataset release not found.

application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-404",
  "title": "Request failed",
  "status": 404,
  "detail": "County or dataset release not found.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

422

One or more request values are invalid.

application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-422",
  "title": "Request failed",
  "status": 422,
  "detail": "One or more request values are invalid.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

429

Rate limit exceeded.

Headers
Retry-After
  • Required: no
  • Seconds before retry when supplied by the service.
  • Type: string

Schema:

{
  "type": "string"
}
application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-429",
  "title": "Request failed",
  "status": 429,
  "detail": "Rate limit exceeded.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

503

Atlas data service is unavailable.

Headers
Retry-After
  • Required: no
  • Seconds before retry when supplied by the service.
  • Type: string

Schema:

{
  "type": "string"
}
application/problem+json

Schema: ProblemDetails (#/components/schemas/ProblemDetails)

Schema:

{
  "$ref": "#/components/schemas/ProblemDetails"
}

Examples:

illustrative

Synthetic error example

{
  "type": "https://carawaylabs.com/problems/http-503",
  "title": "Request failed",
  "status": 503,
  "detail": "Atlas data service is unavailable.",
  "instance": "/v1/observations",
  "request_id": "example-request-id"
}

Geographies

Typed geography identity; delivery is not yet available.

Counties

Existing county details and versioned PDF reports.

On this page

Get county display geometryParametersdataset_versionResponses200application/geo+json304404application/problem+jsonillustrative422application/problem+jsonillustrative429HeadersRetry-Afterapplication/problem+jsonillustrative503HeadersRetry-Afterapplication/problem+jsonillustrativeGet Atlas release metadataParametersdataset_versionResponses200application/json404application/problem+jsonillustrative422application/problem+jsonillustrative429HeadersRetry-Afterapplication/problem+jsonillustrative503HeadersRetry-Afterapplication/problem+jsonillustrativeDownload filtered county rankingsParametersstateqevidenceecological_sharelow_incidence_breakpointmissing_human_weaknessResponses200text/csv404application/problem+jsonillustrative422application/problem+jsonillustrative429HeadersRetry-Afterapplication/problem+jsonillustrative503HeadersRetry-Afterapplication/problem+jsonillustrativeGet county gap scoresParametersdataset_versionecological_sharelow_incidence_breakpointmissing_human_weaknessResponses200application/json404application/problem+jsonillustrative422application/problem+jsonillustrative429HeadersRetry-Afterapplication/problem+jsonillustrative503HeadersRetry-Afterapplication/problem+jsonillustrative