<!-- Agent Datasets docs · Geography guide · canonical: https://www.agentdatasets.com/docs/guides/geo · rendered from https://www.agentdatasets.com -->

# 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.

## 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

```python
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:

```python
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

```python
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

```python
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:

```python
geo_contains(geography_id="state_48", child_level="county", limit=50, cursor="eyJ2IjoxLCJrIjpbLi4uXX0")
```

### Follow an official crosswalk

```python
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_id` is the platform's existing canonical `geo_key`, such as `county_48201` or `au_gccsa_1gsyd`. Database row IDs are never exposed.
- **Parents and crosswalks mean different things.** `parents` follows the strict containment hierarchy. `crosswalks` records 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 `country` and `level` is `bad_parameter`.
- **Relationship vintages matter.** Administrative and statistical boundaries change. Preserve the returned crosswalk `source` and `vintage` when 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

| Tool | What it does | Reference |
| --- | --- | --- |
| `geo_contains` | Walk containment and return descendants at one requested level. | https://www.agentdatasets.com/docs/tools/geo_contains.md |
| `geo_crosswalk` | Return official crosswalk targets for one canonical geography. | https://www.agentdatasets.com/docs/tools/geo_crosswalk.md |
| `geo_get` | Fetch one canonical geography with its relationship context. | https://www.agentdatasets.com/docs/tools/geo_get.md |
| `geo_resolve` | Resolve a place or code to stable canonical geography IDs. | https://www.agentdatasets.com/docs/tools/geo_resolve.md |

Over HTTP: https://www.agentdatasets.com/docs/rest/geography.md