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

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).

https://api.census.gov/data/2019/acs/acs1/pums

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.

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.

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.

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

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

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

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.

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.