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 1-year estimates, 3 for 3-year estimates (2007-2013 only), or 5 for 5-year estimates. Default is 1. 1-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(string) specifies that retrieved data should not be labeled with associated metadata from the API data dictionary. If this option is not specified, the dataset will include variable labels containing the variable description and variable notes containing the name of the variable’s table.
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 geoids(). 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().
| Abbreviation | Product type |
|---|---|
| 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 retrieval. 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().