getcensus is a Stata package for loading American Community Survey (ACS) data from the U.S. Census Bureau API into Stata.

About the Census Bureau API

The Census Bureau publishes thousands of ACS data tables on the web at The underlying data is available through the Census Bureau Application Programming Interface (API).1

To obtain data from the API, you will need to know the table ID and variable ID of the data point you are interested in. Each table that the Census Bureau publishes on has a unique table ID, and each data point within a table has a unique variable ID. For instance, ACS 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.

Accessing ACS Data with getcensus

To retrieve ACS data from the API, users may specify one or more variable IDs, a single table ID, or a keyword to getcensus. For instance, getcensus S1701_C02_001 will load variable S1701_C02_001, the estimated number of people in poverty. getcensus S1701 will load all variables in table S1701, Poverty status in the past 12 months.

By default, getcensus retrieves both estimates and their margins of error2 and attaches metadata from the API data dictionary to the dataset in the form of variable labels and notes.3

Searching the API Data Dictionary with getcensus

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 ACS subject tables (“ST”): the variable ID, the variable’s description, and the name of the variable’s table.

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

Back to top


  1. In fact, is powered by the API.↩︎

  2. If the option noerror is specified, getcensus will retrieve estimates only; see Options.↩︎

  3. If the option nolabel is specified, this metadata will not be included; see Options.↩︎