---
title: "Lookup an address based on a key."
method: POST
path: "/address/lookup/v2"
tags: ["Address Validation"]
---

# Lookup an address based on a key.

`POST /address/lookup/v2`

## Headers

- `Reference-Id` string
- `Timeout-Seconds` integer
- `Add-Addresses` string
- `Add-FinalAddress` boolean

## Request body

- AddressLookupV2Request — The address lookup v2 request.
  - `country_iso` string, required — Gets or sets the country ISO3 code of address.
  - `datasets` string[], nullable, required — Gets or sets the datasets for address validation.
  - `max_addresses` integer, nullable — Gets or sets the maximum number of addresses a search request should return.
  - `max_suggestions` integer, nullable — Gets or sets the maximum number of suggestions a search request should return.
  - `attributes` AddressLookupV2RequestAttributes — AddressLookupV2RequestAttributes for locality search.
    - `locality_lookup` string[], nullable — AddressLookupV2RequestAttributes for locality lookup.
    - `postal_code_lookup` string[], nullable — AddressLookupV2RequestAttributes for postal code lookup.
  - `key` Key — The key of the postal code.
    - `type` string, nullable — Gets or sets the key type
    - `value` string, nullable — Gets or sets the key value
  - `preferred_language` string[], nullable — Gets or sets the preferred language.
  - `preferred_script` string[], nullable — Gets or sets the the preferred script.
  - `names` AddressInputComponentName[], nullable — The names component.
    - `forename` string, nullable — The first name.
    - `middlename` string, nullable — Middle initial.
    - `surname` string, nullable — The surname.
  - `layouts` string[], nullable — Custom layout name.

## Response `200`

OK

- AddressLookupV2Result — Address lookup V2 result.
  - `more_results_available` boolean — Gets or sets a value indicating whether property that there are more suggestions available than the results provided.
  - `confidence` string, nullable — Gets or sets the outcome (confidence level) of the validation.
  - `suggestions_key` string, nullable — Gets or sets the suggestions key for address suggestion refinement.
  - `suggestions_prompt` string, nullable — Gets or sets the prompt to display to the user, indicating what information they should enter next.
  - `suggestions` Suggestion[], nullable — Gets or sets the possible postcode, locality or UDPRN (for GBR)
    - `locality` LocalityComponents — The locality of the suggestion.
      - `region` LocalityItem — Initializes a new instance of the Experian.Hub.Feature.AddressValidate.GfoClients.GfoRest.Models.GfoRestSearchV2ResponseModel.LocalityItem class.
        - `name` string, nullable — Gets or sets the locality name
        - `code` string, nullable — Gets or sets the locality code
        - `description` string, nullable — Gets or sets the locality description
      - `sub_region` LocalityItem — Initializes a new instance of the Experian.Hub.Feature.AddressValidate.GfoClients.GfoRest.Models.GfoRestSearchV2ResponseModel.LocalityItem class.
        - `name` string, nullable — Gets or sets the locality name
        - `code` string, nullable — Gets or sets the locality code
        - `description` string, nullable — Gets or sets the locality description
      - `town` LocalityItem — Initializes a new instance of the Experian.Hub.Feature.AddressValidate.GfoClients.GfoRest.Models.GfoRestSearchV2ResponseModel.LocalityItem class.
        - `name` string, nullable — Gets or sets the locality name
        - `code` string, nullable — Gets or sets the locality code
        - `description` string, nullable — Gets or sets the locality description
      - `district` LocalityItem — Initializes a new instance of the Experian.Hub.Feature.AddressValidate.GfoClients.GfoRest.Models.GfoRestSearchV2ResponseModel.LocalityItem class.
        - `name` string, nullable — Gets or sets the locality name
        - `code` string, nullable — Gets or sets the locality code
        - `description` string, nullable — Gets or sets the locality description
      - `sub_district` LocalityItem — Initializes a new instance of the Experian.Hub.Feature.AddressValidate.GfoClients.GfoRest.Models.GfoRestSearchV2ResponseModel.LocalityItem class.
        - `name` string, nullable — Gets or sets the locality name
        - `code` string, nullable — Gets or sets the locality code
        - `description` string, nullable — Gets or sets the locality description
      - `type` string, nullable — Addresses type. Specific for Japan.
    - `postal_code` PostalCode — The postal code of the suggestion.
      - `full_name` string, nullable — Gets or sets the full postal code
      - `primary` string, nullable — Gets or sets the postal code primary
      - `secondary` string, nullable — Gets or sets the postal code secondary
    - `postal_code_key` string, nullable — Gets or sets the suggestion postal code key (to do postal code enrichment requests)
    - `locality_key` string, nullable — Gets or sets the suggestion locality key (to do centroid enrichment requests)
    - `what3words` What3WordsComponent — What3Words address suggestion.
      - `name` string, nullable — Gets or sets the name;
      - `description` string, nullable — Gets or sets the description
  - `addresses` AddressSuggestionV2Hub[], nullable — Gets or sets the collection of suggested addresses
    - `text` string, nullable — Gets or sets the suggestion text
    - `matched` array[], nullable — Gets or sets the matched field
      - integer[]
    - `global_address_key` string, nullable — Gets or sets the global address key
    - `format` string, nullable — Gets or sets the format field
    - `dataset` string, nullable — Gets or sets the suggestion dataset
    - `names` string[], nullable — The additional attributes of the suggestion.
    - `uprn` string, nullable — The UPRN of the suggestion.
  - `addresses_formatted` AddressLookupV2ResultAddressFormatted[], nullable — Gets or sets the collection of formatted addresses
    - `layout_name` string, nullable — The address layout name.
    - `address` object, nullable — The customized address layouts in default format.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `406` — Not Acceptable
- `408` — Request Timeout
- `415` — Unsupported Media Type
- `429` — Too Many Requests
- `500` — Internal Server Error
- `503` — Service Unavailable

---

[API](https://skmtc.dev/experianaperture/apis/aperture-rest-api.md) · [All operations](https://skmtc.dev/experianaperture/apis/aperture-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/experianaperture/aperture-rest-api/revisions/f17d329b4892/schema)