---
title: "Search for an address."
method: POST
path: "/address/search/v1"
tags: ["Address Validation"]
---

# Search for an address.

`POST /address/search/v1`

## Headers

- `Reference-Id` string
- `Timeout-Seconds` integer
- `Transliterate` boolean
- `Add-Retention` boolean

## Request body

- AddressSearchV1Request — The address search v1 request.
  - `country_iso` string, required — The country ISO3 code of address.
  - `datasets` string[], nullable, required — The datasets for address validation.
  - `max_suggestions` integer, nullable — The maximum number of suggestions a search request should return. Please refer to the <a target="_blank" href="https://docs.experianaperture.io/address-validation/experian-address-validation/api-reference/api-specification/">documentation</a>.
  - `components` AddressInputComponents, required — The address search input component.
    - `unspecified` string[], nullable — The input component collection.
    - `names` AddressInputComponentName[], nullable — The names component.
      - `forename` string, nullable — The first name.
      - `middlename` string, nullable — Middle initial.
      - `surname` string, nullable — The surname.
    - `locality` AddressLocalityConstrains — A class representing search locality constraints
      - `region` AddressRestrictionRules — A class that represents address restriction rules
        - `exists` boolean, nullable — Gets or sets a value indicating whether the address element is required to exist for returned addresses or required to not exist. Null value means that both records with and without such element will be returned.
        - `must_be` string[], nullable — Gets or sets an array of values, causing the returned result to include only records that have one of the values
        - `must_not_be` string[], nullable — Gets or sets an array of values, causing the returned result to include only records that exclude the values
  - `location` string, nullable — Geographical location (latitude,longitude) to use as the center point for the search (USA only).
  - `options` AddressNameValuePair[], nullable — Additional options.
    - `name` string, nullable — The name of the pair.
    - `value` string, nullable — The value of the pair.
  - `preferred_language` string[], nullable — The datasets for address validation.
  - `preferred_script` string[], nullable — The datasets for address validation.
  - `street` string, nullable — The country ISO3 code of address.
  - `town` string, nullable — The country ISO3 code of address.
  - `region` string, nullable — The country ISO3 code of address.
  - `postal_code` string, nullable — The country ISO3 code of address.

## Response `200`

OK

- AddressSearchV1Response — Response model for AddressSearchV1 endpoint.
  - `error` ResponseError — Error model containing the error details.
    - `type` string, nullable — A link to documentation that provides more details about the error you’ve encountered.
    - `title` string, nullable — The title of the error.
    - `detail` string, nullable — A description of the error.
    - `instance` string, nullable — The endpoint that returned the error.
  - `result` AddressSearchV1Result — Address search V1 result.
    - `more_results_available` boolean — To indicate that there are more suggestions available than the results provided.
    - `confidence` string, nullable — The outcome (confidence level) of the validation.
    - `suggestions_key` string, nullable — The suggestions key for address suggestion refinement.
    - `suggestions_prompt` string, nullable — The prompt to display to the user, indicating what information they should enter next.
    - `suggestions` AddressSuggestion[], nullable — The collection of the suggestions that match the address search input.
      - `global_address_key` string, nullable — The ID of the address received as part of a validation.
      - `text` string, nullable — The suggestion that should be presented to the user as a possible match to their input.
      - `matched` array[], nullable — A collection of the characters in the suggestion that have been matched. Integrators can use this information to highlight matched text.
        - integer[]
      - `format` string, nullable — The format URL of the suggested address.
      - `stepin` string, nullable — The stepin URL of the cluster of addresses.
      - `number_of_addresses` integer — The stepin URL of the cluster of addresses.
      - `dataset` string, nullable — The dataset of the suggestion.
      - `additional_attributes` AddressNameValuePair[], nullable — The additional attributes of the suggestion.
        - `name` string, nullable — The name of the pair.
        - `value` string, nullable — The value of the pair.
      - `names` string[], nullable — The additional attributes of the suggestion.
      - `uprn` string, nullable — The UPRN of the suggestion.

## 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)