CDC WONDER API - Detailed Mortality Reference

CDC WONDER is a query tool from the Centers for Disease Control (CDC) that provides access to a collection of online databases for the analysis of public health data.

The following are a sampling of databases available through WONDER that provide vital statistics data through CDC's National Center for Health Statistics

• Births
• Detailed Mortality
• Compressed Mortality
• Multiple cause of death
• Infant Deaths

For this example, we will focus on the Detailed Mortality database, which provides number of deaths and death rates (crude or age-adjusted) for underlying cause of death at the national level (state and county restricted through API). Using the query tool, the user can select grouping and filtering variables that are used to generate a dataset. Results from the endpoint include a data table along with applicable footnotes and caveats, which can then be exported to a tab delimited file or visualized.

WONDER provides an API that allows the same queries to be issued through a HTTP POST request to WONDER's web server (no authentication required). Requests and responses are issued in XML format and are detailed in the API Documentation page. The documentation specifies that when running an automated query, the a limit of one query for every 2 minutes should be made to allow for good system recovery time.

Each XML request consists of a series of parameter tags with name and value children in the following format:

<request-parameters>
    <parameter>
        <name></name>
        <value></value>
    <parameter>
    ...
</request-parameters>

For examples of the format for the request and response, see the Example Request and Response section for detailed examples.

Available parameter names and values vary by database in WONDER. The WONDER API Documentation recommends viewing the HTML source for the web form in the query tool to access available parameter names and values. For convenience, parameter names and values are provided below.

Example XML Request and Response

1. U.S. national cancer deaths (ICD-10 codes C00-D48) by year and by race, for the 5 year time period 2009-2013. Number of deaths, population estimates, crude death rates and age-adjusted death rates per 100,000 persons, 95% confidence intervals and standard errors for age-adjusted death rates.
   • Example 1 Request
   • Example 1 Response
2. U.S. national injury deaths for persons age 18 and under, by Injury Intent and Injury Mechanism, for years 1999-2013. Number of deaths, population estimates, crude death rates.
   • Example 2 Request
   • Example 2 Response

Example Python Scripts

For Python examples of creating, sending, and processing a request, as well as running some basic visualizations, see https://github.com/alipphardt/cdc-wonder-api/blob/master/CDC%2BWONDER%2BAPI%2BExample.ipynb

Reference for All Request Parameters

• B - Group By Parameters
• M - Measure Parameters
• F/I/V Parameters
• O - Other Parameters
• VM - Values for non-standard age adjusted rates
• V - Variable Values
• Miscellaneous Parameters

B - Group By Parameters

Parameter Names:

• B_1
• B_2
• B_3
• B_4
• B_5

The following is a listing of available values for each parameter name in the format:

<value> - <description>

Location

• D76.V10-level1 - Census Region
• D76.V10-level2 - Census Division
• D76.V27-level1 - HHS Region
• D76.V9-level1 - State
• D76.V9-level2 - County
• D76.V19 - 2013 Urbanization
• D76.V11 - 2006 Urbanization

Demographics

• D76.V5 - Age Groups
• D76.V7 - Gender
• D76.V17 - Hispanic Origin
• D76.V8 - Race

Year and Month

• D76.V1-level1 - Year
• D76.V1-level2 - Month

Weekday, Autopsy, Place of Death

• D76.V24 - Weekday
• D76.V20 - Autopsy
• D76.V21 - Place of Death

Cause of Death

• D76.V28 - 15 Leading Causes of Death
• D76.V29 - 15 Leading Causes of Death (Infants)
• D76.V2-level1 ICD - Chapter
• D76.V2-level2 ICD - Sub-Chapter
• D76.V2-level3 - Cause of death
• D76.V4 - ICD-10 113 Cause List
• D76.V12 - ICD-10 130 Cause List (Infants)
• D76.V22 - Injury Intent
• D76.V23 - Injury Mechanism & All Other Leading Causes
• D76.V25 - Drug/Alcohol Induced Causes

M - Measure Parameters

Deaths, Population and Crude Rate are included by default. Additional measures may be added and are included below:

<name> - <value> - <description>

• M_1 - D76.M1 - Deaths
• M_2 - D76.M2 - Population
• M_3 - D76.M3 - Crude Rate
• M_31 - D76.M31 - Crude Rate Standard Error
• M_32 - D76.M32 - Crude 95% Confidence Interval
• M_4 - D76.M4 - Age-adjusted Rate
• M_41 - D76.M41 - Age-adjusted Rate Standard Error
• M_42 - D76.M42 - Age-adjusted Rate Confidence Interval
• M_9 - D76.M9 - Percent of Total Deaths

F/I/V Parameters

The Detailed Mortality database contains several variables that may take on one or more values and may be modified by F/I/V parameters

• D76.V1 - Year and Month
• D76.V10 - Census Regions
• D76.V2 - ICD-10 Codes
• D76.V27 - HHS Regions
• D76.V9 - States and Counties

D76.V1 - Year and Month

Available years in the Detailed Mortality database run from 1999 through 2015. Values for F/I/V parameters (F_D76.V1, I_D76.V1, V_D76.V1) follow this format:

• F - <year1> <year2>
  • Example: "2009 2010"
• I - <year> (<year>)
  • Example: "2009 (2009) 2010 (2010)"
• V - <year> (<year>)
  • Example: "2009 (2009) 2010 (2010)"

With month included, the following format is used (Month names map to two digit codes)

• F - <year1>/<month1> <year2>/<month2>
  • Example: "2009/01 2009/02"
• I - <year1>/<month1> (<month1 abbrev>., <year 1>) <year2>/<month2> (<month2 abbrev>., <year 2>)
  • Example: "2009/01 (Jan., 2009) 2010/02 (Feb., 2010)"
• V - <year1>/<month1> (<month1 abbrev>., <year 1>) <year2>/<month2> (<month2 abbrev>., <year 2>)
  • Example: "2009/01 (Jan., 2009) 2010/02 (Feb., 2010)"

To include all dates:

• F - *All*
• I - *All* (All Dates)
• V - *All* (All Dates)

D76.V10 - Census Regions

In keeping with the vital statistics policy for public data sharing, only national data are available for query by the API. Queries for mortality and births statistics from the National Vital Statistics System cannot limit or group results by any location field, such as Region, Division, State or County, or Urbanization (urbanization categories map to specific geographic counties).

• F_D76.V10 - "*All*"
• I_D76.V10 - "*All* (The United States)"
• V_D76.V10 - ""

D76.V2 - ICD-10 Codes

• *All* - *All* (All Causes of Death)
• A00-B99 - A00-B99 (Certain infectious and parasitic diseases)
• C00-D48 - C00-D48 (Neoplasms)
• D50-D89 - D50-D89 (Diseases of the blood and blood-forming organs and certain disorders involving the immune mechanism)
• E00-E88 - E00-E88 (Endocrine, nutritional and metabolic diseases)
• F01-F99 - F01-F99 (Mental and behavioural disorders)
• G00-G98 - G00-G98 (Diseases of the nervous system)
• H00-H57 - H00-H57 (Diseases of the eye and adnexa)
• H60-H93 - H60-H93 (Diseases of the ear and mastoid process)
• I00-I99 - I00-I99 (Diseases of the circulatory system)
• J00-J98 - J00-J98 (Diseases of the respiratory system)
• K00-K92 - K00-K92 (Diseases of the digestive system)
• L00-L98 - L00-L98 (Diseases of the skin and subcutaneous tissue)
• M00-M99 - M00-M99 (Diseases of the musculoskeletal system and connective tissue)
• N00-N98 - N00-N98 (Diseases of the genitourinary system)
• O00-O99 - O00-O99 (Pregnancy, childbirth and the puerperium)
• P00-P96 - P00-P96 (Certain conditions originating in the perinatal period)
• Q00-Q99 - Q00-Q99 (Congenital malformations, deformations and chromosomal abnormalities)
• R00-R99 - R00-R99 (Symptoms, signs and abnormal clinical and laboratory findings, not elsewhere classified)
• U00-U99 - U00-U99 (Codes for special purposes)
• V01-Y89 - V01-Y89 (External causes of morbidity and mortality)

D76.V27 - HHS Regions

In keeping with the vital statistics policy for public data sharing, only national data are available for query by the API. Queries for mortality and births statistics from the National Vital Statistics System cannot limit or group results by any location field, such as Region, Division, State or County, or Urbanization (urbanization categories map to specific geographic counties).

• F_D76.V27 - "*All*"
• I_D76.V27 - "*All* (The United States)"
• V_D76.V27 - ""

D76.V9 - State and County Codes

In keeping with the vital statistics policy for public data sharing, only national data are available for query by the API. Queries for mortality and births statistics from the National Vital Statistics System cannot limit or group results by any location field, such as Region, Division, State or County, or Urbanization (urbanization categories map to specific geographic counties).

• F_D76.V9 - "*All*"
• I_D76.V9 - "*All* (The United States)"
• V_D76.V9 - ""

O - Other Parameters

• O_V10fmode - Controls whether Census Regions pulls from regular (F) or advanced finder (V_) parameters
  • freg | fadv
• O_V1fmode - Controls whether Year and Month pulls from regular (F) or advanced finder (V_) parameters
  • freg | fadv
• O_V27fmode - Controls whether HHS Regions pulls from regular (F) or advanced finder (V_) parameters
  • freg | fadv
• O_V2fmode - Controls whether ICD Code pulls from regular (F) or advanced finder (V_) parameters
  • freg | fadv
• O_V9fmode - Controls whether State/County pulls from regular (F) or advanced finder (V_) parameters
  • freg | fadv
• O_aar
  • aar_none | aar_std | aar_nonstd
• O_aar_enable - Enable Age Adjusted Rate options. Set to true to allow for confidence interval and standard error options
  • true | false
• O_aar_CI - age adjusted rate 95% confidence interval
  • true | false
• O_aar_SE - age adjusted rate standard error
  • true | false
• O_age
  • D76.V5 - Ten-Year Age Groups
  • D76.V51 - Five-Year Age Groups
  • D76.V52 - Single-Year Age Groups
  • D76.V6 - Infant Age Groups
• O_title - description to display as a title with your results.
• O_rate_per - calculate rates per X people
  • 1000 | 10000 | 100000 | 1000000
• O_post_pops - Use archive rates (calculated with postcensal populations for 2001-2009)
  • true | false
• O_aar_nonstd - Use non-standard rates. If true, supply values for VM variables
  • true | false
• O_aar_pop - The year "2000 U.S. standard" is the default population selection for the calculation of age-adjusted rates. However, you can select other standard populations, or select specific population criteria to determine the age distribution ratios.
  • 0000 - 2000 U.S. Std Population
  • 1940 - 1940 U.S. Std Million
  • 1970 - 1970 U.S. Std Million
  • 2000 - 2000 U.S. Std Million
• O_location -
  • D76.V9 - States
  • D76.V10 - Census Regions
  • D76.V27 - HHS Regions
• O_javascript - Turn on if javascript is enabled. Default is off
  • off | on
• O_ucd - set which field to use for underlying cause of death
  • D76.V2 - ICD-10 Codes
  • D76.V12 - ICD-10 130 Cause List (Infants)
  • D76.V25 - Drug/Alcohol Induced Causes
  • D76.V4 - ICD-10 113 Cause List
  • D76.V22 - Injury Intent and Mechanism
• O_urban
  • D76.V19 - 2013 Urbanization
  • D76.V11 - 2006 Urbanization
• O_show_totals - show totals
  • true | false
• O_show_zeros - show zero values
  • true | false
• O_show_suppressed - show suppressed values
  • true | false
• O_precision - number of decimal places
  • <number between 0 and 9, inclusive>
• O_timeout - data access timeout in minutes
  • 60 - 1 minute
  • 120 - 2 minutes
  • 180 - 3 minutes
  • 240 - 4 minutes
  • 300 - 5 minutes
  • 360 - 6 minutes
  • 420 - 7 minutes
  • 480 - 8 minutes
  • 540 - 9 minutes
  • 600 - 10 minutes
  • 660 - 11 minutes
  • 720 - 12 minutes
  • 780 - 13 minutes
  • 840 - 14 minutes
  • 900 - 15 minutes

VM - Values for non-standard age adjusted rates

• Year - VM_D76.M6_D76.V1_S - All | list of years from 1999-2015 (inclusive)
• Gender - VM_D76.M6_D76.V7
  • F - Female
  • M - Male
• Hispanic Origin - VM_D76.M6_D76.V17
  • *All* - All Origins
  • 2135-2 - Hispanic or Latino
  • 2186-2 - Not Hispanic or Latino
  • NS - Not Stated
• Race - VM_D76.M6_D76.V8
  • *All* - All Races
  • 1002-5 - American Indian or Alaska Native
  • A-PI - Asian or Pacific Islander
  • 2054-5 - Black or African American
  • 2106-3 - White
• Location - VM_D76.M6_D76.V10

V - Variable Values

Variable values to limit in the "where" clause of the query, found in multiple select list boxes and advanced finder text entry boxes in the "Request Form."

• V_D76.V19 - 2013 Urbanization
  • *All* - All Categories
  • 1 - Large Central Metro
  • 2 - Large Fringe Metro
  • 3 - Medium Metro
  • 4 - Small Metro
  • 5 - Micropolitan (non-metro)
  • 6 - NonCore (non-metro)
• V_D76.V11 - 2006 Urbanization
  • *All* - All Categories
  • 1 - Large Central Metro
  • 2 - Large Fringe Metro
  • 3 - Medium Metro
  • 4 - Small Metro
  • 5 - Micropolitan (non-metro)
  • 6 - NonCore (non-metro)
• V_D76.V5 - Ten-Year Age Groups
  • *All* - All Ages
  • 1 - < 1 year
  • 1-4 - 1-4 years
  • 5-14 - 5-14 years
  • 15-24 - 15-24 years
  • 25-34 - 25-34 years
  • 35-44 - 35-44 years
  • 45-54 - 45-54 years
  • 55-64 - 55-64 years
  • 65-74 - 65-74 years
  • 75-84 - 75-84 years
  • 85+ - 85+ years
  • NS - Not Stated
• V_D76.V51 - Five-Year Age Groups
  • *All* - All Ages
  • 1 - < 1 year
  • 1-4 - 1-4 years
  • 5-9 - 5-9 years
  • 10-14 - 10-14 years
  • 15-19 - 15-19 years
  • 20-24 - 20-24 years
  • 25-29 - 25-29 years
  • 30-34 - 30-34 years
  • 35-39 - 35-39 years
  • 40-44 - 40-44 years
  • 45-49 - 45-49 years
  • 50-54 - 50-54 years
  • 55-59 - 55-59 years
  • 60-64 - 60-64 years
  • 65-69 - 65-69 years
  • 70-74 - 70-74 years
  • 75-79 - 75-79 years
  • 80-84 - 80-84 years
  • 85-89 - 85-89 years
  • 90-94 - 90-94 years
  • 95-99 - 95-99 years
  • 100+ - 100+ years
  • NS - Not Stated
• V_D76.V52 - Single-Year Age Groups
  • 0 - < 1 year
  • <Number between 1 and 99>
  • 100 - 100+ years
  • NS - Not Stated
• V_D76.V6 - Infant Age Groups
  • 00 - All Infant Ages
  • 1d - < 1 day
  • 1-6d - 1-6 days
  • 7-27d - 7-27 days
  • 28-364d - 28-364 days
• V_D76.V7 - Gender
  • F - Female
  • M - Male
• V_D76.V17 - Hispanic Origin
  • *All* - All Origins
  • 2135-2 - Hispanic or Latino
  • 2186-2 - Not Hispanic or Latino
  • NS - Not Stated
• V_D76.V8 - Race
  • *All* - All Races
  • 1002-5 - American Indian or Alaska Native
  • A-PI - Asian or Pacific Islander
  • 2054-5 - Black or African American
  • 2106-3 - White
• V_D76.V24 - Weekday
  • *All* - All Weekdays
  • 1 - Sunday
  • 2 - Monday
  • 3 - Tuesday
  • 4 - Wednesday
  • 5 - Thursday
  • 6 - Friday
  • 7 - Saturday
  • 9 - Unknown
• V_D76.V20 - Autopsy
  • *All* - All Values
  • N - No
  • Y - Yes
  • U - Unknown
• V_D76.V21 - Place of Death
  • *All* - All Places
  • 1 - Medical Facility - Inpatient
  • 2 - Medical Facility - Outpatient or ER
  • 3 - Medical Facility - Dead on Arrival
  • 10 - Medical Facility - Status unknown
  • 4 - Decedent's home
  • 5 - Hospice facility
  • 6 - Nursing home/long term care
  • 7 - Other
  • 9 - Place of death unknown

Miscellaneous Parameters

The following parameters should be included using the below name/value pairs.

• action-Send - Send
• finder-stage-D76.V1 - codeset
• finder-stage-D76.V1 - codeset
• finder-stage-D76.V2 - codeset
• finder-stage-D76.V27 - codeset
• finder-stage-D76.V9 - codeset
• stage - request