U.S. flag

An official website of the United States government

Skip Header

Terms Relevant to All Types of Microdata API Queries

Terms Relevant to All Types of Microdata API Queries

Here are some core concepts that are key for all microdata API calls for custom statistics and raw data.

Base URL

Begin your API queries with the base URL. You can find it in the API Discovery Tool for your dataset. The example below shows the base URL for the 2019 American Community Survey (ACS) 1-Year Public Use Microdata Sample (PUMS).


Figure 5: Base URL in the API Discovery Tool

The base URL consists of the:

  • Host name: https://api.census.gov/data
  • Vintage: 2019
  • Dataset name: acs/acs1/pums


Variables are the unit of data you are searching for. Each variable provides data for a range of values.

To explore the variables, click the variables link for a dataset in the API Discovery Tool as shown in Figure 6 for the 2019 ACS 1-Year PUMS dataset.

Figure 6: Variables Column in the API Discovery Tool

The API has three types of variables that you can browse by viewing the “Predicate Type” column on the API Variables page for your dataset (see Figure 7). The output of these variables may appear in a variety of alphanumeric and special characters, depending on the variable type:

  • String Variables – Output may be any combination of letters, numbers, or special characters.
  • Integer (Int) Variables – Output will be numbers, with or without decimals.
  • Float Variables – Output will be numbers with decimals.

Figure 7: Predicate Type Column in the Variables Page for each API Dataset

When you browse the available variables in the Discovery Tool, click a variable for more details. For example, the screenshot below shows details after clicking HICOV, the variable for the health insurance recode (see Figure 8). After clicking the variable, you can see that this variable has a predicate type of int (integer), which tells us that the values will be expressed numerically. In addition, it shows the output values for this variable. A value of 1 refers to people with health insurance coverage, and a value of 2 refers to people without health insurance coverage.

Figure 8: HICOV Variable Link and Details from the API Discovery Tool

Predicates to Restrict Your Universe

Predicates allow you to limit your universe by variable value or geography. They always start with &.

Restrict Universe by Variable Value

You can use variable predicates to restrict the universe or population that your results include. Consider these examples from the 2019 ACS 1-Year PUMS microdata API dataset.

Examples to restrict universe by a single variable value:

  • &HICOV=2 – restricts results to include data for the population without health insurance
  • &SCHL=16 – restricts results to include data for the population whose highest level of educational attainment is a high school diploma
  • &NAICSP=928110P2 – restricts results to include data for the population whose primary or most recent job is the United States Air Force

Examples to restrict universe by multiple variable values:

  • &SCHL=16&SCHL=17 or &SCHL=16,17 – restricts universe to persons whose highest level of educational attainment is a regular high school diploma (SCHL=16) or GED or alternative credential (SCHL=17)
  • &SCHL=16:24 – restricts universe to people with a high school diploma or higher
Tip You can use colons (:) to restrict results by a range of variable values for integer and float variables only. You cannot use colons with string variables.

Examples to restrict universe using variables with decimal values from the December 2020 Current Population Survey (CPS) Basic Monthly microdata API dataset:

  • &PTERNHLY=-0.01 – restricts universe to people who do not have hourly earnings
  • &PTERNHLY=0.01:7.24 – restricts universe to people who earn $0.01 to $7.24 per hour
Tip You must put a zero in front of decimal values between -1 and 1. For example, 0.01 and -0.01. The API query will not work if you try to shorten it to .01 or -.01.

Restrict Universe by Geography

Use geography predicates to specify the geography that your results include. The predicate &for specifies the primary geographic level. The predicate &in further restricts results for geographies that are nested within other geographies (example: public use microdata areas within a state).

Examples to get results for a single geography:

  • &for=state:22 – provides results for Louisiana
  • &for=county:071&in=state:22 – provides results for Orleans Parish, Louisiana. Please be aware that data are only available for some counties in the microdata API for selected CPS datasets.
  • &for=public%20use%20microdata%20area:02400&in=state:22 – provides results for public use microdata area (PUMA) 02400 in Louisiana

Examples to get results for multiple geographies:

  • &for=state:22,28 – provides results for the states of Louisiana and Mississippi
  • &for=state:* – provides results for all states
  • &for=public%20use%20microdata%20area:02400,02401,02402&in=state:22 – provides results for PUMAs 02400, 02401, and 02402 in Louisiana
  • &for=public%20use%20microdata%20area:*&in=state:22 – provides results for all PUMAs in Louisiana

Browse the Geographic Reference Files to explore the Federal Information Processing Standards (FIPS) geography codes to use in microdata API queries.

Page Last Revised - October 8, 2021
Is this page helpful?
Thumbs Up Image Yes Thumbs Down Image No
255 characters maximum 255 characters maximum reached
Thank you for your feedback.
Comments or suggestions?


Back to Header