Retrieve Census data from a given API
Usage
getCensus(
name,
vintage = NULL,
key = NULL,
vars,
region = NULL,
regionin = NULL,
time = NULL,
show_call = FALSE,
convert_variables = TRUE,
year = NULL,
date = NULL,
period = NULL,
monthly = NULL,
category_code = NULL,
data_type_code = NULL,
naics = NULL,
pscode = NULL,
naics2012 = NULL,
naics2007 = NULL,
naics2002 = NULL,
naics1997 = NULL,
sic = NULL,
...
)Arguments
- name
The programmatic name of your dataset, e.g. "timeseries/poverty/saipe" or "acs/acs5". Use listCensusApis() to see valid dataset names. Required.
- vintage
Vintage (year) of dataset, e.g. 2014. Not required for timeseries APIs.
- key
A Census API key, obtained at https://api.census.gov/data/key_signup.html. If you have a
CENSUS_KEYorCENSUS_API_KEYstored in your .Renviron file, getCensus() will automatically use that key. Using a key is recommended but not required.- vars
List of variables to get. Required.
- region
Geography to get.
- regionin
Optional hierarchical geography to limit region.
- time
Time period of data to get. Required for most timeseries APIs.
- show_call
Display the underlying API call that was sent to the Census Bureau. Default is FALSE.
- convert_variables
Convert columns that are likely numbers into numeric data. Default is TRUE. If false, all columns will be characters, which is the type returned by the Census Bureau.
- year, date, period, monthly, category_code, data_type_code, naics, pscode, naics2012, naics2007, naics2002, naics1997, sic
Optional arguments used in some timeseries data APIs.
- ...
Other valid arguments to pass to the Census API. Note: the APIs are case sensitive.
Examples
# Get total population and median household income for Census places
# (cities, towns, villages) in a single state from the 5-year American Community Survey.
acs_simple <- getCensus(
name = "acs/acs5",
vintage = 2022,
vars = c("NAME", "B01001_001E", "B19013_001E"),
region = "place:*",
regionin = "state:01")
head(acs_simple)
#> state place NAME B01001_001E B19013_001E
#> 1 01 00100 Abanda CDP, Alabama 335 29263
#> 2 01 00124 Abbeville city, Alabama 2309 35147
#> 3 01 00460 Adamsville city, Alabama 4325 58631
#> 4 01 00484 Addison town, Alabama 665 47188
#> 5 01 00676 Akron town, Alabama 310 53929
#> 6 01 00820 Alabaster city, Alabama 33417 89423
# Get all data from the B08301 variable group, "Means of Transportation to Work."
# This returns estimates as well as margins of error and annotation flags.
acs_group <- getCensus(
name = "acs/acs5",
vintage = 2022,
vars = "group(B08301)",
region = "state:*")
head(acs_group)
#> state B08301_001E B08301_001EA B08301_001M B08301_001MA B08301_002E
#> 1 01 2183677 <NA> 9550 <NA> 1985736
#> 2 02 351067 <NA> 2187 <NA> 274263
#> 3 04 3244419 <NA> 9451 <NA> 2610395
#> 4 05 1304084 <NA> 6929 <NA> 1177402
#> 5 06 18353469 <NA> 22043 <NA> 14313290
#> 6 08 3006848 <NA> 8149 <NA> 2304559
#> B08301_002EA B08301_002M B08301_002MA B08301_003E B08301_003EA B08301_003M
#> 1 <NA> 10017 <NA> 1808631 <NA> 9646
#> 2 <NA> 2820 <NA> 231484 <NA> 3143
#> 3 <NA> 12006 <NA> 2285920 <NA> 12162
#> 4 <NA> 6616 <NA> 1051964 <NA> 6428
#> 5 <NA> 23546 <NA> 12561068 <NA> 25223
#> 6 <NA> 9026 <NA> 2062480 <NA> 8986
#> B08301_003MA B08301_004E B08301_004EA B08301_004M B08301_004MA B08301_005E
#> 1 <NA> 177105 <NA> 4751 <NA> 137578
#> 2 <NA> 42779 <NA> 2105 <NA> 32397
#> 3 <NA> 324475 <NA> 5200 <NA> 242556
#> 4 <NA> 125438 <NA> 3531 <NA> 94684
#> 5 <NA> 1752222 <NA> 14058 <NA> 1269237
#> 6 <NA> 242079 <NA> 5338 <NA> 180493
#> B08301_005EA B08301_005M B08301_005MA B08301_006E B08301_006EA B08301_006M
#> 1 <NA> 4204 <NA> 24358 <NA> 1675
#> 2 <NA> 1886 <NA> 5712 <NA> 684
#> 3 <NA> 4612 <NA> 48889 <NA> 1844
#> 4 <NA> 2975 <NA> 18415 <NA> 1284
#> 5 <NA> 10568 <NA> 281935 <NA> 5811
#> 6 <NA> 4522 <NA> 37353 <NA> 1984
#> B08301_006MA B08301_007E B08301_007EA B08301_007M B08301_007MA B08301_008E
#> 1 <NA> 8791 <NA> 1005 <NA> 2998
#> 2 <NA> 2977 <NA> 646 <NA> 1039
#> 3 <NA> 18286 <NA> 1327 <NA> 10171
#> 4 <NA> 7226 <NA> 913 <NA> 2976
#> 5 <NA> 109445 <NA> 3668 <NA> 61640
#> 6 <NA> 14757 <NA> 1317 <NA> 6621
#> B08301_008EA B08301_008M B08301_008MA B08301_009E B08301_009EA B08301_009M
#> 1 <NA> 551 <NA> 3380 <NA> 602
#> 2 <NA> 255 <NA> 654 <NA> 256
#> 3 <NA> 1062 <NA> 4573 <NA> 689
#> 4 <NA> 636 <NA> 2137 <NA> 354
#> 5 <NA> 2554 <NA> 29965 <NA> 1345
#> 6 <NA> 758 <NA> 2855 <NA> 496
#> B08301_009MA B08301_010E B08301_010EA B08301_010M B08301_010MA B08301_011E
#> 1 <NA> 6982 <NA> 910 <NA> 6523
#> 2 <NA> 3805 <NA> 603 <NA> 3415
#> 3 <NA> 40113 <NA> 2078 <NA> 35607
#> 4 <NA> 3744 <NA> 551 <NA> 3387
#> 5 <NA> 662772 <NA> 7190 <NA> 423288
#> 6 <NA> 63953 <NA> 2586 <NA> 45745
#> B08301_011EA B08301_011M B08301_011MA B08301_012E B08301_012EA B08301_012M
#> 1 <NA> 928 <NA> 122 <NA> 117
#> 2 <NA> 577 <NA> 1 <NA> 3
#> 3 <NA> 1989 <NA> 960 <NA> 238
#> 4 <NA> 494 <NA> 114 <NA> 97
#> 5 <NA> 5639 <NA> 140862 <NA> 3435
#> 6 <NA> 2229 <NA> 4035 <NA> 418
#> B08301_012MA B08301_013E B08301_013EA B08301_013M B08301_013MA B08301_014E
#> 1 <NA> 77 <NA> 55 <NA> 73
#> 2 <NA> 15 <NA> 23 <NA> 14
#> 3 <NA> 471 <NA> 198 <NA> 2692
#> 4 <NA> 2 <NA> 5 <NA> 59
#> 5 <NA> 58487 <NA> 2233 <NA> 28260
#> 6 <NA> 2546 <NA> 416 <NA> 11234
#> B08301_014EA B08301_014M B08301_014MA B08301_015E B08301_015EA B08301_015M
#> 1 <NA> 95 <NA> 187 <NA> 100
#> 2 <NA> 15 <NA> 360 <NA> 176
#> 3 <NA> 455 <NA> 383 <NA> 143
#> 4 <NA> 51 <NA> 182 <NA> 170
#> 5 <NA> 1506 <NA> 11875 <NA> 985
#> 6 <NA> 864 <NA> 393 <NA> 164
#> B08301_015MA B08301_016E B08301_016EA B08301_016M B08301_016MA B08301_017E
#> 1 <NA> 1253 <NA> 321 <NA> 1878
#> 2 <NA> 1599 <NA> 368 <NA> 474
#> 3 <NA> 6508 <NA> 836 <NA> 10036
#> 4 <NA> 603 <NA> 202 <NA> 1278
#> 5 <NA> 37588 <NA> 1610 <NA> 46193
#> 6 <NA> 2955 <NA> 510 <NA> 4587
#> B08301_017EA B08301_017M B08301_017MA B08301_018E B08301_018EA B08301_018M
#> 1 <NA> 307 <NA> 1805 <NA> 302
#> 2 <NA> 127 <NA> 2447 <NA> 414
#> 3 <NA> 824 <NA> 19629 <NA> 1240
#> 4 <NA> 269 <NA> 2052 <NA> 380
#> 5 <NA> 1803 <NA> 135240 <NA> 3079
#> 6 <NA> 503 <NA> 30681 <NA> 1435
#> B08301_018MA B08301_019E B08301_019EA B08301_019M B08301_019MA B08301_020E
#> 1 <NA> 24058 <NA> 1737 <NA> 16559
#> 2 <NA> 27039 <NA> 1177 <NA> 13159
#> 3 <NA> 54751 <NA> 2254 <NA> 40263
#> 4 <NA> 19571 <NA> 1110 <NA> 11443
#> 5 <NA> 437430 <NA> 5563 <NA> 220114
#> 6 <NA> 79574 <NA> 2429 <NA> 24630
#> B08301_020EA B08301_020M B08301_020MA B08301_021E B08301_021EA B08301_021M
#> 1 <NA> 1341 <NA> 145406 <NA> 4523
#> 2 <NA> 672 <NA> 28281 <NA> 1635
#> 3 <NA> 2081 <NA> 462724 <NA> 7442
#> 4 <NA> 1050 <NA> 87991 <NA> 2781
#> 5 <NA> 4380 <NA> 2500842 <NA> 15830
#> 6 <NA> 1187 <NA> 495909 <NA> 6033
#> B08301_021MA GEO_ID NAME
#> 1 <NA> 0400000US01 Alabama
#> 2 <NA> 0400000US02 Alaska
#> 3 <NA> 0400000US04 Arizona
#> 4 <NA> 0400000US05 Arkansas
#> 5 <NA> 0400000US06 California
#> 6 <NA> 0400000US08 Colorado
# Retreive 2020 Decennial Census block group data within a specific Census tract,
# using the regionin argument to precisely specify the Census tract, county,
# and state.
decennial_block_group <- getCensus(
name = "dec/dhc",
vintage = 2020,
vars = c("NAME", "P1_001N"),
region = "block group:*",
regionin = "state:36+county:027+tract:220300")
head(decennial_block_group)
#> state county tract block_group
#> 1 36 027 220300 1
#> 2 36 027 220300 2
#> 3 36 027 220300 3
#> 4 36 027 220300 4
#> NAME P1_001N
#> 1 Block Group 1; Census Tract 2203; Dutchess County; New York 1467
#> 2 Block Group 2; Census Tract 2203; Dutchess County; New York 1394
#> 3 Block Group 3; Census Tract 2203; Dutchess County; New York 1192
#> 4 Block Group 4; Census Tract 2203; Dutchess County; New York 885
# Get poverty rates for children and for people of all ages beginning in 2000 using the
# Small Area Income and Poverty Estimates API
saipe <- getCensus(
name = "timeseries/poverty/saipe",
vars = c("NAME", "SAEPOVRT0_17_PT", "SAEPOVRTALL_PT"),
region = "state:01",
time = "from 2000")
head(saipe)
#> time state NAME SAEPOVRT0_17_PT SAEPOVRTALL_PT
#> 1 2000 01 Alabama 20.5 14.6
#> 2 2001 01 Alabama 22.1 15.7
#> 3 2002 01 Alabama 21.6 15.4
#> 4 2003 01 Alabama 22.3 15.3
#> 5 2004 01 Alabama 22.6 16.1
#> 6 2005 01 Alabama 24.3 16.9
# Get the number of employees and number of establishments in the construction sector,
# NAICS2017 code 23, using the County Business Patterns API
cbp <- getCensus(
name = "cbp",
vintage = 2021,
vars = c("EMP", "ESTAB", "NAICS2017_LABEL"),
region = "county:*",
NAICS2017 = 23)
head(cbp)
#> state county EMP ESTAB NAICS2017_LABEL NAICS2017
#> 1 01 001 507 90 Construction 23
#> 2 01 003 4322 705 Construction 23
#> 3 01 005 75 20 Construction 23
#> 4 01 007 654 25 Construction 23
#> 5 01 009 592 118 Construction 23
#> 6 01 011 50 8 Construction 23