REST reference

Available[4 endpoints]View as Markdown

Geography

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

Paths are relative to https://api.agentdatasets.com. Every endpoint mirrors an MCP tool over the same service layer — the tool catalog documents the same operations for MCP clients.

GET/v1/geo/geographies/{geography_id}

Get

Return one canonical geography and its parent/crosswalk context.

Parameters

NameInTypeRequiredDefaultConstraintsDescription
geography_idpathstringYes——Stable geography_id returned by geo_resolve

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

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

Response

200 Successful Response · expand a branch to see its fields.

  • dataGeoGetDatarequired
    • geographyGeographyDetailrequiredGeography identity plus containment ancestors and outgoing crosswalks.
      • geography_idstringrequired
      • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
      • codestringrequired
      • namestringrequired
      • country"US" | "AU"required
      • state_codestringrequirednullable
      • sourcestringrequired
      • as_ofstring (date-time)required
      • attributionstringnullable
      • parentsarray<agent_datasets__geo__schemas__GeographyRef>required
        • geography_idstringrequired
        • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
        • codestringrequired
        • namestringrequired
        • country"US" | "AU"required
        • state_codestringrequirednullable
        • sourcestringrequired
        • as_ofstring (date-time)required
        • attributionstringnullable
      • crosswalksarray<GeographyCrosswalk>required
        • geographyagent_datasets__geo__schemas__GeographyRefrequiredStable geography identity with row-level provenance.
          • geography_idstringrequired
          • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
          • codestringrequired
          • namestringrequired
          • country"US" | "AU"required
          • state_codestringrequirednullable
          • sourcestringrequired
          • as_ofstring (date-time)required
          • attributionstringnullable
        • relation"zcta_county" | "county_cbsa"required
        • weightstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • sourcestringrequired
        • vintagestringrequired
        • as_ofstring (date-time)required
      • crosswalks_truncatedbooleanrequired
  • metaMetarequiredResult-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.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

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

Contains

Page descendants at a requested containment level.

Parameters

NameInTypeRequiredDefaultConstraintsDescription
geography_idpathstringYes——Stable geography_id returned by geo_resolve
child_levelquery"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"Yes——Descendant geography level to return
limitqueryintegerNo50min 1, max 200Descendants to return per page
cursorquerystring | nullNo——Opaque cursor from pagination.next_cursor

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ 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 · expand a branch to see its fields.

  • dataGeoContainsDatarequired
    • geography_idstringrequired
    • child_level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
    • childrenarray<agent_datasets__geo__schemas__GeographyRef>required
      • geography_idstringrequired
      • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
      • codestringrequired
      • namestringrequired
      • country"US" | "AU"required
      • state_codestringrequirednullable
      • sourcestringrequired
      • as_ofstring (date-time)required
      • attributionstringnullable
  • metaMetarequiredResult-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.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

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

Crosswalk

Page official outgoing crosswalks to a requested geography level.

Parameters

NameInTypeRequiredDefaultConstraintsDescription
geography_idpathstringYes——Stable geography_id returned by geo_resolve
target_levelquery"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"Yes——Official crosswalk target level
limitqueryintegerNo50min 1, max 200Crosswalk targets to return per page
cursorquerystring | nullNo——Opaque cursor from pagination.next_cursor

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ 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 · expand a branch to see its fields.

  • dataGeoCrosswalkDatarequired
    • geography_idstringrequired
    • target_level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
    • crosswalksarray<GeographyCrosswalk>required
      • geographyagent_datasets__geo__schemas__GeographyRefrequiredStable geography identity with row-level provenance.
        • geography_idstringrequired
        • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
        • codestringrequired
        • namestringrequired
        • country"US" | "AU"required
        • state_codestringrequirednullable
        • sourcestringrequired
        • as_ofstring (date-time)required
        • attributionstringnullable
      • relation"zcta_county" | "county_cbsa"required
      • weightstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
      • sourcestringrequired
      • vintagestringrequired
      • as_ofstring (date-time)required
  • metaMetarequiredResult-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.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable

GET/v1/geo/geographies/resolve

Resolve

Resolve a place or official code to canonical geography entities.

Parameters

NameTypeRequiredDefaultConstraintsDescription
querystringYes——Free-text place, alias, postal abbreviation, or official code
level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga" | nullNo——Optional canonical geography level filter
country"US" | "AU" | nullNo——Optional country filter: US or AU
limitintegerNo10min 1, max 50Maximum ranked matches to return

Example request

Required parameters only, with values taken from the schema. Optional parameters are in the table above.

[ 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 · expand a branch to see its fields.

  • dataGeoResolveDatarequired
    • querystringrequired
    • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"requirednullable
    • country"US" | "AU"requirednullable
    • matchesarray<GeographyMatch>required
      • geography_idstringrequired
      • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
      • codestringrequired
      • namestringrequired
      • country"US" | "AU"required
      • state_codestringrequirednullable
      • sourcestringrequired
      • as_ofstring (date-time)required
      • attributionstringnullable
      • parentsarray<agent_datasets__geo__schemas__GeographyRef>required
        • geography_idstringrequired
        • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
        • codestringrequired
        • namestringrequired
        • country"US" | "AU"required
        • state_codestringrequirednullable
        • sourcestringrequired
        • as_ofstring (date-time)required
        • attributionstringnullable
      • crosswalksarray<GeographyCrosswalk>required
        • geographyagent_datasets__geo__schemas__GeographyRefrequiredStable geography identity with row-level provenance.
          • geography_idstringrequired
          • level"nation" | "state" | "county" | "cbsa" | "zip3" | "zcta" | "au_state" | "au_gccsa" | "au_sa4" | "au_sa3" | "au_lga"required
          • codestringrequired
          • namestringrequired
          • country"US" | "AU"required
          • state_codestringrequirednullable
          • sourcestringrequired
          • as_ofstring (date-time)required
          • attributionstringnullable
        • relation"zcta_county" | "county_cbsa"required
        • weightstringrequirednullablepattern ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
        • sourcestringrequired
        • vintagestringrequired
        • as_ofstring (date-time)required
      • crosswalks_truncatedbooleanrequired
      • scorenumberrequired
      • match_reason"code_exact" | "postal_exact" | "name_exact" | "alias_exact" | "name_fuzzy" | "alias_fuzzy"required
  • metaMetarequiredResult-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.
    • sourcestringrequired
    • as_ofstring (date-time) | string (date)nullable
  • paginationPaginationnullable
    • limitintegerrequired
    • has_morebooleanrequired
    • next_cursorstringnullable