API Reference · Lookup

Location Search

Search and normalize AON Location Registry ids for location pickers, Offer-side geographic targeting, and the optional Query v1.0 viewer location.

Reference provenance and Query boundary

All three public Location operations on this page are implemented by the current runtime. They are documented here as a docs-curated runtime reference because the checked-in service OpenAPI does not yet include /v1/locations/*. That OpenAPI gap does not change their public runtime availability.

Use the results for registry lookup, normalization, verified ancestry, location pickers, or authoring Offer-side geographic targeting. A resolved id can also be sent as the optional Query v1.0 viewer location in context.user_profile.location_ids.

GET/v1/locations/searchPublic

Search legacy or full-catalog locations

Public operation

Query Parameters

Catalog selector, search text, and catalog-specific constraints.

Fields

11·0 required/11 optional

Showing the complete documented schema.

catalogstring

optional

Catalog representation. Omit it or use LEGACY for the compatible three-level registry; use FULL to search every ACTIVE Google Geo Target record.

example: FULLdefault: LEGACYAllowed valuesLEGACYFULL

qstring

optional

Case-insensitive search text. For FULL it matches name, canonical_name, location_id, and country code and is required unless parent_location_id is supplied; LEGACY also supports aliases and top-level levels=COUNTRY browsing.

example: California

parent_location_idstring

optional

Numeric parent id used for direct-child browsing. FULL restricts results to the exact verified canonical parent; LEGACY supports the Country -> Region -> City cascade.

example: 2840pattern: ^[0-9]+$

countrystring

optional

Optional uppercase ISO 3166-1 alpha-2 country code used to narrow results.

example: USpattern: ^[A-Z]{2}$

target_typesstring[]

optional

FULL only. Comma-separated exact raw Google Geo Target types, such as Postal Code, Neighborhood, Ward, or City; this is not a normalized AON level filter.

example: Postal Code,Neighborhood

subdivision_codestring

optional

LEGACY only. Optional first-level subdivision lookup code, such as ISO 3166-2 `US-CA`, CLDR `USCA`, or provider short code `CA` when country is supplied. FULL rejects this parameter.

example: US-CA

subdivision_code_typestring

optional

LEGACY only. How to interpret subdivision_code. AUTO detects supported ISO 3166-2, CLDR, or country-scoped provider short forms; FULL rejects this parameter.

example: AUTOdefault: AUTOAllowed valuesAUTOISO_3166_2CLDRPROVIDER_SHORT

levelsstring[]

optional

LEGACY only. Optional comma-separated subset of COUNTRY, REGION, and CITY; FULL rejects this parameter because target_types preserves the raw source type.

example: REGION,CITYAllowed valuesCOUNTRYREGIONCITY

limitinteger

optional

Maximum results to return. Default is 20 and maximum is 50.

example: 20minimum: 1maximum: 50

cursorstring

optional

FULL only. Opaque continuation cursor returned in data.next_cursor; reuse it only with the same FULL query constraints.

example: opaque-continuation-cursor

localestring

optional

Reserved for future localized names. v0.1 results use registry names.

example: en

Request Examples

Search full-catalog postal codes

curl

curl -G https://api.aon.pro/v1/locations/search \
  --data-urlencode "catalog=FULL" \
  --data-urlencode "q=522410" \
  --data-urlencode "country=IN" \
  --data-urlencode "target_types=Postal Code"

Returns matching locations in the standard success envelope; data.catalog discriminates the FULL response from the unchanged LEGACY shape.

Fields

35·15 required/16 conditional/4 optional

Showing the complete documented schema.

codestring

required

Platform status code for the request.

example: SUCCESSAllowed valuesSUCCESS

messagestring

required

Human-readable status message. Empty string on normal success.

object

required

Catalog-aware Location Search results. Omitted catalog keeps the compatible LEGACY response shape; catalog=FULL returns the full active catalog shape.

6 nested fields

catalogstring

required when catalog=FULL

FULL only. Always FULL; absent from the LEGACY response shape.

example: FULLAllowed valuesFULL

catalog_versionstring

required when catalog=FULL

FULL only. Full catalog version; absent from the LEGACY response shape.

example: v1

registry_versionstring

required when catalog is omitted or LEGACY

LEGACY only. AON Location Registry version; absent from the FULL response shape.

example: v1

source_file_datestring

required

Pinned Google Geo Targets source file date for the selected catalog.

example: 2026-05-28format: date

object[]

required

Matching LEGACY registry locations or ACTIVE FULL catalog records.

14 nested fields

Required or conditional

location_idstring

required

Numeric-string location id aligned to Google Geo Target Criteria ID.

example: 21137pattern: ^[0-9]+$

namestring

required

Short display name.

example: 522410

canonical_namestring

required

Provider canonical location name.

example: California,United States

country_codestring

required

Uppercase ISO 3166-1 alpha-2 country code.

example: INpattern: ^[A-Z]{2}$

target_typestring

required

Exact raw Google Geo Target type. FULL never normalizes this field to COUNTRY, REGION, or CITY.

example: Postal Code

levelstring

required when catalog is omitted or LEGACY

LEGACY only. AON-normalized supported location level; FULL never returns level.

example: REGIONAllowed valuesCOUNTRYREGIONCITY

source_parent_location_idstring | null

required when catalog=FULL

FULL only. Raw Parent ID from the source CSV.

example: 20453

parent_location_idstring | null

required

LEGACY uses the immediate registry parent; FULL uses only a verified ACTIVE source-parent edge and is null when no parent relation can be verified.

example: 2840

object[]

required

Root-to-self path. FULL includes only verified parent relations and never invents missing hierarchy segments.

8 nested fields

location_idstring

required

Path node numeric location id.

example: 20453

namestring

required

Path node display name.

example: Andhra Pradesh

canonical_namestring

required when catalog=FULL

FULL only. Path node canonical name.

example: Andhra Pradesh,India

country_codestring

required when catalog=FULL

FULL only. Path node uppercase ISO 3166-1 alpha-2 country code.

example: IN

target_typestring

required when catalog=FULL

FULL only. Path node raw Google Geo Target type.

example: State

levelstring

required when catalog is omitted or LEGACY

LEGACY only. Path node normalized AON location level.

example: REGIONAllowed valuesCOUNTRYREGIONCITY

hierarchy_precisioninteger

required when catalog=FULL

FULL only. One-based verified depth for this path node.

example: 2minimum: 1

legacy_levelstring

required when catalog=FULL and representable by LEGACY

FULL only. Optional compatible COUNTRY, REGION, or CITY label without relabeling the raw type.

example: REGIONAllowed valuesCOUNTRYREGIONCITY

hierarchy_precisioninteger

required when catalog=FULL

FULL only. One-based verified hierarchy depth used for safe targeting evaluation.

example: 3minimum: 1

legacy_levelstring

required when catalog=FULL and representable by LEGACY

FULL only. Optional compatible COUNTRY, REGION, or CITY label; FULL never returns level.

example: REGIONAllowed valuesCOUNTRYREGIONCITY

chain_statusstring

required when catalog=FULL

FULL only. COMPLETE or UNRESOLVED_SOURCE_PARENT.

example: COMPLETEAllowed valuesCOMPLETEUNRESOLVED_SOURCE_PARENT

unresolved_source_parent_location_idstring

required when catalog=FULL and chain_status=UNRESOLVED_SOURCE_PARENT

FULL only. Raw source parent id that could not be resolved; it is never added to path or location_ids.

example: 2364

Optional

object

optional

LEGACY only. Optional lookup aliases for supported external location code systems. Matching still uses AON location_id values.

3 nested fieldsexample: { "iso_3166_2": "US-CA", "cldr_subdivision": "USCA", "provider_short": "CA" }

next_cursorstring

required when catalog=FULL and another page exists

FULL only. Opaque continuation cursor; absent on the final page.

example: opaque-continuation-cursor

extraobject

required

Optional metadata bag for warnings, pagination, or future expansion.

example: {}

Response Examples

FULL catalog search response

JSON

{
  "code": "SUCCESS",
  "message": "",
  "data": {
    "catalog": "FULL",
    "catalog_version": "v1",
    "source_file_date": "2026-05-28",
    "locations": [
      {
        "location_id": "9304101",
        "name": "522410",
        "canonical_name": "522410,Andhra Pradesh,India",
        "country_code": "IN",
        "target_type": "Postal Code",
        "source_parent_location_id": "20453",
        "parent_location_id": "20453",
        "path": [
          {
            "location_id": "2356",
            "name": "India",
            "canonical_name": "India",
            "country_code": "IN",
            "target_type": "Country",
            "hierarchy_precision": 1
          },
          {
            "location_id": "20453",
            "name": "Andhra Pradesh",
            "canonical_name": "Andhra Pradesh,India",
            "country_code": "IN",
            "target_type": "State",
            "hierarchy_precision": 2
          },
          {
            "location_id": "9304101",
            "name": "522410",
            "canonical_name": "522410,Andhra Pradesh,India",
            "country_code": "IN",
            "target_type": "Postal Code",
            "hierarchy_precision": 3
          }
        ],
        "hierarchy_precision": 3,
        "chain_status": "COMPLETE"
      }
    ],
    "next_cursor": "opaque-continuation-cursor"
  },
  "extra": {}
}

Behavior, compatibility, and source notes

Runtime API for selecting registry ids for location pickers, migration, normalization, and Offer-side geographic targeting authoring. Omit catalog for the compatible three-level LEGACY registry, or use catalog=FULL to search every ACTIVE Google Geo Target record.

This route is a lookup companion to the static registry, not a caller-side offer search filter.
Omit catalog or use LEGACY to preserve the existing Country -> Region -> City selector behavior and response shape.
Use catalog=FULL with target_types to search raw types such as Postal Code, Neighborhood, or Ward; FULL rejects levels and subdivision-code filters.
FULL path and hierarchy_precision expose only verified source-parent relations, so unresolved parents are visible rather than inferred.

GET/v1/locations/resolvePublic

Resolve legacy signals or a full-catalog id

Public operation

Query Parameters

Catalog selector plus a LEGACY external signal or a FULL direct location_id.

Fields

7·0 required/1 conditional/6 optional

Showing the complete documented schema.

Required or conditional

location_idstring

required when catalog=FULL

FULL only and required in FULL mode. Numeric active full-catalog location id selected from FULL search; FULL resolve rejects legacy normalization parameters.

example: 9304101pattern: ^[0-9]+$

Optional

catalogstring

optional

Catalog representation. Omit it or use LEGACY to normalize external location signals; use FULL for a direct active location_id lookup.

example: FULLdefault: LEGACYAllowed valuesLEGACYFULL

countrystring

optional

LEGACY only. Optional ISO 3166-1 alpha-2 country code, required when resolving provider short subdivision codes such as `CA`. FULL rejects this parameter.

example: USpattern: ^[A-Z]{2}$

subdivision_codestring

optional

LEGACY only. External first-level subdivision code to normalize before writing AON location_id values. FULL rejects this parameter.

example: US-CA

subdivision_code_typestring

optional

LEGACY only. Code family for subdivision_code. AUTO detects supported ISO 3166-2, CLDR, or provider short forms; FULL rejects this parameter.

example: ISO_3166_2default: AUTOAllowed valuesAUTOISO_3166_2CLDRPROVIDER_SHORT

citystring

optional

LEGACY only. Optional city text matched under the resolved country or subdivision. Partial city names are supported; FULL rejects this parameter.

example: San Francisco

limitinteger

optional

LEGACY only. Maximum candidates to return. Default is 10 and maximum is 50; FULL resolve returns the direct selected id and rejects this parameter.

example: 10minimum: 1maximum: 50

Returns the resolved location, candidate locations, and the self-to-root location_ids chain for the selected catalog.

Fields

29·16 required/9 conditional/4 optional

Showing the complete documented schema.

codestring

required

Platform status code for the request.

example: SUCCESSAllowed valuesSUCCESS

messagestring

required

Human-readable status message. Empty string on normal success.

object

required

Resolved location and self-to-root registry ancestry for the selected catalog.

8 nested fields

catalogstring

required when catalog=FULL

FULL only. Always FULL; absent from the LEGACY response shape.

example: FULLAllowed valuesFULL

catalog_versionstring

required when catalog=FULL

FULL only. Full catalog version; absent from the LEGACY response shape.

example: v1

registry_versionstring

required when catalog is omitted or LEGACY

LEGACY only. AON Location Registry version; absent from the FULL response shape.

example: v1

source_file_datestring

required

Pinned Google Geo Targets source file date for the selected catalog.

example: 2026-05-28format: date

object

required

FULL returns the direct active location_id. LEGACY returns the best normalized location; unsupported input returns an error envelope rather than a null success.

14 nested fields

Required or conditional

location_idstring

required

Numeric-string location id aligned to Google Geo Target Criteria ID.

example: 9304101pattern: ^[0-9]+$

namestring

required

Short display name.

example: 522410

canonical_namestring

required

Provider canonical location name.

example: 522410,Andhra Pradesh,India

country_codestring

required

Uppercase ISO 3166-1 alpha-2 country code.

example: INpattern: ^[A-Z]{2}$

target_typestring

required

Exact raw Google Geo Target type. FULL never normalizes this field to COUNTRY, REGION, or CITY.

example: Postal Code

levelstring

required when catalog is omitted or LEGACY and data.location is present

LEGACY only. AON-normalized supported location level; FULL never returns level.

example: REGIONAllowed valuesCOUNTRYREGIONCITY

source_parent_location_idstring | null

required when catalog=FULL

FULL only. Raw Parent ID from the source CSV.

example: 20453

parent_location_idstring | null

required

LEGACY uses the immediate registry parent; FULL uses only a verified ACTIVE source-parent edge.

example: 20453

hierarchy_precisioninteger

required when catalog=FULL

FULL only. One-based verified hierarchy depth used for safe targeting evaluation.

example: 3minimum: 1

legacy_levelstring

required when catalog=FULL and representable by LEGACY

FULL only. Optional compatible COUNTRY, REGION, or CITY label; FULL never returns level.

example: REGIONAllowed valuesCOUNTRYREGIONCITY

chain_statusstring

required when catalog=FULL

FULL only. COMPLETE or UNRESOLVED_SOURCE_PARENT.

example: COMPLETEAllowed valuesCOMPLETEUNRESOLVED_SOURCE_PARENT

unresolved_source_parent_location_idstring

required when catalog=FULL and chain_status=UNRESOLVED_SOURCE_PARENT

FULL only. Raw source parent id that could not be resolved.

example: 2364

path[]object[]

required

Root-to-self path. FULL includes only verified parent relations and never invents missing hierarchy segments.

Optional

object

optional

LEGACY only. Lookup aliases mapped to this location when available.

3 nested fieldsexample: { "iso_3166_2": "US-CA", "cldr_subdivision": "USCA", "provider_short": "CA" }

path[]object[]

required

Same root-to-self path as data.location.path.

location_ids[]string[]

required

Self-to-root registry ancestry ids for persistence and Offer-side targeting authoring. This response field is not a Query v1.0 viewer input.

example: 21137pattern: ^[0-9]+$

candidates[]object[]

required

LEGACY candidate locations after applying normalized constraints. FULL returns an empty array after direct active-id resolution.

extraobject

required

Optional metadata bag for warnings, pagination, or future expansion.

example: {}

Response Examples

FULL catalog direct-id resolve

JSON

{
  "code": "SUCCESS",
  "message": "",
  "data": {
    "catalog": "FULL",
    "catalog_version": "v1",
    "source_file_date": "2026-05-28",
    "location": {
      "location_id": "9304101",
      "name": "522410",
      "canonical_name": "522410,Andhra Pradesh,India",
      "country_code": "IN",
      "target_type": "Postal Code",
      "source_parent_location_id": "20453",
      "parent_location_id": "20453",
      "path": [
        {
          "location_id": "2356",
          "name": "India",
          "canonical_name": "India",
          "country_code": "IN",
          "target_type": "Country",
          "hierarchy_precision": 1
        },
        {
          "location_id": "20453",
          "name": "Andhra Pradesh",
          "canonical_name": "Andhra Pradesh,India",
          "country_code": "IN",
          "target_type": "State",
          "hierarchy_precision": 2
        },
        {
          "location_id": "9304101",
          "name": "522410",
          "canonical_name": "522410,Andhra Pradesh,India",
          "country_code": "IN",
          "target_type": "Postal Code",
          "hierarchy_precision": 3
        }
      ],
      "hierarchy_precision": 3,
      "chain_status": "COMPLETE"
    },
    "path": [
      {
        "location_id": "2356",
        "name": "India",
        "canonical_name": "India",
        "country_code": "IN",
        "target_type": "Country",
        "hierarchy_precision": 1
      },
      {
        "location_id": "20453",
        "name": "Andhra Pradesh",
        "canonical_name": "Andhra Pradesh,India",
        "country_code": "IN",
        "target_type": "State",
        "hierarchy_precision": 2
      },
      {
        "location_id": "9304101",
        "name": "522410",
        "canonical_name": "522410,Andhra Pradesh,India",
        "country_code": "IN",
        "target_type": "Postal Code",
        "hierarchy_precision": 3
      }
    ],
    "location_ids": [
      "9304101",
      "20453",
      "2356"
    ],
    "candidates": []
  },
  "extra": {}
}

Behavior, compatibility, and source notes

Runtime API for normalizing external location signals in LEGACY mode or resolving an active FULL catalog location_id with its verified registry ancestry.

Use LEGACY when an integration has external subdivision codes or edge location headers.
Use catalog=FULL with location_id selected by FULL search; FULL rejects legacy normalization parameters and returns an empty candidates array.
The response location_ids array is a self-to-root registry ancestry chain; send its first (most specific) id as Query v1.0 context.user_profile.location_ids rather than the whole chain.
External codes are LEGACY lookup aliases only and are not Offer or Query matching keys.

GET/v1/locations/{location_id}Public

Look up one legacy or full-catalog location

Public operation

Path Parameters

Legacy Registry v1 id or active FULL catalog id to resolve.

Fields

1·1 required

Showing the complete documented schema.

location_idstring

required

Numeric-string location id. LEGACY accepts Registry v1 ids; FULL accepts any ACTIVE full-catalog Google Criteria ID.

example: 9304101pattern: ^[0-9]+$

Query Parameters

Catalog selector for the exact-id lookup.

Fields

1·0 required/1 optional

Showing the complete documented schema.

catalogstring

optional

Catalog representation. Omit it or use LEGACY for Registry v1; use FULL for any ACTIVE full-catalog location id.

example: FULLdefault: LEGACYAllowed valuesLEGACYFULL

Returns one location object and the self-to-root location_ids chain for the selected catalog.

Fields

24·15 required/9 conditional

Showing the complete documented schema.

codestring

required

Platform status code for the request.

example: SUCCESSAllowed valuesSUCCESS

messagestring

required

Human-readable status message. Empty string on normal success.

object

required

Exact location lookup result and self-to-root registry ancestry for the selected catalog.

7 nested fields

catalogstring

required when catalog=FULL

FULL only. Always FULL; absent from the LEGACY response shape.

example: FULLAllowed valuesFULL

catalog_versionstring

required when catalog=FULL

FULL only. Full catalog version; absent from the LEGACY response shape.

example: v1

registry_versionstring

required when catalog is omitted or LEGACY

LEGACY only. AON Location Registry version; absent from the FULL response shape.

example: v1

source_file_datestring

required

Pinned Google Geo Targets source file date for the selected catalog.

example: 2026-05-28format: date

object

required

Single Location Search result object.

13 nested fields

location_idstring

required

Numeric-string location id aligned to Google Geo Target Criteria ID.

example: 9304101pattern: ^[0-9]+$

namestring

required

Short display name.

example: 522410

canonical_namestring

required

Provider canonical location name.

example: 522410,Andhra Pradesh,India

country_codestring

required

Uppercase ISO 3166-1 alpha-2 country code.

example: INpattern: ^[A-Z]{2}$

target_typestring

required

Exact raw Google Geo Target type. FULL never normalizes this field to COUNTRY, REGION, or CITY.

example: Postal Code

levelstring

required when catalog is omitted or LEGACY

LEGACY only. AON-normalized supported location level; FULL never returns level.

example: CITYAllowed valuesCOUNTRYREGIONCITY

source_parent_location_idstring | null

required when catalog=FULL

FULL only. Raw Parent ID from the source CSV.

example: 20453

parent_location_idstring | null

required

LEGACY uses the immediate registry parent; FULL uses only a verified ACTIVE source-parent edge.

example: 20453

hierarchy_precisioninteger

required when catalog=FULL

FULL only. One-based verified hierarchy depth used for safe targeting evaluation.

example: 3minimum: 1

legacy_levelstring

required when catalog=FULL and representable by LEGACY

FULL only. Optional compatible COUNTRY, REGION, or CITY label; FULL never returns level.

example: REGIONAllowed valuesCOUNTRYREGIONCITY

chain_statusstring

required when catalog=FULL

FULL only. COMPLETE or UNRESOLVED_SOURCE_PARENT.

example: COMPLETEAllowed valuesCOMPLETEUNRESOLVED_SOURCE_PARENT

unresolved_source_parent_location_idstring

required when catalog=FULL and chain_status=UNRESOLVED_SOURCE_PARENT

FULL only. Raw source parent id that could not be resolved.

example: 2364

path[]object[]

required

Root-to-self path. FULL includes only verified parent relations and never invents missing hierarchy segments.

path[]object[]

required

Same root-to-self path as data.location.path.

location_ids[]string[]

required

Self-to-root registry ancestry ids for persistence and Offer-side targeting authoring. This response field is not a Query v1.0 viewer input.

example: 1014221pattern: ^[0-9]+$

extraobject

required

Optional metadata bag for warnings, pagination, or future expansion.

example: {}

Response Examples

FULL catalog lookup response

JSON

{
  "code": "SUCCESS",
  "message": "",
  "data": {
    "catalog": "FULL",
    "catalog_version": "v1",
    "source_file_date": "2026-05-28",
    "location": {
      "location_id": "9304101",
      "name": "522410",
      "canonical_name": "522410,Andhra Pradesh,India",
      "country_code": "IN",
      "target_type": "Postal Code",
      "source_parent_location_id": "20453",
      "parent_location_id": "20453",
      "path": [
        {
          "location_id": "2356",
          "name": "India",
          "canonical_name": "India",
          "country_code": "IN",
          "target_type": "Country",
          "hierarchy_precision": 1
        },
        {
          "location_id": "20453",
          "name": "Andhra Pradesh",
          "canonical_name": "Andhra Pradesh,India",
          "country_code": "IN",
          "target_type": "State",
          "hierarchy_precision": 2
        },
        {
          "location_id": "9304101",
          "name": "522410",
          "canonical_name": "522410,Andhra Pradesh,India",
          "country_code": "IN",
          "target_type": "Postal Code",
          "hierarchy_precision": 3
        }
      ],
      "hierarchy_precision": 3,
      "chain_status": "COMPLETE"
    },
    "path": [
      {
        "location_id": "2356",
        "name": "India",
        "canonical_name": "India",
        "country_code": "IN",
        "target_type": "Country",
        "hierarchy_precision": 1
      },
      {
        "location_id": "20453",
        "name": "Andhra Pradesh",
        "canonical_name": "Andhra Pradesh,India",
        "country_code": "IN",
        "target_type": "State",
        "hierarchy_precision": 2
      },
      {
        "location_id": "9304101",
        "name": "522410",
        "canonical_name": "522410,Andhra Pradesh,India",
        "country_code": "IN",
        "target_type": "Postal Code",
        "hierarchy_precision": 3
      }
    ],
    "location_ids": [
      "9304101",
      "20453",
      "2356"
    ]
  },
  "extra": {}
}

Behavior, compatibility, and source notes

Runtime API for exact id lookup and self-to-root registry ancestry construction in the selected catalog.

Use the returned data.location_ids array for persistence, display, or authoring Offer-side geographic targeting; to send the viewer's location, pass the ids in Query v1.0 context.user_profile.location_ids (most specific first).
Omit catalog or use LEGACY for Registry v1; use catalog=FULL for any ACTIVE full-catalog location id.
FULL derives the chain only from verified source-parent relations and preserves unresolved source parents in location metadata.

Implementation checklist · 3 items

Use the static registry as the source of truth for supported ids.
Store numeric-string location_id values rather than display names.
Treat returned location_ids chains as registry ancestry; send only the most specific trusted id as Query v1.0 context.user_profile.location_ids.

Location Targeting

Understand Offer-side geographic targeting and the public Query v1.0 boundary.

Offer Query

Review the current Query v1.0 request: optional context is bounded and excludes viewer-location inputs.

Errors & Rate Limits

Shared HTTP status, body envelope, and retry guidance.

Location Search

Operations

Related links