<!-- Agent Datasets docs · Geography REST endpoints · canonical: https://www.agentdatasets.com/docs/rest/geography · rendered from https://www.agentdatasets.com -->

# Geography REST endpoints

Canonical US Census/OMB and Australian ABS ASGS geography identity, containment hierarchies, aliases, and official crosswalks.

4 endpoints. Paths are relative to `https://api.agentdatasets.com`. Every endpoint mirrors an MCP tool over the same service layer — https://www.agentdatasets.com/docs/tools.md documents the same operations for MCP clients.

## GET /v1/geo/geographies/{geography_id}

Get

Return one canonical geography and its parent/crosswalk context.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| geography_id | path | `string` | yes | — | — | Stable geography_id returned by geo_resolve |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/geo/geographies/GEOGRAPHY_ID"
```

### Response

`200` Successful Response — `GeoGetResult`.

- `data` `GeoGetData` (required)
  - `geography` `GeographyDetail` (required) — Geography identity plus containment ancestors and outgoing crosswalks.
    - `geography_id` `string` (required)
    - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
    - `code` `string` (required)
    - `name` `string` (required)
    - `country` `"US" | "AU"` (required)
    - `state_code` `string | null` (required)
    - `source` `string` (required)
    - `as_of` `string (date-time)` (required)
    - `attribution` `string | null`
    - `parents` `array<agent_datasets__geo__schemas__GeographyRef>` (required)
      - `geography_id` `string` (required)
      - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
      - `code` `string` (required)
      - `name` `string` (required)
      - `country` `"US" | "AU"` (required)
      - `state_code` `string | null` (required)
      - `source` `string` (required)
      - `as_of` `string (date-time)` (required)
      - `attribution` `string | null`
    - `crosswalks` `array<GeographyCrosswalk>` (required)
      - `geography` `agent_datasets__geo__schemas__GeographyRef` (required) — Stable geography identity with row-level provenance.
      - `relation` `"zcta_county" | "county_cbsa"` (required)
      - `weight` `string | null` (required)
      - `source` `string` (required)
      - `vintage` `string` (required)
      - `as_of` `string (date-time)` (required)
    - `crosswalks_truncated` `boolean` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/geo/geographies/{geography_id}/contains

Contains

Page descendants at a requested containment level.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| geography_id | path | `string` | yes | — | — | Stable geography_id returned by geo_resolve |
| child_level | query | `"nation" \| "state" \| "county" \| "cbsa" \| "zip3" \| "zcta" \| "au_state" \| "au_gccsa" \| "au_sa4" \| "au_sa3" \| "au_lga"` | yes | — | — | Descendant geography level to return |
| limit | query | `integer` | no | 50 | min 1, max 200 | Descendants to return per page |
| cursor | query | `string \| null` | no | — | — | Opaque cursor from pagination.next_cursor |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/geo/geographies/GEOGRAPHY_ID/contains?child_level=CHILD_LEVEL"
```

### Response

`200` Successful Response — `GeoContainsResult`.

- `data` `GeoContainsData` (required)
  - `geography_id` `string` (required)
  - `child_level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
  - `children` `array<agent_datasets__geo__schemas__GeographyRef>` (required)
    - `geography_id` `string` (required)
    - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
    - `code` `string` (required)
    - `name` `string` (required)
    - `country` `"US" | "AU"` (required)
    - `state_code` `string | null` (required)
    - `source` `string` (required)
    - `as_of` `string (date-time)` (required)
    - `attribution` `string | null`
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/geo/geographies/{geography_id}/crosswalk

Crosswalk

Page official outgoing crosswalks to a requested geography level.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| geography_id | path | `string` | yes | — | — | Stable geography_id returned by geo_resolve |
| target_level | query | `"nation" \| "state" \| "county" \| "cbsa" \| "zip3" \| "zcta" \| "au_state" \| "au_gccsa" \| "au_sa4" \| "au_sa3" \| "au_lga"` | yes | — | — | Official crosswalk target level |
| limit | query | `integer` | no | 50 | min 1, max 200 | Crosswalk targets to return per page |
| cursor | query | `string \| null` | no | — | — | Opaque cursor from pagination.next_cursor |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/geo/geographies/GEOGRAPHY_ID/crosswalk?target_level=TARGET_LEVEL"
```

### Response

`200` Successful Response — `GeoCrosswalkResult`.

- `data` `GeoCrosswalkData` (required)
  - `geography_id` `string` (required)
  - `target_level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
  - `crosswalks` `array<GeographyCrosswalk>` (required)
    - `geography` `agent_datasets__geo__schemas__GeographyRef` (required) — Stable geography identity with row-level provenance.
      - `geography_id` `string` (required)
      - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
      - `code` `string` (required)
      - `name` `string` (required)
      - `country` `"US" | "AU"` (required)
      - `state_code` `string | null` (required)
      - `source` `string` (required)
      - `as_of` `string (date-time)` (required)
      - `attribution` `string | null`
    - `relation` `"zcta_county" | "county_cbsa"` (required)
    - `weight` `string | null` (required)
    - `source` `string` (required)
    - `vintage` `string` (required)
    - `as_of` `string (date-time)` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json

## GET /v1/geo/geographies/resolve

Resolve

Resolve a place or official code to canonical geography entities.

### Parameters

| Parameter | In | Type | Required | Default | Constraints | Description |
| --- | --- | --- | --- | --- | --- | --- |
| query | query | `string` | yes | — | — | Free-text place, alias, postal abbreviation, or official code |
| level | query | `"nation" \| "state" \| "county" \| "cbsa" \| "zip3" \| "zcta" \| "au_state" \| "au_gccsa" \| "au_sa4" \| "au_sa3" \| "au_lga" \| null` | no | — | — | Optional canonical geography level filter |
| country | query | `"US" \| "AU" \| null` | no | — | — | Optional country filter: US or AU |
| limit | query | `integer` | no | 10 | min 1, max 50 | Maximum ranked matches to return |

### Example request

Required parameters only, with values taken from the schema.

```bash
curl --fail --silent --show-error \
  --header "X-API-KEY: adk_..." \
  "https://api.agentdatasets.com/v1/geo/geographies/resolve?query=QUERY"
```

### Response

`200` Successful Response — `GeoResolveResult`.

- `data` `GeoResolveData` (required)
  - `query` `string` (required)
  - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga" | null` (required)
  - `country` `"US" | "AU" | null` (required)
  - `matches` `array<GeographyMatch>` (required)
    - `geography_id` `string` (required)
    - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
    - `code` `string` (required)
    - `name` `string` (required)
    - `country` `"US" | "AU"` (required)
    - `state_code` `string | null` (required)
    - `source` `string` (required)
    - `as_of` `string (date-time)` (required)
    - `attribution` `string | null`
    - `parents` `array<agent_datasets__geo__schemas__GeographyRef>` (required)
      - `geography_id` `string` (required)
      - `level` `"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"` (required)
      - `code` `string` (required)
      - `name` `string` (required)
      - `country` `"US" | "AU"` (required)
      - `state_code` `string | null` (required)
      - `source` `string` (required)
      - `as_of` `string (date-time)` (required)
      - `attribution` `string | null`
    - `crosswalks` `array<GeographyCrosswalk>` (required)
      - `geography` `agent_datasets__geo__schemas__GeographyRef` (required) — Stable geography identity with row-level provenance.
      - `relation` `"zcta_county" | "county_cbsa"` (required)
      - `weight` `string | null` (required)
      - `source` `string` (required)
      - `vintage` `string` (required)
      - `as_of` `string (date-time)` (required)
    - `crosswalks_truncated` `boolean` (required)
    - `score` `number` (required)
    - `match_reason` `"code_exact" | "postal_exact" | "name_exact" | "alias_exact" | "name_fuzzy" | "alias_fuzzy"` (required)
- `meta` `Meta` (required) — Result-level provenance. ``source`` is a stable connector identifier (e.g. ``sec_edgar_companyfacts``); ``as_of`` is the freshest value-level ``as_of`` on the returned page, or ``None`` when the page is empty. Event-grained sources carry an aware datetime; date-grained sources (e.g. an SEC filing's report period) carry a plain date.
  - `source` `string` (required)
  - `as_of` `string (date-time) | string (date) | null`
- `pagination` `Pagination | null`
  - `limit` `integer` (required)
  - `has_more` `boolean` (required)
  - `next_cursor` `string | null`

Fields are shown to 3 levels; the full schema is in https://www.agentdatasets.com/docs/machine/openapi.json