CDC WONDER Mortality Database - Data Directory

Source ID: DS-00005

This directory contains data files fetched from the CDC WONDER Mortality Database API.

File Structure

Raw JSON Files

drugOverdose_latest.json - Drug overdose deaths (ICD-10: X40-X44, X60-X64, X85, Y10-Y14)
opioid_latest.json - Opioid-specific deaths (ICD-10: T40.0-T40.4, T40.6)
suicide_latest.json - Suicide deaths (ICD-10: X60-X84, Y87.0, U03)
allCause_latest.json - All-cause mortality
all_queries_latest.json - Combined dataset from all queries

Transformed Pipe-Delimited Files

drugOverdose_latest.txt - Drug overdose deaths in Substrate format
opioid_latest.txt - Opioid deaths in Substrate format
suicide_latest.txt - Suicide deaths in Substrate format
allCause_latest.txt - All-cause mortality in Substrate format

Data Format

Raw JSON

Array of mortality records with fields:

state - US state name
year - Year of death
deaths - Number of deaths
population - Population (if available)
crudeRate - Crude death rate per 100,000
ageAdjustedRate - Age-adjusted death rate per 100,000 (if available)

Pipe-Delimited Format

Substrate standard format:

RECORD ID | QUERY TYPE | STATE | YEAR | DEATHS | POPULATION | CRUDE RATE | AGE ADJUSTED RATE
DS-00005-drugOverdose-California-2020 | Drug Overdose Deaths | California | 2020 | 5000 | 39538223 | 12.6 | N/A

Update Process

Run the update script to fetch latest data:

bun run update.ts

Data Coverage

Geographic: All US states + DC + territories
Temporal: 1999-present (ICD-10 era); most recent data typically 1-2 years lag
Frequency: Annual updates (final data); quarterly (provisional data)
Completeness: Census (100% of deaths, not sample)

Important Notes

Cell Suppression

CDC WONDER suppresses cells with counts <10 to protect privacy. Suppressed cells appear as "Suppressed" in results.

Data Quality

Drug overdose deaths: May be undercounted by 10-20% due to incomplete toxicology testing
Suicide deaths: Estimated 20-35% undercount due to classification challenges
Provisional data: Subject to revision when finalized (can change by 5-10%)

Rate Calculations

Crude Rate: Deaths per 100,000 population
Age-Adjusted Rate: Standardized to 2000 US standard population (enables comparability across populations with different age structures)

Citation

When using this data, cite:

Centers for Disease Control and Prevention, National Center for Health Statistics. (2024). Wide-ranging ONline Data for Epidemiologic Research (WONDER). http://wonder.cdc.gov

Last Updated

Generated by update.ts script. See update.log for last update timestamp and details.