The package saipeAPI provides an R client for Census Bureau’s API for
Small Area Income and Poverty Estimates (SAIPE).
Here is a short introduction for the SAIPE program from
Census:
The Small Area Income and Poverty Estimates (SAIPE) program produces single-year estimates of median household income and poverty for states and all counties, as well as population and poverty estimates for school districts. Since SAIPE estimates combine ACS data with administrative and other data, SAIPE estimates generally have lower variance than ACS estimates but are released later because they incorporate ACS data in the models. For counties and school districts, particularly those with populations below 65,000, the SAIPE program provides the most accurate subnational estimates of poverty. For counties, SAIPE generally provides the best single-year estimates of median household income.
# install.packages("remotes")
remotes::install_github("jjchern/saipeAPI@v0.0.3")saipeAPI have three functions that return SAIPE data at different
geographic level:
saipeAPI::saipe_us()
saipeAPI::saipe_state()
saipeAPI::saipe_county()Census’s SAIPE has four levels of income and poverty estimates: us, state, county, and school district.
Available Years (Source)
- State and County: 1989, 1993, 1995–2017
- School Districts: 1995, 1997, 1999–2017
Available Variables (Source)
#> Warning: package 'dplyr' was built under R version 3.4.4
| Name | Label |
|---|---|
| COUNTY | County FIPS Code |
| GEOID | State+County FIPS Code |
| NAME | State or County Name |
| SAEMHI_LB90 | Median Household Income Lower Bound for 90% Confidence Interval |
| SAEMHI_MOE | Median Household Income Margin of Error |
| SAEMHI_PT | Median Household Income Estimate |
| SAEMHI_UB90 | Median Household Income Upper Bound for 90% Confidence Interval |
| SAEPOV0_17_LB90 | Ages 0-17 in Poverty, Count Lower Bound 90% Confidence Interval |
| SAEPOV0_17_MOE | Ages 0-17 in Poverty, Count Margin of Error |
| SAEPOV0_17_PT | Ages 0-17 in Poverty, Count Estimate |
| SAEPOV0_17_UB90 | Ages 0-17 in Poverty, Count Upper Bound for 90% Confidence Interval |
| SAEPOV0_4_LB90 | Ages 0-4 in Poverty, Count Lower Bound for 90% Confidence Interval |
| SAEPOV0_4_MOE | Ages 0-4 in Poverty, Count Margin of Error |
| SAEPOV0_4_PT | Ages 0-4 in Poverty, Count Estimate |
| SAEPOV0_4_UB90 | Ages 0-4 in Poverty, Count Upper Bound for 90% Confidence Interval |
| SAEPOV5_17R_LB90 | Ages 5-17 in Families in Poverty, Count Lower Bound for 90% Confidence Interval |
| SAEPOV5_17R_MOE | Ages 5-17 in Families in Poverty, Count Margin of Error |
| SAEPOV5_17R_PT | Ages 5-17 in Families in Poverty, Count Estimate |
| SAEPOV5_17R_UB90 | Ages 5-17 in Families in Poverty, Count Upper Bound for 90% Confidence Interval |
| SAEPOVALL_LB90 | All ages in Poverty, Count Lower Bound for 90% Confidence Interval |
| SAEPOVALL_MOE | All ages in Poverty, Count Margin of Error |
| SAEPOVALL_PT | All ages in Poverty, Count Estimate |
| SAEPOVALL_UB90 | All ages in Poverty, Count Upper Bound for 90% Confidence Interval |
| SAEPOVRT0_17_LB90 | Ages 0-17 in Poverty, Rate Lower Bound for 90% Confidence Interval |
| SAEPOVRT0_17_MOE | Ages 0-17 in Poverty, Rate Margin of Error |
| SAEPOVRT0_17_PT | Ages 0-17 in Poverty, Rate Estimate |
| SAEPOVRT0_17_UB90 | Ages 0-17 in Poverty, Rate Upper Bound for 90% Confidence Interval |
| SAEPOVRT0_4_LB90 | Ages 0-4 in Poverty, Rate Lower Bound for 90% Confidence Interval |
| SAEPOVRT0_4_MOE | Ages 0-4 in Poverty, Rate Margin of Error |
| SAEPOVRT0_4_PT | Ages 0-4 in Poverty, Rate Estimate |
| SAEPOVRT0_4_UB90 | Ages 0-4 in Poverty, Rate Upper Bound for 90% Confidence Interval |
| SAEPOVRT5_17R_LB90 | Ages 5-17 in Families in Poverty, Rate Lower Bound for 90% Confidence Interval |
| SAEPOVRT5_17R_MOE | Ages 5-17 in Families in Poverty, Rate Margin of Error |
| SAEPOVRT5_17R_PT | Ages 5-17 in Families in Poverty, Rate Estimate |
| SAEPOVRT5_17R_UB90 | Ages 5-17 in Families in Poverty, Rate Upper Bound for 90% Confidence Interval |
| SAEPOVRTALL_LB90 | All ages in Poverty, Rate Lower Bound for 90% Confidence Interval |
| SAEPOVRTALL_MOE | All ages in Poverty, Rate Margin of Error |
| SAEPOVRTALL_PT | All ages in Poverty, Rate Estimate |
| SAEPOVRTALL_UB90 | All ages in Poverty, Rate Upper Bound for 90% Confidence Interval |
| SAEPOVU_0_17 | Ages 0-17 in Poverty Universe |
| SAEPOVU_0_4 | Ages 0-4 in Poverty Universe |
| SAEPOVU_5_17R | Ages 5-17r in Poverty Universe |
| SAEPOVU_ALL | All Ages in Poverty Universe |
| STABREV | Two-letter State Postal abbreviation |
| STATE | FIPS State Code |
| SUMLEV | Summary Level |
| YEAR | Estimate Year |
Obtain an API key from the U.S. Census Bureau at
http://api.census.gov/data/key_signup.html. After that, set your API
key with the function saipeAPI::set_api_key(), and then start calling
the data retrieval functions.
You can also save your API key in the .Renviron file for future usage.
First, open the .Renviron file by
# install.packages("usethis")
usethis::edit_r_environ()Save your key in the file in the format of
saipe_key='<Your API Key Here>'Reload the .Renviron file and check if the key can be assessed:
readRenviron("~/.Renviron")
Sys.getenv("saipe_key")# saipe::set_api_key("<Your API Key Here>")
saipeAPI::saipe_us(year = 2010:2017, var = c("NAME", "SAEMHI_PT", "SAEPOVRTALL_PT"))
#> # A tibble: 8 x 5
#> NAME SAEMHI_PT SAEPOVRTALL_PT time us
#> <chr> <dbl> <dbl> <dbl> <chr>
#> 1 United States 50046 15.3 2010 00
#> 2 United States 50502 15.9 2011 00
#> 3 United States 51371 15.9 2012 00
#> 4 United States 52250 15.8 2013 00
#> 5 United States 53657 15.5 2014 00
#> 6 United States 55775 14.7 2015 00
#> 7 United States 57617 14 2016 00
#> 8 United States 60336 13.4 2017 00# saipe::set_api_key("<Your API Key Here>")
saipeAPI::saipe_state(year = 2010:2017, var = c("NAME", "SAEMHI_PT", "SAEPOVRTALL_PT"))
#> # A tibble: 408 x 5
#> NAME SAEMHI_PT SAEPOVRTALL_PT time state
#> <chr> <dbl> <dbl> <dbl> <chr>
#> 1 Georgia 46252 18 2010 13
#> 2 Alabama 40538 18.9 2010 01
#> 3 Alaska 63456 11 2010 02
#> 4 Arizona 46787 17.6 2010 04
#> 5 Arkansas 38413 18.7 2010 05
#> 6 California 57664 15.8 2010 06
#> 7 Colorado 54411 13.2 2010 08
#> 8 Connecticut 64321 10.1 2010 09
#> 9 Delaware 56172 11.9 2010 10
#> 10 District of Columbia 60729 18.8 2010 11
#> # … with 398 more rows# saipe::set_api_key("<Your API Key Here>")
saipeAPI::saipe_county(year = 2017, var = c("NAME", "SAEMHI_PT", "SAEPOVRTALL_PT"))
#> # A tibble: 3,142 x 6
#> NAME SAEMHI_PT SAEPOVRTALL_PT time state county
#> <chr> <dbl> <dbl> <dbl> <chr> <chr>
#> 1 Yukon-Koyukuk Census Area 37907 23.2 2017 02 290
#> 2 Apache County 33053 33.1 2017 04 001
#> 3 Cochise County 48966 16.1 2017 04 003
#> 4 Coconino County 54399 18.4 2017 04 005
#> 5 Gila County 38897 24.1 2017 04 007
#> 6 Graham County 46378 20.9 2017 04 009
#> 7 Greenlee County 63557 10.1 2017 04 011
#> 8 La Paz County 36389 20.9 2017 04 012
#> 9 Maricopa County 62221 13.5 2017 04 013
#> 10 Mohave County 42210 17.3 2017 04 015
#> # … with 3,132 more rows# The pacakge contains a data frame that shows possible variables and variable labels
saipeAPI::saipe_vars
#> # A tibble: 47 x 9
#> Name Label Concept Required Attributes Limit `Predicate Type` Group
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 COUN… Coun… Select… not req… "" 0 (not a predicat… N/A
#> 2 GEOID Stat… Geogra… not req… "" 0 (not a predicat… N/A
#> 3 NAME Stat… Geogra… not req… "" 0 (not a predicat… N/A
#> 4 SAEM… Medi… Uncert… not req… "" 0 int N/A
#> 5 SAEM… Medi… Uncert… not req… "" 0 int N/A
#> 6 SAEM… Medi… Estima… not req… "" 0 int N/A
#> 7 SAEM… Medi… Uncert… not req… "" 0 int N/A
#> 8 SAEP… Ages… Uncert… not req… "" 0 int N/A
#> 9 SAEP… Ages… Uncert… not req… "" 0 int N/A
#> 10 SAEP… Ages… Estima… not req… "" 0 int N/A
#> # … with 37 more rows, and 1 more variable: Values <chr>
# To get a vector of all possible variables
saipeAPI::saipe_vars$Name
#> [1] "COUNTY" "GEOID" "NAME"
#> [4] "SAEMHI_LB90" "SAEMHI_MOE" "SAEMHI_PT"
#> [7] "SAEMHI_UB90" "SAEPOV0_17_LB90" "SAEPOV0_17_MOE"
#> [10] "SAEPOV0_17_PT" "SAEPOV0_17_UB90" "SAEPOV0_4_LB90"
#> [13] "SAEPOV0_4_MOE" "SAEPOV0_4_PT" "SAEPOV0_4_UB90"
#> [16] "SAEPOV5_17R_LB90" "SAEPOV5_17R_MOE" "SAEPOV5_17R_PT"
#> [19] "SAEPOV5_17R_UB90" "SAEPOVALL_LB90" "SAEPOVALL_MOE"
#> [22] "SAEPOVALL_PT" "SAEPOVALL_UB90" "SAEPOVRT0_17_LB90"
#> [25] "SAEPOVRT0_17_MOE" "SAEPOVRT0_17_PT" "SAEPOVRT0_17_UB90"
#> [28] "SAEPOVRT0_4_LB90" "SAEPOVRT0_4_MOE" "SAEPOVRT0_4_PT"
#> [31] "SAEPOVRT0_4_UB90" "SAEPOVRT5_17R_LB90" "SAEPOVRT5_17R_MOE"
#> [34] "SAEPOVRT5_17R_PT" "SAEPOVRT5_17R_UB90" "SAEPOVRTALL_LB90"
#> [37] "SAEPOVRTALL_MOE" "SAEPOVRTALL_PT" "SAEPOVRTALL_UB90"
#> [40] "SAEPOVU_0_17" "SAEPOVU_0_4" "SAEPOVU_5_17R"
#> [43] "SAEPOVU_ALL" "STABREV" "STATE"
#> [46] "SUMLEV" "YEAR"
# To get a vector of all possible years
saipeAPI::saipe_years
#> [1] 1989 1993 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006
#> [15] 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017
# Use the above two vectors to download all the US-level data
saipeAPI::saipe_us(year = saipeAPI::saipe_years, var = saipeAPI::saipe_vars$Name)
#> # A tibble: 25 x 49
#> COUNTY GEOID NAME SAEMHI_LB90 SAEMHI_MOE SAEMHI_PT SAEMHI_UB90
#> <chr> <chr> <chr> <dbl> <dbl> <dbl> <dbl>
#> 1 000 00000 Unit… 28644 262 28906 29168
#> 2 000 00000 Unit… 31001 240 31241 31481
#> 3 000 00000 Unit… 33752 324 34076 34400
#> 4 000 00000 Unit… 35198 294 35492 35786
#> 5 000 00000 Unit… 36724 281 37005 37286
#> 6 000 00000 Unit… 38507 378 38885 39263
#> 7 000 00000 Unit… 40383 313 40696 41009
#> 8 000 00000 Unit… 41773 217 41990 42207
#> 9 000 00000 Unit… 42016 212 42228 42440
#> 10 000 00000 Unit… 42180 229 42409 42638
#> # … with 15 more rows, and 42 more variables: SAEPOV0_17_LB90 <dbl>,
#> # SAEPOV0_17_MOE <dbl>, SAEPOV0_17_PT <dbl>, SAEPOV0_17_UB90 <dbl>,
#> # SAEPOV0_4_LB90 <dbl>, SAEPOV0_4_MOE <dbl>, SAEPOV0_4_PT <dbl>,
#> # SAEPOV0_4_UB90 <dbl>, SAEPOV5_17R_LB90 <dbl>, SAEPOV5_17R_MOE <dbl>,
#> # SAEPOV5_17R_PT <dbl>, SAEPOV5_17R_UB90 <dbl>, SAEPOVALL_LB90 <dbl>,
#> # SAEPOVALL_MOE <dbl>, SAEPOVALL_PT <dbl>, SAEPOVALL_UB90 <dbl>,
#> # SAEPOVRT0_17_LB90 <dbl>, SAEPOVRT0_17_MOE <dbl>,
#> # SAEPOVRT0_17_PT <dbl>, SAEPOVRT0_17_UB90 <dbl>,
#> # SAEPOVRT0_4_LB90 <dbl>, SAEPOVRT0_4_MOE <dbl>, SAEPOVRT0_4_PT <dbl>,
#> # SAEPOVRT0_4_UB90 <dbl>, SAEPOVRT5_17R_LB90 <dbl>,
#> # SAEPOVRT5_17R_MOE <dbl>, SAEPOVRT5_17R_PT <dbl>,
#> # SAEPOVRT5_17R_UB90 <dbl>, SAEPOVRTALL_LB90 <dbl>,
#> # SAEPOVRTALL_MOE <dbl>, SAEPOVRTALL_PT <dbl>, SAEPOVRTALL_UB90 <dbl>,
#> # SAEPOVU_0_17 <dbl>, SAEPOVU_0_4 <dbl>, SAEPOVU_5_17R <dbl>,
#> # SAEPOVU_ALL <dbl>, STABREV <chr>, STATE <chr>, SUMLEV <chr>,
#> # YEAR <dbl>, time <dbl>, us <chr>- Add school district functions