CDC WONDER vs data.cdc.gov: Which One Do You Need?

Short answer: they do different things

CDC WONDER is a query tool for detailed vital statistics. data.cdc.gov is an open-data portal with a REST API. They share some underlying data sources (both pull from NCHS), but the access model, granularity, and developer experience are completely different.

Pick WONDER when you need county-level mortality cross-tabs with age-adjusted rates. Pick data.cdc.gov when you need a stable JSON endpoint for your app or pipeline.

Most confusion comes from assuming one mirrors the other. It does not.

TL;DR

CDC WONDER = interactive query builder for vital statistics (mortality, natality, VAERS). County-level data available through the web UI only.
data.cdc.gov = Socrata-powered data portal with 1,500+ datasets and a proper REST API (SODA). Covers surveillance, behavioral data, chronic disease, and more.
WONDER's API is XML-based, restricted to national-level data for mortality/natality, and recommends one query every 2 minutes.
data.cdc.gov's SODA API returns JSON/CSV, supports SoQL filtering, and has no practical rate limit with a free app token.
Some datasets exist in both systems but at different granularity levels.
Neither is a replacement for the other. Most health data projects need both at some point.

How we evaluated

We compared both platforms across six axes that matter to developers and researchers: dataset coverage, geographic granularity, API access, update cadence, data suppression, and export formats. All details verified against CDC's own documentation (WONDER API help page last reviewed January 14, 2026) and the Socrata developer docs.

Head-to-head comparison

Feature	CDC WONDER	data.cdc.gov
Primary use	Cross-tabulation of vital stats	Open data catalog with API
Total datasets	~30 query databases	1,500+ flat datasets
API type	XML over HTTP POST	REST (SODA), SoQL queries
Auth required	None	None (app token optional)
Response format	XML only	JSON, CSV, GeoJSON
Geographic depth	County (web) / National only (API)	Varies by dataset
Rate limit	~1 query per 2 minutes (recommended)	Effectively unlimited with app token
Suppression	Cells under 10 deaths hidden	Per-dataset, set by publisher
Row limit	75,000 per query	50,000 per page (paginate for more)
Update cadence	Mostly annual; VAERS weekly	Per-dataset (weekly to annual)

When to use CDC WONDER

WONDER is the right tool when your question involves cross-tabulating mortality or natality data across multiple dimensions at once.

Best for:

County-level death rates by cause (ICD-10 codes), age, sex, and race
Age-adjusted mortality rates with confidence intervals (calculated server-side)
Historical mortality analysis back to 1968
VAERS vaccine adverse event queries with narrative text search
Environmental exposure data (PM2.5, temperature, precipitation grids)

Real example: "How many opioid overdose deaths (ICD-10 X40-X44) occurred in Franklin County, Ohio, in 2023, broken down by age group?" WONDER answers this through its web form in about 30 seconds. No other public tool provides this exact cross-tab.

The catch: The web interface feels like a 1990s government form. Steep learning curve, no bookmarkable queries, and results export as tab-delimited text files only.

When to use data.cdc.gov

data.cdc.gov is the right tool when you need programmatic, repeatable access to CDC data in a format your code can consume directly.

Best for:

Building dashboards or apps that pull live CDC data
COVID-19 provisional death counts by jurisdiction
BRFSS behavioral risk factor surveys
Chronic disease indicators at state level
Any workflow that needs JSON or CSV from a stable endpoint

Real example: Pull provisional COVID-19 death counts with one GET request:

curl "https://data.cdc.gov/resource/dmnu-8erf.json?$limit=50"

No XML. No consent parameter. JSON comes back in under a second.

The catch: Fewer datasets than you might expect for mortality/natality (the granular cross-tabs live in WONDER, not here). Geographic depth depends entirely on what the publishing program chose to release.

The API gap that trips up developers

Here is the single most important thing nobody tells you upfront:

WONDER's API cannot return state or county-level data for mortality and natality.

The web interface shows county-level results. The API does not. CDC restricts the API to national-level aggregates for all National Vital Statistics System databases. This policy has been in place since February 2015 and was reconfirmed in the API documentation reviewed January 14, 2026.

That means if you want county-level mortality data programmatically, your options are:

Screen-scrape WONDER's web form (fragile, against TOS spirit)
Download bulk files from CDC's FTP and process locally
Use a normalized API that has already done the bulk ingestion for you

This restriction does not apply to non-vital-statistics databases. VAERS, environmental data, and TB statistics can be grouped by state/county through the WONDER API.

Datasets that overlap (and how they differ)

Some NCHS data appears in both systems. Same source, different shape:

Dataset	In WONDER	In data.cdc.gov
Provisional COVID-19 deaths	Interactive cross-tab (state x age x sex x week)	Flat table, filter with SoQL
NNDSS notifiable diseases	Weekly/annual summary tables	Flat weekly counts
Mortality summary stats	Full cross-tabulation engine	Pre-aggregated tables

The WONDER version lets you slice on the fly. The data.cdc.gov version is pre-shaped but API-friendly. Think of it as the difference between a SQL database you can query (WONDER) and a CSV download someone already ran the query for (data.cdc.gov).

WONDER's XML API: what you are signing up for

If you decide to query WONDER programmatically, here is what the request looks like:

<request-parameters>
  <parameter>
    <name>accept_datause_restrictions</name>
    <value>true</value>
  </parameter>
  <parameter>
    <name>B_1</name>
    <value>D76.V1-level1</value>
  </parameter>
  <parameter>
    <name>M_1</name>
    <value>D76.M1</value>
  </parameter>
</request-parameters>

You POST this XML to https://wonder.cdc.gov/controller/datarequest/D76 and get XML back. Parameters use cryptic codes: B_ for group-by variables, M_ for measures, V_ and F_ for filters. The database ID (D76) changes when CDC releases a new data vintage, which breaks hardcoded scripts without warning.

CDC's own recommendation: run your query manually first, click "API Options" on the results tab, and download the generated XML as your starting template.

Contrast with data.cdc.gov:

curl "https://data.cdc.gov/resource/mpx5-t7tu.json?$where=state='Ohio'&$limit=100"

One line. Human-readable. Stable endpoint.

Data suppression: the hidden gotcha

WONDER suppresses any cell representing fewer than 10 deaths. Query county-level data by race, age, and a rare cause of death, and your results come back almost entirely marked "Suppressed."

This is not a bug. It is a privacy protection for small populations. But it means granular queries for rare conditions at small geographies return useless results through WONDER.

data.cdc.gov handles suppression differently. Each dataset publisher applies their own disclosure rules before uploading. Some datasets pre-suppress; others publish the raw counts because the geographic level is already broad enough. Check each dataset's documentation.

Common mistakes (and how to avoid them)

Mistake 1: Hardcoding WONDER's database ID. CDC retires old database IDs (like D76) when a new data vintage is released. Your script breaks overnight. Build in a check or query the available databases list before submitting.

Mistake 2: Expecting the WONDER API to work like the website. The web UI shows county data, the API does not (for vital stats). This trips up a new developer every week on StackOverflow and Reddit. Accept that the API is national-only for mortality, and plan your data pipeline around that constraint from the start.

Mistake 3: Ignoring SODA app tokens on data.cdc.gov. Without a token, your requests get throttled per IP. With a free token (takes 30 seconds to register), throttling effectively disappears. Always register a token before building anything production-grade.

Mistake 4: Assuming data.cdc.gov has everything. It has breadth (1,500+ datasets), but WONDER has depth. If you need ad-hoc cross-tabs across four demographic variables and a specific ICD-10 range, WONDER is the only game in town.

Decision flowchart

Start here: Do you need to write code that calls an API on a schedule?

Yes → Go to data.cdc.gov first. Check if your dataset exists there. If it does, you are done.
No, I need an interactive one-off query → Go to WONDER.

If data.cdc.gov does not have your dataset:

Do you need county-level mortality or natality? → WONDER web interface (not the API).
Do you need national-level mortality stats programmatically? → WONDER API works, but the XML is painful.
Do you need both granularity and automation? → Bulk download from CDC FTP, or use a unified health data API that normalizes these sources for you.

FAQ

Can I get county-level death data from WONDER's API?

No. The WONDER API restricts mortality and natality queries to national-level data only. County-level results are available through the web interface but not the API. This policy was set in 2015 and confirmed current in January 2026.

Is data.cdc.gov the same data as WONDER?

Partially. Some datasets (COVID-19 provisional deaths, NNDSS) exist in both. But WONDER's core mortality cross-tabulation engine and its VAERS query tool have no equivalent on data.cdc.gov.

Do I need an API key for either platform?

Neither requires authentication. data.cdc.gov offers optional app tokens that remove rate-limit throttling. WONDER has no token system at all.

How often does WONDER update its data?

Most mortality databases update annually. VAERS updates weekly. Provisional COVID-19 data updates monthly. When a new data vintage is released, the database ID changes (breaking API scripts that hardcode it).

What format does WONDER's API return?

XML only. No JSON option. You parse the XML response yourself or use a wrapper library. The community-maintained cdc-wonder-api Python repo on GitHub provides working examples.

Why do my WONDER results say "Suppressed"?

Cells with fewer than 10 deaths are suppressed to protect individual privacy. Broaden your geographic grouping (county to state) or widen the cause-of-death codes to get unsuppressed results.

Can I combine data from both platforms?

Yes. A common pattern: use data.cdc.gov's SODA API for weekly surveillance data in your pipeline, then pull annual mortality summaries from WONDER for deeper analysis. Match on shared fields like state FIPS codes, year, and ICD-10 cause codes.

Which one should I use for a health data app?

data.cdc.gov. Its REST API returns JSON, supports pagination, and handles thousands of requests without throttling. WONDER's XML API and 2-minute query cadence make it impractical for production applications.

What MyfitByte does with both

MyfitByte normalizes data from CDC WONDER, data.cdc.gov, FDA, NPI, and CMS into a single REST API. County-level mortality data that requires manual WONDER queries becomes a standard JSON endpoint with filtering, pagination, and no suppression headaches at the API layer.

If you are building a health data product and want programmatic access to CDC data without maintaining XML parsers or screen scrapers, join the waitlist.

Last verified: August 22, 2026. Sources: CDC WONDER API documentation (reviewed January 14, 2026), Socrata SODA developer docs, CDC WONDER FAQ.