Rather than using the standard geography predicates, many datasets in the Census API also allow you to use the Uniform Census Geography Identifier (ucgid) predicate &ucgid to specify your desired geographies.

Benefits of using &ucgid to select your geography:

• It allows you to get data for multiple levels of geography in the same API query
  Example: &ucgid=0400000US24,0500000US24017 provides results for Maryland and Charles County, MD
• It allows you to access data for collections of geographies that are not accessible using the standard geography predicates
  Example: &ucgid=pseudo(0400000US24$8600000) provides results for all ZIP Code Tabulation Areas fully/partially within Maryland

Drawbacks of using &ucgid to specify your geography:

• You must specify the fully qualified GEOID of the area(s) you want to include in your query.
• The ucgid predicate is not available for every dataset in the API. If available, ucgid will appear in the list of variables on the dataset page.

Using ucgid for Individual Geographies

Use the ucgid predicate: &ucgid= and then type the fully qualified GEO ID. In the below example, the ucgid predicate provides results for New York city, NY &ucgid=1600000US3651000

api.census.gov/data/2022/acs/acs1/profile?get=NAME,DP05_0001E&ucgid=1600000US3651000

To specify individual geographies using ucgid, you will need to know the fully qualified GEO ID for that geography.

Fully qualified GEO IDs consist of:

• 3-character summary level
• 2-character geographic variant
• 2-character geographic component
• US
• Numeric codes that uniquely identify the geographic area. These may include:
  • InterNational Committee for Information Technology Standards (INCITS) codes, formerly Federal Information Process Standards (FIPS) codes.
  • Other codes assigned by the Census Bureau, U.S. Department of Education, and individual states for geographic areas not covered by INCITS.

As an example, consider the fully qualified GEO ID for New York City, NY:
1600000US3651000

• 160 = 3-character summary level for place
• 00 = 2-character geographic variant, indicating that a geographic variant does not apply
• 00 = 2-character geographic component, indicating this is not a geographic component
• US = United States
• 36 = 2-digit state code for New York
• 51000 = 5-digit place code for New York city

Table 1: Ucgid Examples for Individual Geographies

The ucgid predicate allows you to specify multiple geographies in the same API query by listing each desired fully qualified GEO ID separated by a comma. For example:

• &ucgid=0400000US06,0400000US41 – Provides results for California and Oregon
• &ucgid=0400000US06,0500000US06059,1600000US0602000 – Provides results for California, Orange County CA, and Anaheim city CA

Remember, &ucgid is an alternative option instead of using the standard geography predicates (&for and &in). An example query below shows how to use &ucgid to get total population for California and Oregon from the 2022 ACS 1-Year Data Profiles:

api.census.gov/data/2022/acs/acs1/profile?get=NAME,DP05_0001E&ucgid=0400000US06,0400000US41

Geographic Variants

A geographic variant is a version of a geographic area based on the date its boundaries are intended to represent. Geographic variants only apply to specific types of geographic areas that need to be added or replaced by a more recent version, for example, congressional districts when a state redraws its congressional district boundaries.

Geographies that commonly use geographic variants include: Congressional districts, state legislative districts, metropolitan/micropolitan statistical areas, ZIP Code tabulation areas (ZCTAs), urban areas, public use microdata areas (PUMAs), New England city and town areas (NECTAs). You must specify the correct geographic variant when using the ucgid predicate for these types of geographies. If you are unsure which variant applies to a dataset, reference the section below: Finding Fully Qualified GEO IDs.

Geographic Components

A geographic component is a subset of a given type of geographic area based on a certain geographic or population characteristic. For example, the geographic component “United States – Rural” is a geography selection representing the portion of the United States that falls within a rural area. Some common types of geographic components include: Urban, rural, in metropolitan/micropolitan statistical area, and not in metropolitan/micropolitan statistical area.

In most cases, the geographic component in the GEO ID will be 00, as they do not apply to data analyses for most data users.

Finding Fully Qualified GEO IDs

The Census Bureau offers several options to find fully qualified GEO IDs for a particular geography:

1.      TIGER/Line Shapefiles: Reference the GEOIDFQ field

2.      TIGER/Line Geodatabases: Reference the GEOIDFQ field

3.      API: Include the GEO_ID variable in your API query. Example:
https://api.census.gov/data/2022/acs/acs5/profile?get=GEO_ID,NAME&for=congressional%20district:*&in=state:01

Figure 5: Example API Query and Output with GEO_ID Variable - All Congressional Districts in Alabama from 2022 ACS 1-Year Data Profiles

4.      data.census.gov: Download the ZIP file for a table that includes your desired geographies. The GEO_ID column of the file will show the fully qualified GEO ID.

Figure 6: Example ZIP Download Output from data.census.gov - All Congressional Districts in Alabama from 2022 ACS 1-Year Data Profiles

You may also find it helpful to review additional reference materials to understand GEO IDs:

• Understanding Geographic Identifiers (GEOIDs) geography webpage
• American National Standards Institute (ANSI), Federal Information Process Series (FIPS), and Other Standardized Geographic Codes geography webpage

Using ucgid for Collections of Geographies (Pseudo Geos)

The ucgid predicate also allows you to retrieve data for collections of geographies, such as All Counties within Maryland or All Census Tracts within Jessamine County, Kentucky. This functions similarly to using the wildcard functionality (*) when using the standard geography predicates (&for and &in) – except the ucgid predicate provides access to even more options to request data for collections of geographies. “All Census Tracts in the U.S.” or “All ZIP Code Tabulation Areas fully/partially within Maryland” are some examples of collections of geographies that are exclusively available by using ucgid.

Use the ucgid predicate: &ucgid=pseudo and in parentheses, enter the joined parent/child GEO IDs. In the below example, the ucgid predicate provides results for All Counties within Maryland:
&ucgid=pseudo(0400000US24$0500000)

api.census.gov/data/2022/acs/acs1/profile?get=NAME,DP05_0001E&ucgid=pseudo(0400000US24$0500000)

GEO IDs for collections of geographies (pseudo geos), consist of:

• The fully qualified GEO ID of the parent geography. The parent geography is a single reference geography when considering whether other geographies intersect with it.
• A dollar sign ($) to represent the joining of two geographies.
• The 7-character ID representing the type of geographic area for the child geographies. Child geographies are the collection of geographic areas that intersect with the parent geography, meaning they are fully and/or partially contained within the parent geography.

As an example, consider the ucgid predicate for All Counties within Maryland:

&ucgid=pseudo(0400000US24$0500000)

• 0400000US24 = Fully qualified GEO ID for Maryland (parent geography)
• $ = Symbol that represents the joining of two geographies
• 0500000 = All Counties (child geography)*

*The first 3 characters always indicate the child geography’s summary level, in this case, 050 for counties. This is typically followed by four zeros, with a few exceptions noted in column B of the List of Available Collections of Geographies.

The List of Available Collections of Geographies also provides documentation of each possible geography collection that can be used in the API. Please be aware that not every collection of geography is available for every dataset. In most cases, collections of geographies are supported when a dataset provides data for the both the parent and child summary levels.

Table 2: Ucgid Examples for Collections of Geographies