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 (its latest year partial, with a notice saying so), and two multiple-cause databases covering the same two eras. Break results out by year, month, age group, sex, race, Hispanic origin, or underlying cause of death — ICD-10 chapter or sub-chapter, CDC's 113-cause list, its 15 leading causes, or injury intent — 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). Chapter and sub-chapter rows carry their ICD-10 code range as cause_code, which cause_icd10 accepts as it stands; 113-cause-list rows carry cause_level, their depth in that nested list, whose deeper causes are already counted in the cause containing them; leading_causes ranks the 15 leading causes by deaths and combines with no other grouping, while the filters still apply; month rows carry deaths only — CDC publishes no monthly population, so population and both rates come back "Not Applicable". The values each grouping dimension can take multiply to bound the table — year beside month, or icd_chapter beside icd_subchapter, adds nothing, since the finer level already enumerates the coarser — and a grouping that could produce more than 10,000 rows is refused before any request with the product named, since WONDER takes longer than the request deadline to answer a table that large; narrow year_range, sex or age_groups, or drop a dimension. Some measure cells come back as a CDC status token rather than a number — "Suppressed" (withheld for confidentiality), "Unreliable" (a rate CDC judges statistically unstable and does not show — on D76 and D77 when it is computed from 20 or fewer deaths, and D176, D158, and D157 when its 95% confidence interval is wider than 160% of the rate, whatever the death count), or "Not Applicable" (no population denominator); those cells read null in rows and each one is listed in cellNotes with its token. Each rate comes with the 95% confidence interval CDC publishes for it, as _lower and _upper right after the rate — null where CDC published none — so two rates can be compared by their intervals rather than their point values. 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. One call returns at most 10,000 rows: with limit omitted it returns the rest of the table up to that ceiling, a larger limit is lowered to it, and a smaller limit takes smaller pages; a page that stops short of the end reports the table's totalCount and a nextOffset to continue from. Paging shapes the response only — every call fetches the whole table from WONDER and returns a slice of it, so the figures, caveats and hidden-row notices are the same on every page and a smaller page saves no time. CDC rejects requests made less than 15 seconds apart across all five databases, so calls are spaced automatically: calls made while another is running wait their turn and run one after another, each queued call adding about 16 seconds plus its own query time before it returns. A request WONDER has not finished answering within 20 seconds fails as a retryable upstream_error, so one call queued behind another returns within about 56 seconds.
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "cdc_query_wonder"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sex | No | Filter by sex. | all |
| limit | No | Rows to return from the table CDC sent — any positive integer. Omit to take the rest of the table from offset, up to 10,000 rows. One call returns at most 10,000 rows: a larger limit is lowered to 10,000, and the response says so and gives a nextOffset when rows remain. 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. | |
| 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)". Its latest year is partial — deaths only through the data-through date the response names, against a full-year population — so its counts and rates read low next to a finished year, and a notice says so whenever the years queried include it. "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, each at most once), in output-column order — e.g. ["year"], ["year","sex"], ["icd_chapter","year"]. Results are always national. "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 categories on the others, one of them "More than one race" — so a race series from one family cannot be spliced onto one from the other. "hispanic_origin" splits Hispanic or Latino, Not Hispanic or Latino, and Not Stated. "month" groups by calendar month (labels such as "Jan., 2019") and returns deaths only: population and both rates are "Not Applicable". The rest group by underlying cause: "icd_chapter" and "icd_subchapter" by node of CDC's ICD-10 tree, each row carrying the node's code range as cause_code (e.g. "C00-D48"), which cause_icd10 takes as it stands; "cause_113" by CDC's 113-cause list, each row carrying cause_level, its depth in that nested list (1 for a top-level cause) — a deeper cause is already counted in the one containing it; "leading_causes" by the 15 leading causes, ranked by deaths, and only on its own — CDC refuses it beside any other dimension, though the filters still apply; "injury_intent" by intent (unintentional, suicide, homicide, undetermined, legal intervention, or no injury). The most values the listed dimensions can take, multiplied, must be 10,000 or fewer — e.g. icd_subchapter (177) × year (22 on the 1999–2020 databases) × sex (2) fits, and adding age_group (12) does not — or the call is refused before any request. year beside month, and icd_chapter beside icd_subchapter, add nothing to the product, since each month names its year and each sub-chapter sits inside one chapter. | |
| mcd_icd10 | No | Filter to deaths with any of these ICD-10 codes 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. Takes one code or range, or a list of them, e.g. opioid involvement as ["T40.0","T40.1","T40.2","T40.3","T40.4","T40.6"]. 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", where the 24-week withholding also covers drug poisoning (T36-T50) as a listed cause. Combines with cause_icd10, which keeps meaning the underlying cause: a death must match both filters. 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; a repeated group counts once. "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. CDC refuses "NS" beside only some of the other groups: list it on its own to count those deaths, or list all twelve values — the same as omitting age_groups — to include them. Omit for all ages, which includes them. | |
| year_range | No | Inclusive year range; from must not be later than to. 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 ICD-10 underlying causes of death — the single condition CDC certified as having started the chain of events leading to death. Takes one code or range, or a list of them for a cause defined as a code set, e.g. drug overdose as ["X40","X41","X42","X43","X44","X60","X61","X62","X63","X64","X85","Y10","Y11","Y12","Y13","Y14"]. 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. "999-999", the cause_code a sub-chapter row carries for the same deaths, is accepted too and sent as "999--999". On that database CDC withholds external-cause (V01-Y89) and sudden-death (R95, R96) causes for the 24 weeks before its data-through date, so a filter reaching them — a block or chapter containing one included — undercounts those weeks; the notice names the cutoff. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cap | No | Page size that ended this response — limit, or 10,000 (the most one call returns) when limit was omitted or set higher. Present only when rows remain past the page. | |
| rows | No | Result rows. Each carries the requested group-by dimensions, then cause_code when grouped by icd_chapter or icd_subchapter — CDC's code range for the row's ICD-10 node (the sub-chapter's when both are grouped), null where CDC sent none; the provisional database's withheld-cause row reads "999--999" by chapter and "999-999" by sub-chapter, and cause_icd10 takes either as it stands — then cause_level when grouped by cause_113, the row's depth in that nested list as an integer, then 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, and it is the rate to compare across groups, since crude_rate moves with each group's age mix. Each rate is followed by its 95% confidence interval: crude_rate_lower and crude_rate_upper, then age_adjusted_rate_lower and age_adjusted_rate_upper when the row has age_adjusted_rate. The bounds are CDC's own published figures, never computed here, and are null wherever CDC sent no interval (a "Not Applicable" rate, for one); an "Unreliable" rate reads null but keeps the interval CDC published with it. 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. These are one page of the table CDC sent, in its order, bounded by limit and by the 10,000-row per-call ceiling; 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 or CDC recorded no deaths for the query, when the returned rows are a page of a larger table — naming whether limit or the 10,000-row per-call ceiling ended it — or the offset ran past it, whether the rows CDC withheld leave the deaths in rows complete or partial, a note when CDC returned a status token in place of a measure value, that rows grouped by cause_113 nest and do not sum across levels, on a multiple-cause database queried without mcd_icd10, that its figures match the underlying-cause database for the same years, and on the provisional database, when the years queried include its partial latest year (naming the partial month too when grouped by month) or a cause filter or cause grouping reaches causes CDC is still withholding under its 24-week reporting lag. | |
| caveats | No | CDC-provided caveats and footnotes: data revisions, population-estimate sources, suppression and rate-reliability rules. CDC's links to its methodology pages are kept as Markdown links, e.g. "[More information.](https://wonder.cdc.gov/wonder/help/ucd-expanded.html#Confidence-Intervals)". 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 apart from links, which are kept as Markdown links. 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. A stratum hidden for zero deaths recorded none, so deaths summed from rows stay complete; while the suppressed-deaths message is present, a stratum missing from rows may have been dropped rather than unobserved, and any count, ranking, or completeness claim drawn from rows is partial. The notice says which reading applies. 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 whenever it falls short of totalCount. | |
| 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 any page was taken. 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. |