Geography
Canonical US Census/OMB and Australian ABS ASGS geography identity, containment hierarchies, aliases, and official crosswalks.
Where the data comes from
Every value this category returns is attributable to one of these publishers, and every payload carries the source tag with it.
| Source | Publisher | What we hold | Licence |
|---|---|---|---|
| abs_asgs | Australian Bureau of Statistics | Australian Statistical Geography Standard (ASGS) Edition 4: 2026 SA3-and-higher hierarchy, with Edition 3 2025 Local Government Areas | Creative Commons Attribution 4.0 International (cc-by-4.0) |
| census_geo | U.S. Census Bureau | State and county geography reference codes (2020 vintage) | U.S. Government work, public domain (us-gov-public-domain); standard Census non-endorsement caveat applies |
| census_rel2020 | U.S. Census Bureau | ZCTA-to-county relationship file (2020 vintage) | U.S. Government work, public domain (us-gov-public-domain); standard Census non-endorsement caveat applies |
| omb_delineation_2023 | Office of Management and Budget (delineation lists distributed via the U.S. Census Bureau) | Core-based statistical area (CBSA) delineation lists (2023 vintage) | U.S. Government work, public domain (us-gov-public-domain); standard Census non-endorsement caveat applies |
Required notices
- This product uses Census Bureau data but is not endorsed or certified by the Census Bureau.
Full licence text, attribution strings, and every source on the surface are in Attribution.
Resolve first, then traverse
Geography is an identity graph. Start with a name, alias, postal abbreviation, or official code and resolve it to a stable geography_id. Use that ID for exact lookup, containment, or an official crosswalk; do not guess IDs from display names.
US entities come from Census geography files and OMB delineations. Australian entities come from the ABS Australian Statistical Geography Standard and carry the required CC BY 4.0 attribution on every entity in the response.
Worked workflows
Resolve a place
geo_resolve(query="Sydney", country="AU", limit=10)The result is a bounded relevance list. Each match includes its stable ID, official level/code/name, country and state code, match reason and score, containment parents, outgoing official crosswalks, as_of, source, and attribution. pagination is null; narrow ambiguous searches with country or level.
For a qualified US county:
geo_resolve(query="Harris County, TX", country="US", level="county", limit=10)The Harris County match is county_48201. Its containment parents are Texas and the United States; its outgoing county_cbsa relationship points to the Houston CBSA and names the OMB source and vintage.
Inspect one exact entity
geo_get(geography_id="county_48201")This scalar response repeats the full identity and parent context and includes up to 50 official crosswalks. If crosswalks_truncated is true, use the paged crosswalk tool for the complete set. An unknown ID returns unknown_entity with suggestions when possible.
Walk containment
geo_contains(geography_id="state_48", child_level="county", limit=50)Containment can skip intermediate levels: ask a nation for counties or an Australian GCCSA for SA3s, and the service recursively walks the stored hierarchy. Children sort by geography_id. When pagination.has_more is true, pass the opaque cursor back with every other argument unchanged:
geo_contains(geography_id="state_48", child_level="county", limit=50, cursor="eyJ2IjoxLCJrIjpbLi4uXX0")Follow an official crosswalk
geo_crosswalk(geography_id="zcta_78701", target_level="county", limit=50)Crosswalk rows are not containment guesses. Each row states the relation, source, vintage, and exact decimal weight when the publisher supplies one. ZCTA-to-county relationships can be weighted because a ZCTA may span counties; county-to-CBSA relationships normally have no weight. Continue a long result with pagination.next_cursor.
Coverage and caveats
- IDs are stable strings.
geography_idis the platform's existing canonicalgeo_key, such ascounty_48201orau_gccsa_1gsyd. Database row IDs are never exposed. - Parents and crosswalks mean different things.
parentsfollows the strict containment hierarchy.crosswalksrecords an official relationship between schemes, such as county to CBSA or ZCTA to county. - The country universes differ. US levels are nation, state, county, CBSA, ZIP3, and ZCTA. Australian levels are nation, state/territory, GCCSA, SA4, SA3, and LGA. A conflicting
countryandlevelisbad_parameter. - Relationship vintages matter. Administrative and statistical boundaries change. Preserve the returned crosswalk
sourceandvintagewhen citing or joining results. - Static references refresh on release. Operators run the US seed after Census or OMB publishes updated reference files and the Australian seed after ABS publishes a new allocation; these sources are not polled.
Tools and endpoints
Each tool's full input schema, provenance, and bounds are on its own page; the REST endpoints mirror them one for one.
| Tool | What it does | Page size |
|---|---|---|
| geo_contains | Walk containment and return descendants at one requested level. | default 50 · min 1 · max 200 |
| geo_crosswalk | Return official crosswalk targets for one canonical geography. | default 50 · min 1 · max 200 |
| geo_get | Fetch one canonical geography with its relationship context. | scalar result |
| geo_resolve | Resolve a place or code to stable canonical geography IDs. | default 10 · min 1 · max 50 |
Over HTTP: Geography REST endpoints.