# Location Search Source: https://docs.aon.pro/api/location-search > Derived from the same AON Docs release as the source page. API Reference · Lookup Search and normalize AON Location Registry ids for location pickers and Offer-side geographic targeting without treating lookup results as Query v1.0 viewer inputs. > 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. Current Query v1.0 does not define a viewer-location input and rejects undeclared fields such as `context.user_profile.location_ids`. ## Operations ### GET /v1/locations/search **GET** `/v1/locations/search` Search legacy or full-catalog locations Authentication: Public. Source: Public operation. #### Request Query Parameters Catalog selector, search text, and catalog-specific constraints. ##### `catalog` Type: string. Requirement: 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: FULL - default: LEGACY Allowed values: `LEGACY`, `FULL` ##### `q` Type: string. Requirement: 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_id` Type: string. Requirement: 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: 2840 - pattern: ^\[0-9\]+$ ##### `country` Type: string. Requirement: optional. Optional uppercase ISO 3166-1 alpha-2 country code used to narrow results. - example: US - pattern: ^\[A-Z\]{2}$ ##### `target_types` Type: string\[\]. Requirement: 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_code` Type: string. Requirement: 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_type` Type: string. Requirement: 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: AUTO - default: AUTO Allowed values: `AUTO`, `ISO_3166_2`, `CLDR`, `PROVIDER_SHORT` ##### `levels` Type: string\[\]. Requirement: 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,CITY Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `limit` Type: integer. Requirement: optional. Maximum results to return. Default is 20 and maximum is 50. - example: 20 - minimum: 1 - maximum: 50 ##### `cursor` Type: string. Requirement: optional. FULL only. Opaque continuation cursor returned in data.next\_cursor; reuse it only with the same FULL query constraints. - example: opaque-continuation-cursor ##### `locale` Type: string. Requirement: optional. Reserved for future localized names. v0.1 results use registry names. - example: en Request Examples ##### Search full-catalog postal codes ```bash 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" ``` #### Response Returns matching locations in the standard success envelope; data.catalog discriminates the FULL response from the unchanged LEGACY shape. ##### `code` Type: string. Requirement: required. Platform status code for the request. - example: SUCCESS Allowed values: `SUCCESS` ##### `message` Type: string. Requirement: required. Human-readable status message. Empty string on normal success. ##### `data` Type: object. Requirement: required. Catalog-aware Location Search results. Omitted catalog keeps the compatible LEGACY response shape; catalog=FULL returns the full active catalog shape. ##### `data.catalog` Type: string. Requirement: required when catalog=FULL. FULL only. Always FULL; absent from the LEGACY response shape. - example: FULL Allowed values: `FULL` ##### `data.catalog_version` Type: string. Requirement: required when catalog=FULL. FULL only. Full catalog version; absent from the LEGACY response shape. - example: v1 ##### `data.registry_version` Type: string. Requirement: required when catalog is omitted or LEGACY. LEGACY only. AON Location Registry version; absent from the FULL response shape. - example: v1 ##### `data.source_file_date` Type: string. Requirement: required. Pinned Google Geo Targets source file date for the selected catalog. - example: 2026-05-28 - format: date ##### `data.locations[]` Type: object\[\]. Requirement: required. Matching LEGACY registry locations or ACTIVE FULL catalog records. ##### `data.locations[].location_id` Type: string. Requirement: required. Numeric-string location id aligned to Google Geo Target Criteria ID. - example: 21137 - pattern: ^\[0-9\]+$ ##### `data.locations[].name` Type: string. Requirement: required. Short display name. - example: 522410 ##### `data.locations[].canonical_name` Type: string. Requirement: required. Provider canonical location name. - example: California,United States ##### `data.locations[].country_code` Type: string. Requirement: required. Uppercase ISO 3166-1 alpha-2 country code. - example: IN - pattern: ^\[A-Z\]{2}$ ##### `data.locations[].target_type` Type: string. Requirement: required. Exact raw Google Geo Target type. FULL never normalizes this field to COUNTRY, REGION, or CITY. - example: Postal Code ##### `data.locations[].level` Type: string. Requirement: required when catalog is omitted or LEGACY. LEGACY only. AON-normalized supported location level; FULL never returns level. - example: REGION Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `data.locations[].source_parent_location_id` Type: string | null. Requirement: required when catalog=FULL. FULL only. Raw Parent ID from the source CSV. - example: 20453 ##### `data.locations[].parent_location_id` Type: string | null. Requirement: 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 ##### `data.locations[].path[]` Type: object\[\]. Requirement: required. Root-to-self path. FULL includes only verified parent relations and never invents missing hierarchy segments. ##### `data.locations[].path[].location_id` Type: string. Requirement: required. Path node numeric location id. - example: 20453 ##### `data.locations[].path[].name` Type: string. Requirement: required. Path node display name. - example: Andhra Pradesh ##### `data.locations[].path[].canonical_name` Type: string. Requirement: required when catalog=FULL. FULL only. Path node canonical name. - example: Andhra Pradesh,India ##### `data.locations[].path[].country_code` Type: string. Requirement: required when catalog=FULL. FULL only. Path node uppercase ISO 3166-1 alpha-2 country code. - example: IN ##### `data.locations[].path[].target_type` Type: string. Requirement: required when catalog=FULL. FULL only. Path node raw Google Geo Target type. - example: State ##### `data.locations[].path[].level` Type: string. Requirement: required when catalog is omitted or LEGACY. LEGACY only. Path node normalized AON location level. - example: REGION Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `data.locations[].path[].hierarchy_precision` Type: integer. Requirement: required when catalog=FULL. FULL only. One-based verified depth for this path node. - example: 2 - minimum: 1 ##### `data.locations[].path[].legacy_level` Type: string. Requirement: required when catalog=FULL and representable by LEGACY. FULL only. Optional compatible COUNTRY, REGION, or CITY label without relabeling the raw type. - example: REGION Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `data.locations[].hierarchy_precision` Type: integer. Requirement: required when catalog=FULL. FULL only. One-based verified hierarchy depth used for safe targeting evaluation. - example: 3 - minimum: 1 ##### `data.locations[].legacy_level` Type: string. Requirement: required when catalog=FULL and representable by LEGACY. FULL only. Optional compatible COUNTRY, REGION, or CITY label; FULL never returns level. - example: REGION Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `data.locations[].chain_status` Type: string. Requirement: required when catalog=FULL. FULL only. COMPLETE or UNRESOLVED\_SOURCE\_PARENT. - example: COMPLETE Allowed values: `COMPLETE`, `UNRESOLVED_SOURCE_PARENT` ##### `data.locations[].unresolved_source_parent_location_id` Type: string. Requirement: 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 ##### `data.locations[].external_codes` Type: object. Requirement: optional. LEGACY only. Optional lookup aliases for supported external location code systems. Matching still uses AON location\_id values. - example: { "iso\_3166\_2": "US-CA", "cldr\_subdivision": "USCA", "provider\_short": "CA" } ##### `data.locations[].external_codes.iso_3166_2` Type: string. Requirement: optional. ISO 3166-2 subdivision code mapped to this location when available. - example: US-CA - pattern: ^\[A-Z\]{2}-\[A-Z0-9\]{1,3}$ ##### `data.locations[].external_codes.cldr_subdivision` Type: string. Requirement: optional. Unicode CLDR subdivision id mapped to this location when available. - example: USCA - pattern: ^\[A-Z\]{2}\[A-Z0-9\]{1,3}$ ##### `data.locations[].external_codes.provider_short` Type: string. Requirement: optional. Country-scoped provider short subdivision code when available. - example: CA ##### `data.next_cursor` Type: string. Requirement: required when catalog=FULL and another page exists. FULL only. Opaque continuation cursor; absent on the final page. - example: opaque-continuation-cursor ##### `extra` Type: object. Requirement: 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": {} } ``` #### Errors #### 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/resolve **GET** `/v1/locations/resolve` Resolve legacy signals or a full-catalog id Authentication: Public. Source: Public operation. #### Request Query Parameters Catalog selector plus a LEGACY external signal or a FULL direct location\_id. ##### `location_id` Type: string. Requirement: 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: 9304101 - pattern: ^\[0-9\]+$ ##### `catalog` Type: string. Requirement: optional. Catalog representation. Omit it or use LEGACY to normalize external location signals; use FULL for a direct active location\_id lookup. - example: FULL - default: LEGACY Allowed values: `LEGACY`, `FULL` ##### `country` Type: string. Requirement: 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: US - pattern: ^\[A-Z\]{2}$ ##### `subdivision_code` Type: string. Requirement: 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_type` Type: string. Requirement: 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\_2 - default: AUTO Allowed values: `AUTO`, `ISO_3166_2`, `CLDR`, `PROVIDER_SHORT` ##### `city` Type: string. Requirement: 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 ##### `limit` Type: integer. Requirement: 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: 10 - minimum: 1 - maximum: 50 Request Examples ##### Resolve a full-catalog postal code ```bash curl -G https://api.aon.pro/v1/locations/resolve \ --data-urlencode "catalog=FULL" \ --data-urlencode "location_id=9304101" ``` #### Response Returns the resolved location, candidate locations, and the self-to-root location\_ids chain for the selected catalog. ##### `code` Type: string. Requirement: required. Platform status code for the request. - example: SUCCESS Allowed values: `SUCCESS` ##### `message` Type: string. Requirement: required. Human-readable status message. Empty string on normal success. ##### `data` Type: object. Requirement: required. Resolved location and self-to-root registry ancestry for the selected catalog. ##### `data.catalog` Type: string. Requirement: required when catalog=FULL. FULL only. Always FULL; absent from the LEGACY response shape. - example: FULL Allowed values: `FULL` ##### `data.catalog_version` Type: string. Requirement: required when catalog=FULL. FULL only. Full catalog version; absent from the LEGACY response shape. - example: v1 ##### `data.registry_version` Type: string. Requirement: required when catalog is omitted or LEGACY. LEGACY only. AON Location Registry version; absent from the FULL response shape. - example: v1 ##### `data.source_file_date` Type: string. Requirement: required. Pinned Google Geo Targets source file date for the selected catalog. - example: 2026-05-28 - format: date ##### `data.location` Type: object. Requirement: 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. ##### `data.location.location_id` Type: string. Requirement: required. Numeric-string location id aligned to Google Geo Target Criteria ID. - example: 9304101 - pattern: ^\[0-9\]+$ ##### `data.location.name` Type: string. Requirement: required. Short display name. - example: 522410 ##### `data.location.canonical_name` Type: string. Requirement: required. Provider canonical location name. - example: 522410,Andhra Pradesh,India ##### `data.location.country_code` Type: string. Requirement: required. Uppercase ISO 3166-1 alpha-2 country code. - example: IN - pattern: ^\[A-Z\]{2}$ ##### `data.location.target_type` Type: string. Requirement: required. Exact raw Google Geo Target type. FULL never normalizes this field to COUNTRY, REGION, or CITY. - example: Postal Code ##### `data.location.level` Type: string. Requirement: required when catalog is omitted or LEGACY and data.location is present. LEGACY only. AON-normalized supported location level; FULL never returns level. - example: REGION Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `data.location.source_parent_location_id` Type: string | null. Requirement: required when catalog=FULL. FULL only. Raw Parent ID from the source CSV. - example: 20453 ##### `data.location.parent_location_id` Type: string | null. Requirement: required. LEGACY uses the immediate registry parent; FULL uses only a verified ACTIVE source-parent edge. - example: 20453 ##### `data.location.hierarchy_precision` Type: integer. Requirement: required when catalog=FULL. FULL only. One-based verified hierarchy depth used for safe targeting evaluation. - example: 3 - minimum: 1 ##### `data.location.legacy_level` Type: string. Requirement: required when catalog=FULL and representable by LEGACY. FULL only. Optional compatible COUNTRY, REGION, or CITY label; FULL never returns level. - example: REGION Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `data.location.chain_status` Type: string. Requirement: required when catalog=FULL. FULL only. COMPLETE or UNRESOLVED\_SOURCE\_PARENT. - example: COMPLETE Allowed values: `COMPLETE`, `UNRESOLVED_SOURCE_PARENT` ##### `data.location.unresolved_source_parent_location_id` Type: string. Requirement: required when catalog=FULL and chain\_status=UNRESOLVED\_SOURCE\_PARENT. FULL only. Raw source parent id that could not be resolved. - example: 2364 ##### `data.location.path[]` Type: object\[\]. Requirement: required. Root-to-self path. FULL includes only verified parent relations and never invents missing hierarchy segments. ##### `data.location.external_codes` Type: object. Requirement: optional. LEGACY only. Lookup aliases mapped to this location when available. - example: { "iso\_3166\_2": "US-CA", "cldr\_subdivision": "USCA", "provider\_short": "CA" } ##### `data.location.external_codes.iso_3166_2` Type: string. Requirement: optional. ISO 3166-2 subdivision code mapped to this location when available. - example: US-CA - pattern: ^\[A-Z\]{2}-\[A-Z0-9\]{1,3}$ ##### `data.location.external_codes.cldr_subdivision` Type: string. Requirement: optional. Unicode CLDR subdivision id mapped to this location when available. - example: USCA - pattern: ^\[A-Z\]{2}\[A-Z0-9\]{1,3}$ ##### `data.location.external_codes.provider_short` Type: string. Requirement: optional. Country-scoped provider short subdivision code when available. - example: CA ##### `data.path[]` Type: object\[\]. Requirement: required. Same root-to-self path as data.location.path. ##### `data.location_ids[]` Type: string\[\]. Requirement: 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: 21137 - pattern: ^\[0-9\]+$ ##### `data.candidates[]` Type: object\[\]. Requirement: required. LEGACY candidate locations after applying normalized constraints. FULL returns an empty array after direct active-id resolution. ##### `extra` Type: object. Requirement: 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": {} } ``` #### Errors #### 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; current Query v1.0 does not accept it as viewer context. - External codes are LEGACY lookup aliases only and are not Offer or Query matching keys. ### GET /v1/locations/{location\_id} **GET** `/v1/locations/{location_id}` Look up one legacy or full-catalog location Authentication: Public. Source: Public operation. #### Request Path Parameters Legacy Registry v1 id or active FULL catalog id to resolve. ##### `location_id` Type: string. Requirement: required. Numeric-string location id. LEGACY accepts Registry v1 ids; FULL accepts any ACTIVE full-catalog Google Criteria ID. - example: 9304101 - pattern: ^\[0-9\]+$ Query Parameters Catalog selector for the exact-id lookup. ##### `catalog` Type: string. Requirement: optional. Catalog representation. Omit it or use LEGACY for Registry v1; use FULL for any ACTIVE full-catalog location id. - example: FULL - default: LEGACY Allowed values: `LEGACY`, `FULL` Request Examples ##### Look up a full-catalog postal code ```bash curl -G https://api.aon.pro/v1/locations/9304101 \ --data-urlencode "catalog=FULL" ``` #### Response Returns one location object and the self-to-root location\_ids chain for the selected catalog. ##### `code` Type: string. Requirement: required. Platform status code for the request. - example: SUCCESS Allowed values: `SUCCESS` ##### `message` Type: string. Requirement: required. Human-readable status message. Empty string on normal success. ##### `data` Type: object. Requirement: required. Exact location lookup result and self-to-root registry ancestry for the selected catalog. ##### `data.catalog` Type: string. Requirement: required when catalog=FULL. FULL only. Always FULL; absent from the LEGACY response shape. - example: FULL Allowed values: `FULL` ##### `data.catalog_version` Type: string. Requirement: required when catalog=FULL. FULL only. Full catalog version; absent from the LEGACY response shape. - example: v1 ##### `data.registry_version` Type: string. Requirement: required when catalog is omitted or LEGACY. LEGACY only. AON Location Registry version; absent from the FULL response shape. - example: v1 ##### `data.source_file_date` Type: string. Requirement: required. Pinned Google Geo Targets source file date for the selected catalog. - example: 2026-05-28 - format: date ##### `data.location` Type: object. Requirement: required. Single Location Search result object. ##### `data.location.location_id` Type: string. Requirement: required. Numeric-string location id aligned to Google Geo Target Criteria ID. - example: 9304101 - pattern: ^\[0-9\]+$ ##### `data.location.name` Type: string. Requirement: required. Short display name. - example: 522410 ##### `data.location.canonical_name` Type: string. Requirement: required. Provider canonical location name. - example: 522410,Andhra Pradesh,India ##### `data.location.country_code` Type: string. Requirement: required. Uppercase ISO 3166-1 alpha-2 country code. - example: IN - pattern: ^\[A-Z\]{2}$ ##### `data.location.target_type` Type: string. Requirement: required. Exact raw Google Geo Target type. FULL never normalizes this field to COUNTRY, REGION, or CITY. - example: Postal Code ##### `data.location.level` Type: string. Requirement: required when catalog is omitted or LEGACY. LEGACY only. AON-normalized supported location level; FULL never returns level. - example: CITY Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `data.location.source_parent_location_id` Type: string | null. Requirement: required when catalog=FULL. FULL only. Raw Parent ID from the source CSV. - example: 20453 ##### `data.location.parent_location_id` Type: string | null. Requirement: required. LEGACY uses the immediate registry parent; FULL uses only a verified ACTIVE source-parent edge. - example: 20453 ##### `data.location.hierarchy_precision` Type: integer. Requirement: required when catalog=FULL. FULL only. One-based verified hierarchy depth used for safe targeting evaluation. - example: 3 - minimum: 1 ##### `data.location.legacy_level` Type: string. Requirement: required when catalog=FULL and representable by LEGACY. FULL only. Optional compatible COUNTRY, REGION, or CITY label; FULL never returns level. - example: REGION Allowed values: `COUNTRY`, `REGION`, `CITY` ##### `data.location.chain_status` Type: string. Requirement: required when catalog=FULL. FULL only. COMPLETE or UNRESOLVED\_SOURCE\_PARENT. - example: COMPLETE Allowed values: `COMPLETE`, `UNRESOLVED_SOURCE_PARENT` ##### `data.location.unresolved_source_parent_location_id` Type: string. Requirement: required when catalog=FULL and chain\_status=UNRESOLVED\_SOURCE\_PARENT. FULL only. Raw source parent id that could not be resolved. - example: 2364 ##### `data.location.path[]` Type: object\[\]. Requirement: required. Root-to-self path. FULL includes only verified parent relations and never invents missing hierarchy segments. ##### `data.path[]` Type: object\[\]. Requirement: required. Same root-to-self path as data.location.path. ##### `data.location_ids[]` Type: string\[\]. Requirement: 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: 1014221 - pattern: ^\[0-9\]+$ ##### `extra` Type: object. Requirement: 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": {} } ``` #### Errors #### 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; current Query v1.0 does not accept it as viewer context. - 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; current Query v1.0 does not expose a viewer-location field. ## Related links [ Location Targeting Understand Offer-side geographic targeting and the public Query v1.0 boundary. ](https://docs.aon.pro/protocol/location-targeting)[ Offer Query Review the current Query v1.0 request: optional context is bounded and excludes viewer-location inputs. ](https://docs.aon.pro/api/offer-query)[ Errors & Rate Limits Shared HTTP status, body envelope, and retry guidance. ](https://docs.aon.pro/api/errors-rate-limits)