Skip to contents

Retrieve STI surveillance data from CDC AtlasPlus

Source: R/get_atlas.R
get_atlas.Rd

get_atlas() provides a programmatic interface to the CDC AtlasPlus platform, returning case counts, population denominators, and rate estimates for sexually transmitted infection (STI) surveillance. The function submits a payload to the AtlasPlus data endpoint and parses the response into a tidy tibble.

Usage

get_atlas(disease, geography, year, stratify_by = NULL)

Arguments

disease

Character scalar. A single disease name (e.g. "gonorrhea"). Multiple diseases are not currently supported in a single request.

geography

Character scalar. One of "national", "region", "state", "county", or "msa".

year

Integer vector of years. Valid values are from 2000 to 2023. Can be a single year (e.g., 2022) or a sequence (e.g., 2018:2022).

stratify_by

Optional character vector. Zero, one, or two of "age", "race", "sex". If NULL, totals (unstratified) are returned.

restrict_to

Optional character vector restricting results to specific states or counties (case-insensitive). If omitted, all units at that geographic level are returned.

Value

A tibble with the following columns:

indicator

Disease/condition name (factor)

year

Calendar year (numeric)

geography

Geographic unit name (factor)

data_status

Data quality flags (factor)

race_ethnicity

Race/ethnicity category (factor, if stratified)

sex

Sex category (factor, if stratified)

age

Age group (factor, if stratified)

transmission

Transmission category (factor)

rate100000

Incidence rate per 100,000 (numeric)

cases

Case count (numeric)

population

Population denominator (numeric)

lowerci_rate, upperci_rate

95% CI bounds for rate (numeric)

rse

Relative standard error (numeric)

lowerci_cases, upperci_cases

95% CI bounds for cases (numeric)

FIPS code (character)

Columns and naming conventions may differ depending on CDC schema changes. The function attempts to standardize but does not guarantee historical compatibility for all years.

Details

The function supports multiple diseases, geographic levels, year ranges, and optional stratification. Stratified queries expand results into all requested combinations (e.g., age by race). When possible, numeric fields are returned as double and identifiers as character.

Supported diseases

  • "chlamydia"

  • "gonorrhea"

  • "syphilis"

Geography

  • "national"

  • "region"

  • "state"

  • "county"

  • "msa" (metropolitan statistical area)

Stratification The CDC AtlasPlus API supports stratification by one or two dimensions:

  • "age"

  • "race"

  • "sex"

Stratification increases the number of returned rows. For example, stratify_by = c("race", "sex") returns all race × sex combinations for each geography-year pair.

This function is a reverse-engineered wrapper around the AtlasPlus public query system. The CDC does not publish an official API specification, and internal identifiers may change without notice. If the CDC modifies the backend schema, requests may fail. Please report issues via GitHub.

See also

cdc_atlas_meta() for metadata lookup and variable dictionaries.

Examples

if (FALSE) {
# National gonorrhea rates for 2018–2022
get_atlas(disease = "gonorrhea", geography = "national", year = 2018:2022)

# State-level chlamydia, stratified by race
get_atlas(
  disease = "chlamydia",
  geography = "state",
  year = 2022,
  stratify_by = "race"
)

# Limit to specific states
get_atlas(
  disease = "gonorrhea",
  geography = "state",
  year = 2022,
  restrict_to = c("NY", "CA", "TX")
)
}