Title

getcensus -- Load American Community Survey data from the U.S. Census Bureau API into Stata.

Syntax

Retrieve estimates

getcensus variable IDs, table ID, or keyword [, options]

Search the API data dictionary

getcensus catalog [, options]

Main
years(numlist) year(s) to retrieve; default is most recent available.

sample(integer) 1, 3, or 5; default is sample(1).

geography(string) geography to retrieve, default is geography(state).

key(string) your Census Bureau API key.

nolabel do not label variables with associated metadata from the API data dictionary.

noerror do not retrieve margins of error associated with estimates.

saveas(filename) save retrieved data as a Stata dataset.

exportexcel if saveas() is specified, also save retrieved data as an Excel spreadsheet.

replace if saveas() is specified, overwrite existing files.

clear replace the data in memory, even if the current data have not been saved to disk.

browse browse the retrieved data in the Data Editor after getcensus completes.

Geography options
statefips(string) state FIPS codes of states to retrieve; default is usually all.

countyfips(string) county FIPS codes of counties to retrieve; default is usually all.

geoids(string) GEOIDs of geographies to retrieve; default is usually all.

geocomponents(string) geographic component codes of geographies to retrieve.

Catalog options
product(string) load the API data dictionary for estimates of given product type.

table(string) load the API data dictionary for estimates in a given table.

search(string) load the API data dictionary for estimates with descriptions matching a search term.

Advanced options
cachepath(string) customize where getcensus caches API data dictionaries.

Description

getcensus loads American Community Survey (ACS) estimates from the U.S. Census Bureau API into memory.

To retrieve ACS data from the API, users may specify one or more variable IDs,
a single table ID, or a keyword. If a list of
variable IDs is specified, the variables must come from tables that share the
same product type (Data Profile, Subject Table, Comparison Profile, or Detailed
Table).

The Census Bureau publishes thousands of tables of ACS data. Each table has a
unique table ID. Each data point within a table is called a variable, and each
variable has a unique variable ID. For instance, table S1701, "Poverty status
in the past 12 months" contains the estimated number of people in poverty. The
variable ID for this data point is S1701_C02_001. By default, getcensus
retrieves both estimates and their margins of error, so users should not suffix
variable IDs with "E" (for estimate) or "M" (for margin of error).

In a dataset retrieved by getcensus, the variable names are the ACS variable
IDs. Variable labels contain the ACS variable's description and a variable note
contains the name of the ACS variable's table. If the option nolabel is
specified, this metadata will not be included.

Users rarely know offhand the variable ID or table ID of the data points they
would like to retrieve. getcensus catalog allows users to access the API
data dictionaries. For instance, getcensus catalog, product(ST) will load
into memory a dataset containing, for every variable in the subject tables
("ST"): the variable ID, the variable's description, and the name of the
variable's table.

If you are new to American Community Survey data, the Census Bureau's handbook
Understanding and Using American Community Survey Data: What All Data Users Need to Know
is the best place to start.

getcensus uses the Census Bureau Data API but is not endorsed or certified by the Census Bureau.

Options

Main

years(numlist) specifies the years (or endyears, if multiyear estimates
are requested) of the sample to be retrieved. Defaults is the most recent
available. If multiple years are requested, data for all years requested will be
appended together. Users requesting multiple years should be aware that not all
ACS estimates are available for all years, and table specifications and
geographies may change between years; see
ACS Table & Geography Changes
on the Census Bureau website. Users may deviate from numlist conventions
and separate ranges with "-" rather than "/" (e.g., "2017-2019" for 2017, 2018
and 2019).

sample(integer) specifies the sample to retrieve: 1 for one-year
estimates, 3 for three-year estimates (2007-2013 only), or 5 for five-year
estimates. Default is 1. One-year estimates are only available for geographic
areas with more than 65,000 residents; see
When to Use 1-year or 5-year Estimates
on the Census Bureau website.

geography(string) specifies the geographic unit for which to retrieve
data. Default is state. See
Supported Geographies.

key(string) specifies your Census Bureau API key. If you do not have an
API key, you may acquire one at
https://api.census.gov/data/key_signup.html. To avoid specifying
key() each time getcensus is used, store your API key in a global
macro named censuskey in your profile.do. Learn about where to find
your profile.do in the
profile.do FAQ
on the Stata website. If you are unfamiliar with global macros, simply type
global censuskey "your-api-key-here" into your profile.do.

nolabel specifies that retrieved data should not be labeled with
associated metadata from the API data dictionary.

noerror specifies that getcensus should not retrieve margins of error
associated with estimates.

saveas(filename) causes retrieved data to be saved under the name
filename as a Stata dataset.

exportexcel if saveas() is specified, causes retrieved data to also be
exported to an Excel spreadsheet.

replace if saveas() is specified, allows existing files to be
overwritten.

clear causes the data in memory to be replaced, even if the current data
have not been saved to disk.

browse opens retrieved data in the Data Editor after getcensus
completes.

Geography options

statefips(string) Two-digit FIPS codes of state(s) to retrieve. Default is
usually all. A listing of state FIPS codes can be found on the
FIPS Codes page
on the Census Bureau website.

countyfips(string) Three-digit FIPS codes of counties to retrieve. A list
of county FIPS codes by year can be found on the
Geography Reference Files page
on the Census Bureau website. Note that county FIPS codes may change
between years; see
ACS Table & Geography Changes
on the Census Bureau website.

geoids(string) GEOID(s) of geographies to retrieve. Default is usually
all. GEOIDs are numeric codes that uniquely identify all geographic areas for
which the Census Bureau tabulates data; see
Understanding Geographic Identifiers
on the Census Bureau website. Many geography types have GEOIDs that are made up
of several components. Only the last component should be specified in
geoid(). The state code component of the GEOID should be specified in
statefips(). If the GEOID includes a county code, it should be specified in
countyfips(). See Examples. Note that GEOIDs and
geography definitions may change between years; see
ACS Table & Geography Changes
on the Census Bureau website. getcensus supports most, but not all,
geographies supported by the ACS API; see
Supported Geographies.

geocomponents(string) Geographic component codes of the geographic
components to retrieve. Geographic components are division of a geographic unit
by certain criteria, such as rural, urban, in metropolitan statistical area,
and not in metropolitan statistical area. getcensus does not support all
geographic components available on the Census Bureau API; see
Supported Geographies.

Catalog options

product(string) will load the API data dictionary for variables in tables
of a given product type, as specified with a two-letter abbreviation. Default is
DT. For information about ACS tables and product types, see
Table IDs Explained
on the Census Bureau website. If both product() and table() are
specified with getcensus catalog, product() is ignored and the
appropriate product type is determined by the contents of table().

product Description

DP Data Profile
ST Subject Table
CP Comparison Profile
DT Detailed Table

table(string) will load the API data dictionary for a given table. For
information about ACS tables and product types, see
Table IDs Explained
on the Census Bureau website. If both product() and table() are
specified with getcensus catalog, product() is ignored and the
appropriate product type is determined by the contents of table().

search(string) will load the API data dictionary for variables whose
descriptions match a given search term, such as "children", "poverty", or
"veteran". A regular expression may be specified to search().

Advanced options

cachepath(string) getcensus caches API data dictionaries for future
retreival. By default, these files are saved in application support
("~/AppData/Local/" on Windows and "~/Library/Application Support" on Mac). To
save these files elsewhere, pass your desired location to cachepath().

Supported Geographies

Geographies

getcensus supports most, but not all, geographies supported by the Census
Bureau API. Users who are requesting data for multiple years should be aware
that ACS geography definitions may change between years; see
ACS Table & Geography Changes
on the Census Bureau website.

A list of geographies supported by getcensus can be found below. For some
geographies, users may specify an abbreviation rather than the full name. The
third column indicates whether statefips() or countyfips() may be
specified with a given geography. Bold indicates the option is required with a
given geography.

Name Abbreviation Options

us
region
division
state statefips
county co statefips
* county subdivision cousub statefips, countyfips
* tract statefips, countyfips
* block group bg statefips, countyfips
place statefips
* zip code tabulation area zcta statefips
* state legislative district (upper chamber) sldu statefips
* state legislative district (lower chamber) sldl statefips
congressional district cd statefips
school district (elementary) elsd statefips
school district (secondary) scsd statefips
school district (unified) unsd statefips
public use microdata area puma statefips
alaska native regional corporation anrc statefips
american indian area/alaska native area/
hawaiian home land aiannh
** metropolitan statistical area/
micropolitan statistical area metro statefips
combined statistical area cbsa
new england city and town area necta
combined new england city and town area cnecta
urban area urban

* only 5-year estimates are available for this geography.
** only 5-year estimates are available when statefips() is specified with this geography.
may not be specified starting with the 2020 5-year estimates (2019 for subject tables).

Geographic components

Geographic components are division of a geographic unit by certain criteria.
getcensus does not support all geographic components available on the Census
Bureau API.

An example: getcensus [variable IDs], geography(state) geocomponents(H0 C0)
will return two observations for each state: one for the portion of the state
not in a metropolitan statistical area ("H0"), and one for the portion of the
state in a metropolitan statistical area ("C0").

Available with geography() us, region, division, or state

00 Total
H0 Not in metropolitan statistical area
C0 In metropolitan statistical area
C1 In metropolitan statistical area: in principal city
C2 In metropolitan statistical area: not in principal city
E0 In micropolitan statistical area
A0 In metropolitan or micropolitan statistical area
E1 In micropolitan statistical area: in principal city
E2 In micropolitan statistical area: not in principal city
G0 Not in metropolitan or micropolitan statistical area
01 Urban
43 Rural

Available with geography(us) only

89 American Indian Reservation and Trust Land: Federal
* 90 American Indian Reservation and Trust Land: State
91 Oklahoma Tribal Statistical Area
** 92 Tribal Designated Statistical Area
93 Alaska Native Village Statistical Area
94 State Designated Tribal Statistical Area
* 95 Hawaiian Home Land

* only 5-year estimates are available for this geographic component.
** 1-year estimates are not available for this geographic component.

Keywords

Users may use a keyword to retrieve a curated set of variables.

Keyword Description

pov Number and percent of population in poverty; overall, by age, and by race

povratio Population by income-to-poverty ratio

povratio_char Characteristics of the population at various income-to-poverty ratios

medinc Median household income, overall and by race of householder

snap Percent of households participating in SNAP and characteristics of participating households

medicaid Number and percent of population covered by Medicaid, overall and by age

housing_overview Housing characteristics, including housing costs*

costburden_renters Detailed renter housing cost burden*

costburden_owners Detailed homeowner housing cost burden

opt tenure_inc Median household income and family poverty status, by housing tenure

kids_nativity Nativity of children, by age and parent's nativity

kids_pov_parents_nativity Children by poverty status and parent's nativity

* When using the data retrieved by keyword costburden_renters to
compute rates of renter housing cost burden, compute the denominator by
subtracting the number of renters for whom cost burden is not computed
(B25070_011) from the number of renters (B25070_001). This step is not necessary
when using the data returned by keyword housing_overview; the total in this
table's section on rent burden (DP04_0136) already excludes the number of
renters for whom cost burden cannot be computed.

Example(s)

Variables, tables, and keywords

Single table

. getcensus S2701

Single variable

. getcensus B19013_001

Multiple variables from a single table

. getcensus DP02_0053 DP02_0054 DP02_0055 DP02_0056 DP02_0057

Multiple variables from more than one table

. getcensus S1701_C03_001 S2701_C05_001

Keyword

. getcensus medinc

Years and samples

Single year (default is most recent available)

. getcensus B19013, year(2010)

Multiple years

. getcensus B19013, years(2018/2019)

. getcensus B19013, years(2010 2015 2019)

Samples (default is 1)

. getcensus B19013, sample(5)

. getcensus B19013, sample(3) year(2013)

Geographies

Types (default is state)

. getcensus B19013, geography(us)

. getcensus B19013, geography(county)

. getcensus B19013, sample(5) geography(sldu) statefips(26)

Within a state or set of states

. getcensus B19013, statefips(11)

. getcensus B19013, geography(county) statefips(04)

. getcensus B19013, geography(congressional district) statefips(24 51)

. getcensus B19013, sample(5) geography(metro) statefips(06)

With specific GEOIDs

. getcensus B19013_001, geography(metro) geoids(47900)

. getcensus B19013_001, geography(county) statefips(24) geoids(005 510)

. getcensus B19013_001, geography(place) statefips(48) geoids(35000)

. getcensus B19013_001, sample(5) geography(tract) statefips(01) countyfips(001) geoids(020100)

Geographic components

. getcensus B19013, geocomponents(H0)

. getcensus B19013, geocomponents(01 43) statefips(13)

. getcensus B19013, sample(5) geography(us) geocomponents(92)

Catalog

All variables in tables of a given product type

. getcensus catalog, product(DP)

Variables from a single table

. getcensus catalog, table(S0901)

Variables matching a search term

. getcensus catalog, search(children) product(ST)

. getcensus catalog, search(educational attainment) table(S1701)

Website

Online documentation:
centeronbudget.github.io/getcensus/

GitHub repository:
github.com/CenterOnBudget/getcensus

Authors

getcensus is a project of the
Center on Budget and Policy Priorities, a nonpartisan
research and policy institute. It is maintained by Claire Zippel and was
developed by Claire Zippel and Matt Saenz. getcensus was created by Raheem
Chaudhry and Vincent Palacios. Contributors include Lori Zakalik.