Resolve Census Geography
census_resolve_geographyResolve a place name, ZIP code, or street address to Census FIPS identifiers. Converts names like "King County, WA", "Seattle, WA", or "Seattle-Tacoma-Bellevue, WA", and ZIPs like "98109", to the codes required by census_query_data and census_compare_geographies. Use before querying when you have a place name rather than raw FIPS codes — state_fips maps to parent_fips and fips_summary maps to geography_fips in downstream tools, and geography_type is itself the geography_level to query at.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"name": "<name>"
},
"name": "census_resolve_geography"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Place name (e.g., "King County, WA", "Seattle, WA", "California"), 5-digit ZIP code (e.g., "98109", resolved to its ZIP Code Tabulation Area), or street address of at most 100 characters (e.g., "1600 Pennsylvania Ave NW, Washington, DC 20500"). Include the state after a comma — its abbreviation or full name, as in "Chatham County, Georgia" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so "Kansas City, MO" and "Kansas City, KS" both reach the MO-KS metro area. Matching ignores case, reads "Saint" and "St." as the same word, and accepts unaccented spellings ("Dona Ana County, NM"). For a statistical area a leading city is enough ("Denver, CO" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city ("Denver-Aurora-Lakewood, CO"). A New York City borough with a New York suffix resolves to the county it is coextensive with when geography_type is "county" or omitted — "Brooklyn, NY" is Kings County, "Manhattan, NY" New York County, "Staten Island, NY" Richmond County. At county subdivision it is the borough's own subdivision; at any other level it is no_match, and at place, economic place, state, tract, or consolidated city the hint names the county. In the twelve states whose towns and townships govern like incorporated places, a town or township resolves to its county subdivision ("Cherry Hill, NJ", "Greenwich, CT"), and a trailing "Township" also reaches a Michigan charter township ("Clinton Township, MI"). "Fairfield County, CT" — or "Fairfield, CT" at geography_type "county" — resolves to Connecticut's county 001 from before 2022, which every vintage through 2021 publishes; the other seven of those eight counties resolve the same way. | |
| county_fips | No | County FIPS code to resolve within — 1 to 3 digits, zero-padded here to the 3 the Census stores. A tract name is unique only inside its county, and a town or township name can repeat across a state's counties, so a name matching two counties comes back as ambiguous_name until this is set: take the countyFips of the candidate you want from that error and re-call. Only county, county subdivision, and tract sit within a county, so this restricts resolution to those three levels — pairing it with any other geography_type, or with a street address, is a county_scope_unsupported error rather than a scope quietly dropped. census_query_data takes the same code as its own county_fips. | |
| geography_type | No | Geography level to resolve to, named exactly as census_query_data's geography_level and census_list_geographies name it. Auto-detection covers only state, county, county subdivision, place, tract, and zip code tabulation area: zip code tabulation area for a 5-digit ZIP or ZIP+4 — the ACS's ZIP-shaped area, not cbp's "zip code" level, which takes the ZIP itself with no resolution — state for a two-letter abbreviation or a spelled-out state name, county when the name contains the word "County" or "Parish", county then place for the word "Borough" (an Alaska borough is a county, a PA or NJ borough a place), tract for the word "Tract", otherwise place (incorporated places and census-designated places together) with a fallback to county, where a census-designated place answers only when no incorporated place or county has the exact name — "Arlington, VA" is Arlington County, and set "place" to reach the Arlington CDP. When the state suffix is one of the twelve states whose towns and townships govern like incorporated places (CT, ME, MA, MI, MN, NH, NJ, NY, PA, RI, VT, WI), county subdivision follows county in that chain: a town or township named exactly the input outranks a CDP of that name and a place that only contains it ("Cherry Hill, NJ" is Cherry Hill township, not Cherry Hill Mall CDP), while a county named exactly it still answers ("Plymouth, MA" is Plymouth County, and the notice names Plymouth town). Elsewhere a county subdivision is a statistical census county division or a township without a place's powers — some, as in Ohio and Illinois, have a government of their own — and is never auto-detected; set "county subdivision" to resolve one in any state. The other four are never auto-detected and must be set explicitly, because their names overlap city names — "metropolitan statistical area/micropolitan statistical area" covers both metro and micro areas and yields a 5-digit code, "combined statistical area" yields a 3-digit code, "consolidated city" covers the eight merged city-county governments (Nashville-Davidson, Louisville/Jefferson County, Indianapolis, Athens-Clarke County, Augusta-Richmond County, Butte-Silver Bow, Milford CT, Greeley County KS), and "economic place" yields the 8-digit code ecnbasic 2022 publishes a place under: the 3-digit county it lies in (000 when it spans counties) followed by its 5-digit place code. Economic places are the incorporated places, census-designated places, and county subdivisions the 2022 Economic Census tabulates, plus each county's remainder ("Balance of Adams County, WA"). Setting it explicitly also overrides auto-detection — "New York" auto-detects as the state, so New York City needs "place". |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Canonical name of the resolved geography. | |
| error | No | Present when the call failed. Absent on success. | |
| notice | No | Present when the result needs context its fields cannot carry: a New York City borough ("Brooklyn", "The Bronx", "Queens borough") resolved to the county it is coextensive with; a county subdivision with its own government named exactly the input — beside a county auto-detected in one of the twelve town-and-township states, or a census-designated place resolved at geography_type "place" there — named with its county and code, or a statement that the check could not run; a Connecticut county from before 2022, which vintages through 2021 publish in place of the planning regions; or a census tract, which is a 2020 tract that earlier vintages, drawn on earlier tracts, can lack — and in Connecticut sits under its planning region, where vintages through 2021 publish the same code under an earlier county. | |
| place_fips | No | 5-digit place FIPS code when the resolved geography is a place — incorporated or census-designated. For an economic place, the place part of its 8-digit code, which is also the place code the 2017 and 2012 ecnbasic vintages take. For a street address, the incorporated place the address sits in (query it at the place level with state_fips as parent_fips); absent when the address is outside every incorporated place, and a census-designated place is never reported for an address. | |
| state_fips | No | 2-digit state FIPS code. Use as parent_fips in census_query_data for sub-state queries. Absent for a metropolitan/micropolitan or combined statistical area, which can span several states and needs no parent_fips, and for a zip code tabulation area, whose source layer carries no state. | |
| tract_fips | No | 6-digit census tract FIPS code when the resolved geography is a tract — from a street address, or from a tract name. It is a 2020 census tract, which ACS 5-year vintages from 2020 and the 2020 Census files publish; earlier vintages publish earlier tracts, where the code can be missing, and the notice says so. | |
| county_fips | No | 3-digit county FIPS code when the resolved geography is a county or sub-county level. | |
| fips_summary | No | Pre-formatted FIPS value ready to use as geography_fips in census_query_data (e.g., "033" for King County with state_fips "53" as parent_fips, "42660" for the Seattle-Tacoma-Bellevue metro area with no parent at all, "03363000" for Seattle as an ecnbasic 2022 economic place). | |
| geography_type | No | Resolved geography level. Pass this straight through as geography_level in census_query_data and census_compare_geographies. | |
| block_group_fips | No | 1-digit block group within tract_fips, for a street address only. Query it as geography_level "block group" with this as geography_fips, alongside parent_fips, county_fips, and tract_fips. geography_type and fips_summary stay at the tract. | |
| census_designated_place | No | Present (true) when the resolved place or economic place is a census-designated place (CDP): an unincorporated community the Census delineates for statistics, with no municipal government. Its code is queried like an incorporated place's. Absent for an incorporated place and every other level. | |
| county_subdivision_fips | No | 5-digit county subdivision FIPS code: the resolved town, township, or other county subdivision (the same code as fips_summary), or for a street address the county subdivision the address sits in — query it at geography_level "county subdivision" with this as geography_fips, state_fips as parent_fips, and county_fips. A Connecticut subdivision carries its planning-region county (110–190), the one vintages from 2022 publish it under; vintages through 2021 publish it under the county from before 2022. |