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).
The base URL consists of the:
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:
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:
Examples to restrict universe by multiple variable values:
|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:
|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:
Examples to get results for multiple geographies:
Browse the Geographic Reference Files to explore the Federal Information Processing Standards (FIPS) geography codes to use in microdata API queries.