<!--
  %\VignetteEngine{knitr}
%\VignetteIndexEntry{e) Mapping Census Data}
-->
  
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)](https://www.census.gov/acs/www/). Internally it uses the acs package to get the data.  

choroplethr has four functions for working with ACS data:

1. `?get_acs_data`
1. `?state_choroplethr_acs` 
2. `?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](http://api.census.gov/data/key_signup.html). 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](https://www.census.gov/programs-surveys/acs/methodology/questionnaire-archive.html) the list of questions the ACS asks.  
1.  [Learn](http://www.census.gov/programs-surveys/acs/guidance/estimates.html) about the difference between the 1, 3 and 5 year estimates.
2. [Select](http://factfinder2.census.gov/faces/help/jsf/pages/metadata.xhtml?lang=en&type=survey&id=survey.en.ACS_ACS) a survey to visualize.
3. [Select](http://factfinder2.census.gov/faces/help/jsf/pages/metadata.xhtml?lang=en&type=dataset&id=dataset.en.ACS_12_5YR) 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.

```{r}
# state_choropleth_acs("B01003", endyear=2012, span=5)
```
![](https://raw.githubusercontent.com/trulia/choroplethr/master/wiki-images/v20/acs-example.png)