The predicate &for restricts the variables by geography at various levels, while &in and %20 restricts to geographic areas smaller than state level. You can include wildcards (*) along with &for and &in.

Examples to get results for a single geography:

•  &for=state:01 – restricts the result to include only Alabama
• &for=county:001&in=state:01 – restricts the result to include only Autauga County, Alabama
• &for=county%20(or%20part):073&in=state:01%20place:07000 – restricts the result to include the portion of Jefferson County (county:073), Alabama that is within Birmingham city (place:07000)

Examples to get results for multiple geographies:

•  &for=state:01,13 – retrieves the result for Alabama and Georgia
• &for=state:* – retrieves the result for all states
• &for=county:*&in=state:01 – restricts the result to include all counties in Alabama
• &for=county%20(or%20part):*&in=state:01%20place:62328 – restricts the result to include all counties within Prattville city (place: 62328), Alabama

The “Examples” pages in the discovery tool will list the available geographic levels and predicates for your dataset so you don’t have to build these from scratch.

For more information on Census Bureau geography, visit the Geography webpage.

As an alternative, you may instead use &ucgid to restrict your variables by geography. For more details, see the Ucgid Predicate section of this guide.

You can create a predicate of string variables with various restrictions and can include wildcards (*). Below are several examples across different surveys and programs.

Examples to get results for a single variable value:

•  &AGEGROUP=29 – restricts results to include data for people age 18 years and over (example: 2019 Population Estimates Program Characteristics of Age Groups)
• &POPGROUP=400 – restricts results to include data for POPGROUP code 400, which corresponds to the Hispanic or Latino population (example: 2019 ACS 1-Year Selected Population Profiles)
• &GEOCOMP=A0 – restricts results to include data for the portion of your geography that is within a metropolitan/micropolitan statistical area (example: 2018 ACS 5-year Data Profiles)
• &PORT=0101 – restricts the result to include data for PORT code 0101, which corresponds to Portland, ME (example: International Trade – U.S. Exports by Port and Harmonized System)

Examples to get results for multiple variable values:

•  &POPGROUP=400&POPGROUP=451 – restricts results to include data for POPGROUP codes 400 and 451, which are the codes for the Hispanic or Latino and Non-Hispanic white alone populations (example: 2019 ACS 1-Year Selected Population Profiles)
• &PORT=0101&PORT=0501 – restricts the result to include only ports with PORT codes 0101 and 0501 which correspond to Portland, ME and Newport, RI (example: International Trade – U.S. Exports by Port and Harmonized System)
• &PORT=21* – restricts the result to include data for PORT codes starting with 21 which may include but is not limited to 2101, 2102, 2103, and 2104, etc. (example: International Trade – U.S. Exports by Port and Harmonized System)
• &NAICS2017=23* -- restricts results to include data for all available NAICS codes that begin with 23 in the construction sector (example: 2018 County Business Patterns)

You can use wildcards (*) in predicates with string variables and geographies only. You cannot use wildcards in time predicates or predicates with numeric variables.

You can create a predicate of a range of values for numeric (integer and float) variables. Please note that you cannot build a predicate with wildcards for numeric variables.

Examples from County Business Patterns and the American Community Survey:

•  &PAYANN=100000 – restricts the result to include data where annual payroll is equal to 100,000
• &PAYANN=200000&PAYANN=300000 – restricts the result to include data where annual payroll is equal to 200,000 or 300,000
• &PAYANN=0:399999 – restricts the result to include data with annual payroll less than 400,000
• &PAYANN=400000:500000 – restricts the result to include data where annual payroll is from 400,000 to 500,000
• &DP05_0001E=100000:999999 – restricts results to include data where total population is from 100,000 to 999,999
• &DP03_0128PE=0:20 – restricts results to include data where the percent of people in poverty is from 0% to 20%

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.

For some datasets available on the Census Data API, data are stored for multiple points of time in one dataset, rather than across several datasets for individual points of time. When this occurs, we refer to the dataset as a time series dataset. You can find the list of time series datasets in the time series section of the API Discovery Tool.

You can limit by time in most time series datasets by using the predicate &time. Please note that you cannot build a predicate with wildcards (*) for time in a time series dataset. The plus sign (+) is needed for time ranges, such as the time range from 1997 to 2012 (below).

Examples:

•  &time=2015 – restricts the result to include data for 2015
• &time=from+1997+to+2012 – restricts the result to include data from 1997 to 2012
• &time=2015-01 – restricts the result to include data for January, 2015
• &time=2015-Q1 – restricts the result to include data for the first quarter of 2015
• &time=from+2015-01 – restricts the result to include data from January, 2015 to the present
• &time=to+2015-01 – restricts the result to include data up to January, 2015
• &time=from+2015-01+to+2015-06 – restricts the result to include data from January, 2015 to June, 2015

Some time series datasets do not include the variable “time.” Instead, they use other variables such as “Year.” For these time-related variables, check the predicate type in the discovery tool to find out whether you can filter it following the guidelines for string or numeric variables described earlier in this document.

For more information about time series datasets, see the Time Series Dataset Example – International Trade Monthly Exports section of this user guide.