Cdc Query Wonder
cdc_query_wonderQuery CDC WONDER for national US mortality statistics — deaths, population, and crude/age-adjusted death rates — across its five mortality databases, selected with the database input: final underlying-cause data for 1999–2020 (the default) or 2018–2024, provisional data running from 2018 through the current year, and two multiple-cause databases covering the same two eras. Break results out by year, age group, sex, and/or race, and filter by ICD-10 cause of death, sex, age group, or year range; on a multiple-cause database, mcd_icd10 additionally matches a cause listed anywhere on the death certificate rather than only the one certified as underlying. Each database holds a different span of years (1999–2026 across all of them) and a request whose year_range falls outside the selected one's span is rejected with that span named. WONDER is a separate CDC system from the Socrata datasets the other cdc_* tools query. Data is national only — sub-national (state/county) breakdowns are not available through the API (CDC vital-statistics policy). Cause of death is a filter, not a grouping. Some measure cells come back as a CDC status token rather than a number — "Suppressed" (withheld for confidentiality), "Unreliable" (a rate from fewer than 20 deaths), or "Not Applicable" (no population denominator); those cells read null in rows and each one is listed in cellNotes with its token. CDC also drops whole rows before sending the table — strata with zero deaths, and strata whose death count is suppressed — so a stratum can be missing from rows entirely; messages carries CDC's statement whenever that happened. The whole table comes back by default; a broad grouping can run past a thousand rows, so set limit to take it a page at a time and follow the nextOffset the response reports. Paging shapes the response only — WONDER is asked once either way, and the figures, caveats and hidden-row notices are the same on every page. CDC rejects requests made less than 15 seconds apart across all five databases, so consecutive calls are spaced automatically and a follow-up call may wait about 16 seconds before it runs.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | Filter by sex. | all |
| limit | No | Rows to return from the table CDC sent (1–5000). Omit to return the whole table. WONDER's request carries no limit of its own, so this pages a table already fetched in full rather than narrowing the query: the deaths, rates, caveats and hidden-row notices are the same whichever page is read. A four-dimension grouping can run past a thousand rows, so set this and follow nextOffset to walk them. | |
| offset | No | Index of the first row to return, for continuing past a previous call (default 0, max 10,000). Rows keep the order CDC returned them in, which is stable for a given query, so offset plus limit walks the table without gaps or repeats. An offset at or past the row total returns an empty page rather than an error. | |
| database | No | Which WONDER mortality database to query. "underlying_1999_2020" (D76) is final data for 1999–2020 and the default. "provisional" (D176) runs 2018 through the current year, updated weekly, and returns the most recent years labelled e.g. "2025 (provisional)". "underlying_2018_2024" (D158) is settled — not provisional — data for 2018–2024. "multiple_1999_2020" (D77) and "multiple_2018_2024" (D157) record every cause listed on the death certificate; without an mcd_icd10 filter they return the same figures as the underlying-cause database for the same era, so pick one only to use that filter. The two 1999–2020 databases report race in CDC's four bridged groups; the other three use the six single-race groups — figures broken out by race are not comparable between the two families. | underlying_1999_2020 |
| group_by | No | Dimensions to break results out by (1–4), in output-column order — e.g. ["year"], ["year","sex"], ["age_group","race"]. Results are always national. Cause of death is a filter (cause_icd10), not a grouping. "race" resolves to whichever race vocabulary the selected database uses — four bridged groups (Asian and Pacific Islander combined) on the 1999–2020 databases, six single-race groups plus a multiracial category on the others — so a race series from one family cannot be spliced onto one from the other. | |
| mcd_icd10 | No | Filter to deaths with this ICD-10 code recorded anywhere on the death certificate, whether or not it was the underlying cause — e.g. "died with a respiratory condition listed", a population no underlying-cause query can produce. Valid only when database is "multiple_1999_2020", "multiple_2018_2024", or "provisional"; the other databases record only the underlying cause and reject it. "999--999", the withheld-cause marker described under cause_icd10, is offered here too but only by "provisional". Combines with cause_icd10, which keeps meaning the underlying cause. Omit for all causes. | |
| age_groups | No | Restrict to deaths in any of the listed age groups — e.g. ["25-34","35-44"] covers both. "1" is the under-1-year group. "NS" is the group CDC puts a death in when the age was not recorded; it is not covered by any of the ten-year groups, so a filter listing all eleven of those still leaves those deaths out and returns fewer deaths than the same query unfiltered. List "NS" alongside them to match an unfiltered total, or on its own to count them. Omit for all ages, which includes them. | |
| year_range | No | Inclusive year range. These bounds span every database (1999–2026); the years the selected one actually holds are narrower, and a range outside them is rejected with that database's span named. Omit for all years the database holds. | |
| cause_icd10 | No | Filter to a specific ICD-10 underlying cause of death — the single condition CDC certified as having started the chain of events leading to death. Omit for all causes. Accepted by every database. "999--999" is not an ICD-10 code but CDC's own marker for deaths whose cause it is still withholding under the provisional database's six-month reporting lag; it counts that backlog, and only the "provisional" database offers it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | The requested limit that bounded this response. | |
| rows | No | Result rows. Each carries the requested group-by dimensions plus deaths, population, crude_rate, and age_adjusted_rate (per 100,000) when age standardization is possible — it is omitted when age_group is a grouping dimension or age_groups selects a single group. Dimension values are CDC's own labels with only surrounding whitespace removed, so the same year keys identically across databases; nothing inside a label is changed, and on the provisional database a year reads "2025 (provisional)" or "2026 (provisional and partial)" rather than a bare year. A measure cell CDC returned as a status token instead of a number is null here; cellNotes names the cell and the token. When limit or offset is set these are one page of the table CDC sent, in its order; totalCount says how many rows the whole table holds. | |
| error | No | Present when the call failed. Absent on success. | |
| shown | No | Number of rows returned in this response. | |
| notice | No | Guidance when no rows matched, when the returned rows are a page of a larger table or the offset ran past it, and a note when CDC returned a status token in place of a measure value. | |
| caveats | No | CDC-provided caveats and footnotes: data revisions, population-estimate sources, suppression and rate-reliability rules. They describe the whole table CDC assembled, so they come back complete on every page rather than scoped to the rows returned. | |
| database | No | WONDER dataset code the rows came from — e.g. "D76", "D176", "D157". | |
| messages | No | Notices CDC attached to this table, verbatim. The ones that matter say rows were withheld before the table was sent — "Rows with zero Deaths are hidden." and "Rows with suppressed Deaths are hidden." A withheld row is absent from rows entirely, with nothing in the table marking the gap, so while this array is non-empty a stratum missing from rows may have been dropped rather than unobserved, and any count, ranking, or completeness claim drawn from rows is partial. These describe the whole table, so they come back complete on every page. Empty when CDC withheld no rows. | |
| rowCount | No | Number of rows returned in this response — the page size when limit or offset is set. | |
| cellNotes | No | One entry per measure cell CDC returned as a status token rather than a number, covering the rows in this response only. Those cells read null in rows, so this is what tells a withheld value apart from an unreliable one or a genuinely absent one. | |
| truncated | No | True when rows remain past the ones returned. Absent means this response runs to the end of the table, which is also the case for an offset past it. | |
| nextOffset | No | Offset to pass on the next call to resume immediately after the last row returned. Present only when further rows remain. | |
| totalCount | No | Rows in the whole table CDC returned, before limit/offset. Exact rather than estimated — the table is parsed in full before a page is taken from it. | |
| databaseTitle | No | CDC's own title for that database, e.g. "Underlying Cause of Death, 1999-2020". Names the era and record type the rows describe, so a result read on its own is self-describing. | |
| effectiveQuery | No | Human-readable summary of the grouping and filters sent to WONDER. | |
| suppressedCount | No | How many cellNotes carry the "Suppressed" token — cells CDC withheld for confidentiality. Counted over the rows in this response, so it tracks the page rather than the whole table. |