U.S. flag

An official website of the United States government

Skip Header

Geography Tutorial

Getting Started

The beginning of an api call will always start with:


Let’s break down the portion of the api call related to geography:

One important thing is to know is what levels of geography are recorded for a particular survey. Not every survey looks at the same geographic levels, for example, in the 2010 Decennial and ACS 5y you can search by congressional district, school district, zip code etc, but in some Pop Estimates you can only search state>county. This varies by survey and even by subcategories of the same survey, so its important to double check what geographies are available to you. This can be found from the main Discovery page: api.census.gov/data.html  and clicking on ‘geographies’ in the row with your survey.

You will also need to know the FIPS or GNIS codes for states, counties, districts, etc. If you want to search for everything in a category, use a wildcard *


To include geography in a query string, you must use a for argument to define the geography level with a FIPS (or GNIS) code

&for=name of type of geography:number code of that geography (for argument may include additional codes, separate by commas)



&for=state:02, 03, 04

In some cases, you must also include an in argument to fully define the geography. This is required if the geographic level desired is lower than the first level of a geographic hierarchy; and you will have to specify all the levels above it until you get to the highest level:

&for=name of type of geography:number code of that geography (if multiple codes, separate by comma)&in=name of next highest type:number code for that specific geography, name of next highest type:number code (and so on, if applicable)3

Full Example


This searches for the unweighted sample count of the population in every county in Alaska, and data is displayed for every county for which there is data publicly available.

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


Back to Header