# Mapping US Census Data

choroplethr provides native support for creating choropleths from US Census data. Note that the Census Bureau has many datasets; currently choroplethr only works with data from the American Community Survey (ACS). Internally it uses the acs package to get the data.

choroplethr has four functions for working with ACS data:

1. `?get_acs_data`
2. `?state_choroplethr_acs`
3. `?county_choropleth_acs`

## Census API Key

To use these functions you must get and install a Census API. It is free and you can get one here. Then type the following from R:

    library(acs);
    api.key.install('<your census api key>');

Note that the Census API currently only provides ACS data from 2010 onwards.

## Navigating ACS Data

Here are some tips for getting started with ACS data:

1. Browse the list of questions the ACS asks.
2. Learn about the difference between the 1, 3 and 5 year estimates.
3. Select a survey to visualize.
4. Select a table to visualize. When you click thru to a particular survey, you will likely be surprised at just how much data is available. Here are some popular tables to gets you started:
   - B01003: total population
   - B01002: median age by sex
   - B19001: household income in the last 12 months

## Example

Here is how to view population estimates for each state from the 2012 5-year ACS. Notice that the title is automatically created for you from the name of the table. Note that it is commented out because CRAN's servers do not have a US Census API key installed.

    # state_choropleth_acs("B01003", endyear=2012, span=5)