CDC WONDER Scraper

Query CDC WONDER — the CDC's public health statistics system — for US mortality (underlying cause of death) and natality (births) data. Group results by year, sex, race, Hispanic origin, age, and cause of death, with death/birth counts and rates. HTTP-only via the official wonder.cdc.gov machine-readable XML API. No auth, no login, no proxy.

What this actor does

• Three datasets: historical mortality (1999-2020), current mortality (2018-2023, single-race categories), and natality/births (2007-2023)
• Flexible grouping: cross-tabulate by up to two axes at once (e.g. year x sex, race x cause of death, or birth weight x gestational age)
• Demographic filters: sex, race, Hispanic origin, age group, marital status (natality)
• Natality health axes: group births by birth weight or gestational age at delivery
• Cause-of-death filter: restrict mortality queries to a single ICD-10 disease chapter (cancer, heart disease, injuries, etc.)
• Rates: crude death rate always included; optional age-adjusted rate (mortality) with 95% confidence interval
• Empty fields are omitted

Output per record

• dataset — D76 / D158 / D66 (CDC WONDER's internal dataset code)
• datasetLabel — human-readable dataset name
• year — calendar year (when Year is a grouping axis)
• sex, race, hispanicOrigin, ageGroup, causeOfDeath — mortality demographic/cause breakdown (when used as a grouping axis)
• ageOfMother, maritalStatus, birthWeight, gestationalAge — natality-specific breakdown (when used as a grouping axis)
• deaths / births — the underlying count
• population — mid-year population denominator (mortality only)
• crudeRate — rate per 100,000 population (mortality) / per 1,000 population (natality), with crudeRateConfidenceInterval when available
• ageAdjustedRate, ageAdjustedRateConfidenceInterval — age-standardized death rate (mortality, opt-in)
• birthRate, birthRateConfidenceInterval — births per 1,000 population (natality, opt-in)
• deathsSuppressed / birthsSuppressed / crudeRateSuppressed — true when CDC WONDER withheld the exact value for small-count privacy protection (see FAQ)
• isTotal — true for subtotal/grand-total rows (present whenever "Show Totals" is on, which it always is)
• sourceUrl — CDC WONDER's dataset documentation page
• recordType — mortalityRecord or natalityRecord
• scrapedAt — UTC timestamp

Input

Field	Type	Default	Description
mode	string	mortalityHistorical	mortalityHistorical / mortalityCurrent / natality
groupBy1	string	year	Primary grouping axis (natality adds birthWeight / gestationalAge)
groupBy2	string	none	Optional second grouping axis (natality adds birthWeight / gestationalAge)
yearFrom / yearTo	int	2015 / 2020	Year range (clamped to the selected dataset's valid range)
sexFilter	string	all	Restrict to Female/Male (shared across all 3 datasets)
raceFilter	string	all	Race filter for mortalityHistorical / natality (bridged-race categories)
raceFilterCurrent	string	all	Race filter for mortalityCurrent (single-race categories)
hispanicOriginFilter	string	all	Hispanic origin filter for mortality modes
hispanicOriginFilterNatality	string	all	Hispanic origin filter for natality mode
ageGroupFilter	string	all	10-year age band filter (mortality modes)
ageOfMotherFilter	string	all	Mother's age band filter (natality)
maritalStatusFilter	string	all	Mother's marital status filter (natality)
icd10Category	string	all	ICD-10 disease chapter filter (mortality modes)
includeAgeAdjustedRate	bool	false	Add age-adjusted rate (mortalityHistorical only)
maxItems	int	500	Hard cap on emitted records (1-5000)

Example: deaths by year and sex, 2015-2020

{
  "mode": "mortalityHistorical",
  "groupBy1": "year",
  "groupBy2": "sex",
  "yearFrom": 2015,
  "yearTo": 2020
}

Example: cancer deaths by race, current dataset, with age-adjusted comparison unavailable (crude rate only)

{
  "mode": "mortalityCurrent",
  "groupBy1": "year",
  "groupBy2": "raceFilterCurrent",
  "icd10Category": "C00-D48",
  "yearFrom": 2019,
  "yearTo": 2022
}

Example: births by year and age of mother

{
  "mode": "natality",
  "groupBy1": "year",
  "groupBy2": "ageOfMother",
  "yearFrom": 2018,
  "yearTo": 2023
}

Example: heart disease mortality trend, single axis

{
  "mode": "mortalityHistorical",
  "groupBy1": "year",
  "icd10Category": "I00-I99",
  "includeAgeAdjustedRate": true,
  "yearFrom": 1999,
  "yearTo": 2020
}

Example: births by birth weight and gestational age

{
  "mode": "natality",
  "groupBy1": "birthWeight",
  "groupBy2": "gestationalAge",
  "yearFrom": 2022,
  "yearTo": 2023
}

Use cases

• Public health research — trend analysis of mortality/natality by demographic group
• Journalism / data storytelling — sourcing verified US vital-statistics figures
• Epidemiology courses — teaching datasets with real CDC-published numbers
• Actuarial and insurance analysis — age-adjusted mortality trend inputs
• Policy analysis — cause-of-death and birth-rate trends over time by demographic

Limitations

• sourceUrl may return 403 from a plain curl/script request. CDC WONDER's website (all of wonder.cdc.gov, including its homepage) is protected by Akamai bot-management that blocks unauthenticated GET requests from non-browser clients - this affects every page on the domain, not just the ones this actor links to. It renders normally in a real web browser. Only the specific POST-based API endpoint this actor uses (/controller/datarequest/<dataset>) is allowlisted for programmatic access, which is exactly why this actor's requests succeed reliably while a plain curl of the same domain's pages does not.
• National totals only. CDC WONDER's public web-service API (which this actor uses) returns USA-wide totals only. State, county, region, division, and urbanization breakdowns are available on the interactive wonder.cdc.gov website but are rejected by the API with an explicit error - this is a CDC-side restriction, not a bug in this actor.
• Small-count suppression. Per federal statistical disclosure policy, CDC WONDER withholds exact counts below a small threshold (typically under 10). Suppressed cells are represented as <field>Suppressed: true with the numeric field omitted, rather than a fabricated zero or null.
• Birth Rate not available. CDC WONDER's natality dataset exposes a Birth Rate measure in its interactive UI, but its machine-readable API currently rejects every Birth Rate request with a server-side error regardless of grouping or filters (confirmed live across all axis combinations). This actor does not request Birth Rate for that reason; birth counts (births) are always returned.
• Rate limiting. CDC WONDER enforces a mandatory 15-second minimum interval between API requests platform-side; the actor respects this automatically on retries.
• Bridged-race natality data. CDC's "bridged race" methodology (used by raceFilter in natality mode) was discontinued after 2020 - race breakdowns for natality years after 2020 may return sparse or no results for that axis.
• 2018-2023 mortality data only (not through 2024) and 2007-2023 natality data only (not through 2024) - the most recent year is often still provisional at CDC and unavailable via the API even though the dataset's public label mentions a later year.

FAQ

What is CDC WONDER? CDC WONDER (Wide-ranging ONline Data for Epidemiologic Research) is the CDC's public system for querying US public-health statistics, including mortality and natality data compiled from official vital records. See wonder.cdc.gov.

Is this affiliated with the CDC? No. This is a third-party actor that queries CDC WONDER's public, documented API. It is not endorsed by or affiliated with the CDC.

Why are some values missing / marked "Suppressed"? Federal statistical disclosure policy requires CDC WONDER to withhold death/birth counts below a small threshold to protect individual privacy. This is standard CDC policy, not a scraping error.

Can I get state or county-level data? Not through this actor. CDC WONDER's API only serves national totals; state/county data requires the interactive web UI and manual data-use agreement steps CDC does not expose programmatically.

What's the difference between the two mortality datasets? mortalityHistorical (D76) uses CDC's "bridged race" 4-category classification and covers 1999-2020. mortalityCurrent (D158) uses the newer single-race classification (including "Native Hawaiian/Other Pacific Islander" and "More than one race" as separate categories) and covers 2018 onward.

What does "crude rate" vs "age-adjusted rate" mean? Crude rate is deaths per population, unadjusted. Age-adjusted rate standardizes for age-distribution differences across groups/years, making it the preferred metric for comparing mortality trends over time or between populations with different age structures.

How current is the data? CDC WONDER data lags several months to a year behind real time as vital records are finalized; the most recent 1-2 years available in each dataset's label are often not yet queryable via the API.