Skip to content

Query Examples

Component ID: #ti1542606650

Procedures: How Do You Build A Query?

Following are some examples that give a detailed breakdown of the components of the URL needed for building a query on a dataset.

Expand All

Collapse All
Component ID: #ti385140076

Let’s begin with a query for the resident population totals per state in the dataset, Vintage 2014 Population Estimates: US, State, and PR Total Population and Components of Change. You will find this dataset listed on the Census Data API Datasets page:

api.census.gov/data.html

Format queries as a URL, as follows (Use Firefox.):

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

Assemble components of this query by following these steps:

  1. Start your query with the host name: https://api.census.gov/data
  2. Add the data year to the URL. This is the year the data were estimated;; e.g., 2014

    https://api.census.gov/data/2014

  3. Add the dataset name’s acronym, which is listed in the “Dataset Name” column on the Census Data API Datasets page (api.census.gov/data.html); e.g., pep/natstprc.

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

    This is the base URL for this dataset.

  4. Follow the base URL with the query character ? (question mark). Add variables starting with a get clause get= followed by the name of the variable for which you are searching. The link for the list of variables is in the “Variable List” column on the Census Data API Datasets page (api.census.gov/data.html) and will lead you to this Variables page:

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

    Because there is more than one variable in this query, use a comma to separate each variable:

    https://api.census.gov/data/2014/pep/natstprc?get=STNAME,POP

    In this dataset, STNAME will provide the state name to clarify the output reading for state code.

  5. Add geography using a predicate clause starting with an ampersand (&) to separate it from your get clause, and then a for followed by in clause, if needed; e.g., &for=state. Because we are looking for information for all the states, add a wildcard (:*) to indicate all values; e.g., state:*

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

    A full list is available at the geography page linked next to this dataset on the Census Data API Datasets page: api.census.gov/data/2014/pep/natstprc/geography.html. As you can see, you can only search on the state or national level for this dataset. Other datasets present many more geographical subdivisions. Sometimes datasets change the number of geographies they publish from year to year.

  6. When you finish practicing and are ready to publish your data and use a key, insert &key= followed by your key code into the search URL. You can place this anywhere in the URL after the question mark; e.g., &key=your key here

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

  7. You can copy your query results into a spreadsheet to clean it up and analyze it, or you can save it as a file and consume it as JSON. The response for all queries is formatted as a two dimensional JSON array where the first row provides column names and the subsequent rows provide data values. The first rows of output of the query are configured as follows:

    [["STNAME","POP","DATE","state"],
    ["Alabama","4849377","7","01"],
    ["Alaska","736732","7","02"],
    ["Arizona","6731484","7","04"],
    ["Arkansas","2966369","7","05"],
    ["California","38802500","7","06"],
    ["Colorado","5355866","7","08"],
    ["Connecticut","3596677","7","09"],
    ["Delaware","935614","7","10"],
    ["District of Columbia","658893","7","11"],
    .....

    You can find examples of other queries for this dataset by clicking the link in the Examples column on the API datasets page, which takes you to this Example page:
    api.census.gov/data/2014/pep/natstprc/examples.html

Tip As you begin to build queries, start with examples and expand upon them. This is a great way to learn how to use the Census Data API.

Component ID: #ti1411811283

The ACS has many datasets in the Census Data API with a large amount of variables and special naming conventions. In our example, we will focus on the American Community Survey 1-Year Data.

Component ID: #ti459025566

2.1 American Community Survey Variable Names

E and M

At the end of a variable’s name in all ACS datasets, E and M are characters for estimates and margins of error. E indicates the estimated number from the sample surveyed, while M at the end of a variable number indicates the margin of error. The smaller the sample size the greater the margin of error.

PE and PM

At the end of a variable’s name in the ACS datasets, PE stands for percentage estimate, and PM stands for percentage margin of error.

Component ID: #ti459025567

2.2 ACS1 Query

This query concerns how many Hmong people are living in each US state as determined by the 2013 American Community Survey 1-Year Data. Format the search query URL as follows:

https://api.census.gov/data/2013/acs1?get=NAME,B02015_009E,B02015_009M&for=state:*

Assemble components of this query by following these steps:

  1. Start your query with the host name: https://api.census.gov/data
  2. Add the data year to the URL; e.g., 2013

    https://api.census.gov/data/2013

  3. Add the dataset name acronym, which is available here: https://api.census.gov/data.html; e.g., acs1

    https://api.census.gov/data/2013/acs1

    This is the base URL for this dataset.

  4. Start your query with a ? and add variables starting with a get clause get=. In this dataset, the variable called NAME will provide the geographic name you are using to limit your search, along with your numerical data. Use a comma to separate this variable from the variable designating the Hmong population; e.g., ?get=NAME,B02015_009E,B02015_009M. (A full list of ACS 1-Year geographies and variables  is available here: api.census.gov/data/2013/acs1/variables.html)

    https://api.census.gov/data/2013/acs1?get=NAME,B02015_009E,B02015_009M

  5. Add geography using a predicate clause starting with an ampersand (&) to separate it from your get clause and then a for followed by an in clause, if needed; e.g., &for=state. Because we are looking for information in all the states, add a wildcard (:*) to indicate all values; e.g., state:* (A full list is available here: api.census.gov/data/2013/acs1/geography.html)

    https://api.census.gov/data/2013/acs1?get=NAME,B02015_009E,B02015_009M&for=state:*

  6. If you are using a key, insert &key= followed by your key code at the end of your search URL: &key=your key here

    https://api.census.gov/data/2013/acs1?get=NAME,B02015_009E,B02015_009M&for=state:*&key=your key here

    The query configures the first rows of output as follows:


    [["NAME","B02015_009E","B02015_009M","state"],
    ["Alabama",null,null,"01"],
    ["Alaska",null,null,"02"],
    ["Arizona","125","131","04"],
    ["Arkansas",null,null,"05"],
    ["California","96207","9900","06"],
    ["Colorado","5640","2528","08"],
    ["Connecticut","39","63","09"],
    ["Delaware",null,null,"10"],
    ["District of Columbia",null,null,"11"],
    ["Florida","544","474","12"],
    .....

    “Null” occurs as a result when there is no data entered for that answer. You can find other examples of searches in this dataset by clicking the link in the “Examples” column on the API datasets page, which will take you to the examples page here:

    api.census.gov/data/2013/acs1/examples.html

Tip If your query returns an error message with no data, check your spelling, capitalization, and spacing. Correct it, and run it again.

Component ID: #ti1086204654

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.  In this example, we will build a query for one of the time series datasets in the API, International Trade: Monthly U.S. Exports by End-Use Code for the total export value (monthly and year-to-date) for all Customs districts for June 2016:

https://api.census.gov/data/timeseries/intltrade/exports/enduse?get=DISTRICT,DIST_NAME,ALL_VAL_MO,ALL_VAL_YR&YEAR=2016&MONTH=06.

For more information on time series datasets, See Section 4.1.4 Predicate: Time (Time Series Dataset Only) in this user guide. You can find the list of time series datasets on the Census Data API here: https://api.census.gov/data/timeseries.html

Assemble components of this query following these steps:

  1. Start your query with the host name: https://api.census.gov/data
  2. Add timeseries to the URL: https://api.census.gov/data/timeseries
  3. Add the dataset name acronym, intltrade/exports/enduse (International Trade: Monthly U.S. Exports by End-use Code):

    https://api.census.gov/data/timeseries/intltrade/exports/enduse

    Start your query with a ? (question mark). Add variables starting with a get clause, get= followed by the names of the variables. (A full list of variables is available here: api.census.gov/data/timeseries/intltrade/exports/enduse/variables.html). Use a comma to separate the variables:

    https://api.census.gov/data/timeseries/intltrade/exports/enduse?get=DISTRICT,DIST_NAME,ALL_VAL_MO,ALL_VAL_YR

  4. Add the time period (REQUIRED for time series) using a predicate clause; e.g., &YEAR=2016&MONTH=06:

    https://api.census.gov/data/timeseries/intltrade/exports/enduse?get=DISTRICT,DIST_NAME,ALL _VAL_MO,ALL_VAL_YR&YEAR=2016&MONTH=06

    Tip You can also specify this required time range as &time=2016-06. See Predicate: Time (Time Series Dataset Only) in this user guide for building predicates for time series.
  5. If you are using a key, insert &key= followed by your key code at the end of your search: https://api.census.gov/data/timeseries/intltrade/exports/enduse?get=DISTRICT,DIST_NAME, ALL_VAL_MO,ALL_VAL_YR&YEAR=2016&MONTH=06&key=your key here

    The query configures the first rows of output of the query as follows:

    ["DISTRICT","DIST_NAME","ALL_VAL_MO","ALL_VAL_YR","YEAR","MONTH"],
    ["","TOTAL FOR ALL DISTRICTS","125024387876","711355944093","2016","06"],
    ["01","PORTLAND, ME","331269702","2082731222","2016","06"],
    ["02","ST. ALBANS, VT","184995129","1144444553","2016","06"],
    ["04","BOSTON, MA","727085911","3808920861","2016","06"],
    ["05","PROVIDENCE, RI","16926100","77856036","2016","06"],
    ["07","OGDENSBURG, NY","1440920883","8137120100","2016","06"],
    ["09","BUFFALO, NY","4343113148","23189188640","2016","06"],
    ["10","NEW YORK CITY, NY","11703487744","67797106022","2016","06"],
    ["11","PHILADELPHIA, PA","1401964078","7895311695","2016","06"],
    ["13","BALTIMORE, MD","1218070977","7354545603","2016","06"],
    ["14","NORFOLK, VA","1999192268","13011038202","2016","06"],
    ["15","WILMINGTON, NC","452856985","2828815661","2016","06"],
    ["16","CHARLESTON, SC","2950121172","16716095334","2016","06"],
    ["17","SAVANNAH, GA","4150832886","22986303931","2016","06"],
    .....

Component ID: #ti681276526

Now you are ready to write your API query (or queries) for a dataset. You can open and save your search to a text-editing program as a json file. You can save your search directly in Firefox and Chrome, but in Internet Explorer and Safari, you need to save your search to a text file program.

You can only search for variables that the variable table specifically lists with the API.

X
  Is this page helpful?
Thumbs Up Image Yes    Thumbs Down Image No
X
No, thanks
255 characters remaining
X
Thank you for your feedback.
Comments or suggestions?