Query CDC WONDER for national US mortality statistics — deaths, population, and crude and age-adjusted death rates with their 95% confidence intervals — from one of five mortality databases, final and provisional, underlying-cause and multiple-cause, together covering 1999 through the current year. 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 matches a cause listed anywhere on the death certificate rather than only the one certified as underlying. 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). Where this server stages tables (cdc_dataframe_query is listed), a first page that leaves rows past it also stages the whole table, which cdc_dataframe_query ranks, compares, or pages with SQL without another WONDER request. 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.
View input schema
{
"type": "object",
"properties": {
"database": {
"default": "underlying_1999_2020",
"description": "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; 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 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 and the other three in six single-race groups, so figures broken out by race are not comparable between the two families.",
"type": "string",
"enum": [
"underlying_1999_2020",
"provisional",
"underlying_2018_2024",
"multiple_1999_2020",
"multiple_2018_2024"
]
},
"group_by": {
"default": [
"year"
],
"description": "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: CDC publishes no monthly population, so 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\"; the sub-chapter's when both are grouped, null where CDC sent none), 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, so deaths do not sum across levels; \"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, since WONDER takes longer than the request deadline to answer a larger table. 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.",
"minItems": 1,
"maxItems": 4,
"type": "array",
"items": {
"type": "string",
"enum": [
"year",
"age_group",
"sex",
"race",
"icd_chapter",
"icd_subchapter",
"cause_113",
"leading_causes",
"injury_intent",
"hispanic_origin",
"month"
]
}
},
"cause_icd10": {
"description": "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, and the cause_code a chapter row carries for them; 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.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"enum": [
"999--999",
"999-999"
]
},
{
"type": "string",
"pattern": "^[A-Z][0-9]{2}(\\.[0-9]+)?(-[A-Z][0-9]{2}(\\.[0-9]+)?)?$",
"description": "ICD-10 underlying-cause code or range. WONDER takes a node of its ICD-10 tree — a chapter such as \"A00-B99\" (infectious) or \"V01-Y89\" (external causes), a block such as \"X40-X49\" (accidental poisoning) or \"C00-C97\" (malignant neoplasms), or a single code such as \"I21\" — and rejects any other span, e.g. \"X40-X44\", naming it in the error. List the codes (or blocks) to cover a span that is not a tree node."
},
{
"maxItems": 50,
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"enum": [
"999--999",
"999-999"
]
},
{
"type": "string",
"pattern": "^[A-Z][0-9]{2}(\\.[0-9]+)?(-[A-Z][0-9]{2}(\\.[0-9]+)?)?$",
"description": "ICD-10 code or range."
}
],
"description": "One list entry: an ICD-10 code or range, or the withheld-cause marker."
},
"description": "A list of up to 50 entries, each in the single-value form, matched as a union: a death counts once when it matches any of them, so a code set such as X40–X44 plus X60–X64 is one series with one set of rates. Repeated entries are ignored. An empty list reads as omitted."
}
]
},
"mcd_icd10": {
"description": "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.",
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"enum": [
"999--999",
"999-999"
]
},
{
"type": "string",
"pattern": "^[A-Z][0-9]{2}(\\.[0-9]+)?(-[A-Z][0-9]{2}(\\.[0-9]+)?)?$",
"description": "ICD-10 code or range, same form as cause_icd10 — a chapter such as \"S00-T98\" (injury and poisoning, a chapter the underlying-cause finder does not list), a block such as \"J09-J18\" (influenza and pneumonia), or a single code such as \"T40.1\" (heroin)."
},
{
"maxItems": 50,
"type": "array",
"items": {
"anyOf": [
{
"type": "string",
"enum": [
"999--999",
"999-999"
]
},
{
"type": "string",
"pattern": "^[A-Z][0-9]{2}(\\.[0-9]+)?(-[A-Z][0-9]{2}(\\.[0-9]+)?)?$",
"description": "ICD-10 code or range."
}
],
"description": "One list entry: an ICD-10 code or range, or the withheld-cause marker."
},
"description": "A list of up to 50 entries, each in the single-value form, matched as a union: a death counts once when it matches any of them, so a code set such as X40–X44 plus X60–X64 is one series with one set of rates. Repeated entries are ignored. An empty list reads as omitted."
}
]
},
"sex": {
"default": "all",
"description": "Filter by sex.",
"type": "string",
"enum": [
"all",
"male",
"female"
]
},
"age_groups": {
"description": "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.",
"type": "array",
"items": {
"type": "string",
"enum": [
"1",
"1-4",
"5-14",
"15-24",
"25-34",
"35-44",
"45-54",
"55-64",
"65-74",
"75-84",
"85+",
"NS"
]
}
},
"year_range": {
"description": "Inclusive year range; from must not be later than to. Its bounds span every database; the selected one holds a narrower span, and a range outside it is rejected with that database's span named. Omit for all years the database holds.",
"type": "object",
"properties": {
"from": {
"type": "integer",
"minimum": 1999,
"maximum": 2026,
"description": "First year of the range."
},
"to": {
"type": "integer",
"minimum": 1999,
"maximum": 2026,
"description": "Last year of the range."
}
},
"required": [
"from",
"to"
]
},
"limit": {
"description": "Rows to return from the table CDC sent — any positive integer. 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. Omitted, it is 100 where this server stages tables for SQL (cdc_dataframe_query is listed), and otherwise the rest of the table from offset, up to 10,000 rows. WONDER's request carries no limit of its own, so every call fetches the whole table and returns a slice of it: the figures, caveats and messages are the same on every page, and a smaller page saves no time. Where tables are staged, a call at offset 0 that leaves rows past its page stages the whole table and names it in stagedTable, and cdc_dataframe_query reads the rest of it without another WONDER request; a call at a later offset stages nothing.",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"offset": {
"default": 0,
"description": "Index of the first row to return, for continuing past a previous call. Rows keep CDC's order, 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.",
"type": "integer",
"minimum": 0,
"maximum": 10000
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false
}