U.S. flag

An official website of the United States government

Skip Header
Search data, events, resources, and more
The Census Bureau's API allows developers to design web and mobile apps to explore or learn more about America's changing population and economy.
About Developers App Gallery Terms of Service
Request an API Key Developers' Forum Geography Contact Us
Guidance for Developers Census Data API User Guide Census Microdata API User Guide
Census Data API Discovery Tool Workshop: Basics of Using the Census API View All Video Tutorials
Latest Data Releases News
Updates Contact Us
About Developers App Gallery Terms of Service Request an API Key Developers' Forum Geography Contact Us
Guidance for Developers Census Data API User Guide Census Microdata API User Guide Census Data API Discovery Tool Workshop: Basics of Using the Census API View All Video Tutorials
Latest Data Releases News Updates Contact Us

Query Components

Skip Navigation
Within Developers

Query Components

What are the Components of a Query?

1. The Terms You Will Need

Below are the terms you will need to be familiar with when running an API query, like this one for the dataset, Vintage 2014 Population Estimates: US, State, and PR Total Population and Components of Change (Use Firefox or Chrome):

https://api.census.gov/data/2014/pep/natstprc?get=STNAME,POP&DATE_=7&for=state:*

Tip We recommend that you use Chrome or Firefox when building and running API queries.

1.1 Variable

A variable is each unit of data you are searching for in a dataset.  Each variable that you can search for in a dataset has a name, which may be an acronym or meaningful on its own; e.g., STNAME, POP, DATE_.

In larger datasets, such as the American Community Survey, many of these names are based on an alphanumeric code; e.g., B01003_001E (Total Population).

You can find the list of variables in the dataset by visiting the variables page. For example, the variables page for the Vintage 2014 Population Estimates: US, State, and PR Total Population and Components of Change.

Figure 2: Variable Table for 2014 Population Estimates: US, State, and PR Total Population and Components of Change


1.2 Required Variables

Required variables are the parameters that you need to include in your search; otherwise, your search will produce no data and an error message. The variable table for each dataset lists which variables are required, as shown below in the variable table for one of the 2014 Population Estimates datasets found here:

https://api.census.gov/data/2014/pep/natstprc/variables.html

Figure 3: Variable Table for 2014 Population Estimates: US, State, and PR Total Population and Components of Change


1.3 Get Function

The get function (get=) specifies the required and selected variables you are requesting the API to give you. For example (Use Firefox or Chrome.):

https://api.census.gov/data/2014/pep/natstprc?get=STNAME,POP&DATE_=7&for=state:*

1.4 Predicate

The predicate specifies how variables should be filtered or limited, and you can create predicates of geography, string variables, numeric variables, and time (in time series datasets). In this example, the predicate limits the search on the July 1, 2014 (&DATE_=7) population or housing unit estimate and for all states (&for=state:*):

https://api.census.gov/data/2014/pep/natstprc?get=STNAME,POP&DATE_=7&for=state:*

Please note:

  • Predicates always start with an ampersand (&).
  • A wildcard (:*) can be included to search for all the values of a variable. Wildcards work for geographies and string variables only.
  • A variable should appear only once in a query ̶ either in the get statement or as a predicate.  In the example above, DATE_ is a predicate (&DATE_=7), so you do not need to include it in the get statement (?get=STATENAME,POP).

Geography

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

Examples:

  • &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:073&in=state:01+place:07000 – restricts the result to include the portion of Jefferson County (county:073), Alabama that is within Birmingham city (place:07000)

Examples with wildcards:

  • &for=state:* – retrieves the result for all states
  • &for=county:*&in=state:01 – restricts the result to include all counties in Alabama
  • &for=county:*&in=state:01+place:62328 – restricts the result to include all counties within Prattville city (place: 62328), Alabama

For more information on Census Bureau geography, click here:

www.census.gov/geography.html

Top of Section

Variables – String

You can create a predicate of string variables with various restrictions and can include
wildcards (:*).

Examples with PORT (code) and PORT_NAME from the Monthly International Trade Time Series – U.S. Exports by Port and Harmonized System (HS) Code dataset:

  • &PORT_NAME=NEWPORT, RI – restricts the result to include only the port of Newport, RI
  • &PORT_NAME=NEWPORT, RI &PORT_NAME=BANGOR, ME – restricts the result to include only the ports of Newport, RI and Bangor, ME
  • &PORT=0101 – restricts the result to include only the port with PORT code 0101
  • &PORT=0101&PORT=0102 – restricts the result to include only ports with PORT
    codes 0101 and 0102

Examples with wildcards:

  • &PORT_NAME=B* – restricts the result to include data for port names starting with the letter “B”
  • &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.
Tip You can use wildcards (:*) in predicates with string variables and geographies only. You cannot use wildcards in time predicates or predicates with numeric variables.

Top of Section

Variables – Numeric

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

Examples from County Business Patterns:

  • &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.

Top of Section

Time (Time Series Datasets Only)

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 on the Census Data API here: api.census.gov/data/timeseries.html You can limit by time in 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. Note that + 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

For more information about time series datasets, see Example: A Time Series Dataset – International Trade Monthly Exports in this users guide.

Top of Section


1.5 Response Format – JSON

The results from your Census Data API data queries will return in JavaScript Object Notation (JSON) format, and you can easily plug those data into the formatting file or graphic of your choice. JSON is an easy format for exchanging data between platforms using human-readable language, rivaling the popularity of XML. The Census uses a nonstandard version of JSON that is streamlined:

  • Data are represented in a two-dimensional array
  • Square brackets [ ] hold arrays
  • Values are separated by a , (comma).

[["STNAME","POP","DATE_","state"],
["Alabama","4849377","7","01"],
["Alaska","736732","7","02"],
["Arizona","6731484","7","04"],
["Arkansas","2966369","7","05"],
["California","38802500","7","06"],
.....

2. What Are the Query Limits?

You can include up to 50 variables in a single API query and can make up to 500 queries per IP address per day. More than 500 queries per IP address per day requires that you register for a Census key. That key will be part of your data request URL string.

Please keep in mind that all queries from a business or organization having multiple employees might employ a proxy service or firewall. This will make all of the users of that business or organization appear to have the same IP address.  If multiple employees were making queries, the 500-query limit would be for the proxy server/firewall, not the individual user.

3. How Do You Register For A Key?

  1. Go to www.census.gov/developers/
  2. Click on the Request a KEY box on the left side of the page.
  3. Fill out the pop-up window form.
  4. You will receive an email with your key code in the message.

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

Top

Back to Header