githubreadme <- TRUE
# DON'T MAKE ANY CHANGES -- edit vignettes/IntroVignette.Rmd instead
knitr::opts_chunk$set(fig.width = 4, fig.height = 3,
                      fig.align = 'center')


This package makes it easier to use the CDC Wonder API. It does so by employing hidden default query lists and lookup tables, allowing users to focus only on the variables they're interested in obtaining, and to write queries using human readable names rather than numeric codes.



mylist <- list(list("And By", "Gender"))
mydata0 <- getData(TRUE, "Detailed Mortality", mylist)
mydata0 %>% head()
mydata0 %>% head() %>% kable()

show_databases() displays available databases by name and code:


More databases will be added in the future.

The best way to become familiar with CDC Wonder API options is to use the web interface:, as the options available through the API are nearly identical. The greatest difference is that location variables are not available through the API.


This package is not on CRAN. It can be installed from Github with the devtools package:

devtools::install_github("socdataR/wonderapi", build_vignettes = TRUE)

(The vignettes are an important component of the package as the codebooks are stored as vignettes, so be sure to include build_vignettes = TRUE.)

Getting started

Queries are composed of parameter name-value pairs. Setting up a query without assistance is complex because the query must be submitted as an .xml file with a long list of required parameters, such as here (Example 1) and here (Example 2). The point of the package is to prevent your having to create requests in this form. It relies on the wondr package which creates converts R lists to xml and makes the query. The value of this package is in the "pre" and "post" stages of the query, that is, the processes of setting up the query and tidying the results.


Codebooks are provided as package vignettes to allow the user to conveniently look up the names and values of available parameters in each dataset. They may be accessed quickly by typing:

> ??codebook

in the console, or searching for "codebook" in the Help window. The codebooks are an important contribution of the package and are not provided by the CDC. They are generated automatically by this script, which scrapes the CDC Wonder web interface form, and displays parameter names and values in human readable form. The benefit of this method is the ability to quickly produce and update codebook vignettes that closely follow the web interface, with parameters appearing in the same order. It also means, however, that the codebooks contain more information than the typical user needs to submit a query. Most users will only need Group By variables (codes beginning with "B_"), Measures (codes beginning with "M_"), and Limiting Variables (codes beginning with "V_").

Although some of the parameter names are long and/or awkward, for the sake of consistency, we follow the CDC names exactly. The only exception is that any content that appears in parentheses should be dropped. For example, "Fertility Rate" can be substituted for "M_5", but "Fertility Rate (Census Region, Census Division, HHS Region, State, County, Year, Age of Mother, Race) cannot.

Default query lists and requests

To facilitate the process of designing a query list, this package relies on default query lists. Each default query is set to request a single Group By Results parameter, generally set to "Year". It is set to request the Measures that are listed as default Measures on the web interface (i.e. Births for the Births dataset; Deaths, Population and Crude Rate for the Detailed Mortality dataset.) To see the default settings, perform a query request without specifying a querylist:

natdata <- getData(TRUE, "Natality for 2007 - 2016")
natdata %>% head()
dmdata <- getData(TRUE, "Detailed Mortality")
dmdata %>% head()
natdata <- getData(TRUE, "Natality for 2007 - 2016")
natdata %>% head() %>% kable()
dmdata <- getData(TRUE, "Detailed Mortality")
dmdata %>% head() %>% kable()

The default lists were prepared based on CDC examples, but we make no claim that they are error free. If you have any suggestions for improving them, please make a pull request on Github or send an email to Joyce Robbins. The default lists are available here.

Creating customized queries

There are different types of parameters. Most critical are Group Results By and Measures. The Group Results By parameters serve as keys for grouping the data; the maximum number of Group Results By parameters is five. Limiting Variables may also be used to constrain results behind the scenes.

To make changes to the default list, first create a list of lists, wherein each nested list is a name-value pair. For example, the following changes the first (and currently only) "Group Results By" variable to Weekday:

mylist <- list(list("Group Results By", "Weekday"))
mydata <- getData(TRUE, "Detailed Mortality", mylist)
mydata %>% head()
mydata %>% head() %>% kable()

As the set up is slightly different depending on the parameter type, more details on setting up the name-value pairs by parameter types are provided below.

Group By variables

Each dataset allows for fixed number (5 or fewer) Group By variables, codes for which are "B_1", "B_2", "B_3", etc. "Group By Results" may be substituted for "B_1" and "And By" for "B_2". "And By" may not, however, be substituted for "B_3" on to avoid ambiguity (this may change in the future.) Values -- in this case, the Group By variables -- may be specified by code or human readable name. The following, thus, are equivalent:

## not run
mylist <- list(list("B_1", "D66.V2"))
mylist <- list(list("Group Results By", "Race"))
mylist <- list(list("B_1", "Race"))
mylist <- list(list("Group Results By", "D66.V2"))

See the appropriate codebook for all Group By options.


Measures do not need values; it is sufficient to specify a name only:

mylist <- list(list("Group Results By", "Marital Status"),
               list("And By", "Year"),
               list("Average Age of Mother", ""))
mydata2 <- getData(TRUE, "Natality for 2007 - 2016", mylist)
mydata2 %>% head()
mydata2 %>% head() %>% kable()

Limiting variables

Queries can be constrained with parameters that limit results in the background. For example, if you're only interested in February births, you may choose to limit results to February as follows, rather than grouping by Month:

mylist <- list(list("Month", "2"))
getData(TRUE, "D66", mylist)

Note that values for Limiting Variables must be entered as codes; in this case "2" rather than "February." We hope to add capability for human readable values in the future.

Plotting query results

By returning a tidy data frame, the query results are ready to be plotted without any additional data manipulation:

ggplot(mydata2, aes(x = Year, y = Births, color = `Marital Status`)) +
    geom_line() + ggtitle("Births by Marital Status")
ggplot(mydata2, aes(x = Year, y = `Average Age of Mother`,
                   color = `Marital Status`)) + geom_line() +
    geom_point() + ylab("age (in years)") + 
    ggtitle("Average Age of Mother")
mydata2 <- mydata2 %>% 
    select(-`Average Age of Mother`) %>% 
    spread(key = `Marital Status`, value = `Births`) %>% 
    mutate(Total = Married + Unmarried)
ggplot(mydata2, aes(x = Year, y = Unmarried / Total)) + geom_line() +
    geom_point() + ggtitle("Births to Unmarried Mothers") +
    ylab("Percent of Total Births")

Combining results from multiple datasets

Some of the datasets, such as the Births, are divided into multiple databases by time period. wonderapi makes it easy to combine the data into one data frame. (Care needs to be taken as the variables are not identical in all. For example, the 1995 - 2002 dataset does not have any measure options; it only returns number of births. To find out what's available, see the codebooks (>??codebook) and crosscheck with the CDC Wonder API web interface.)

births <- rbind(getData(TRUE, "Natality for 1995 - 2002"),
                getData(TRUE, "Natality for 2003 - 2006"),
                getData(TRUE, "Natality for 2007 - 2016"))
ggplot(births, aes(Year, Births)) + geom_line() + 
    ggtitle("U.S. Births by Year, 1995 - 2016")


The main source of errors is improper query requests. The wonderapi has limited ability to catch problems before the query request is made. It checks the list of parameter names and will reject the name-value pair if the name, either in code or human readable form, is not recognized. (Checking for value problems will be added in the future.) Here is an example of an unrecognized parameter name:

mydata3 <- getData(TRUE, "Detailed Mortality", 
        list(list("Suspect", "Mrs. Peacock")))
mydata3 %>% head()
mydata3 %>% head() %>% kable()

Errors due to the constraints of the CDC Wonder API are more difficult to catch since there are many quirky rules and it is currently beyond the scope of this package to check for them. The following, for example, appears to be a reasonable request, but results in an error:

mylist <- list(list("And By", "Education"), 
               list("Birth Rate", ""))
mydata4 <- getData(TRUE, "Natality for 2007 - 2016", mylist)

In this case, the best approach is to visit the CDC Wonder API web interface and try the same query. If all goes well, you will receive more detailed information on what went wrong:

We learn that we can't include "Education" if we request the "Birth Rate" measure. If we try again with "Bridged Race" instead of "Education", it works:

mylist <- list(list("And By", "Bridged Race"), 
               list("Birth Rate", ""))
mydata5 <- getData(TRUE, "Natality for 2007 - 2016", mylist)
mydata5 %>% head()
mydata5 %>% head() %>% kable()

socdataR/wonderapi documentation built on Oct. 31, 2018, 2:17 p.m.