The /validate endpoint is used in the Validate search type.

Headers

Name Type Description
Auth-Token string Input your unique token here. This is required to submit an API request.
x-app-key
(Optional)
string Alternative authentication header. Auth-Token takes precedence.
Reference-Id
(Optional)
string Identifier that will be returned to the response to help you track the request.
Timeout-Seconds
(Optional)
integer Maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned.

The default value of this setting is 15.
Add-Components
(Optional)
boolean Specifies if the response should contain the address broken down into its components.

The default value of this setting is false.
Add-Metadata
(Optional)
boolean Specify whether the response should return all fields and values, in addition to the main core information.

The default value of this setting is false.

Body

In the request body you can specify:

Name Type Description
country_iso string The ISO3 code of the country you want to search against.
datasets collection The collection of datasets you want to search against.
components collection Collection of input components.
unspecified collection Collection of unspecified text inputs.
options
(Optional)
collection Additional options. See options for more detailed information.
max_suggestions
(Optional)
string The maximum number of suggestions you want to get returned.
Acceptable values: 1-100

The default value of this setting is 7.
layouts
(Optional)
collection Collection of layout names.

The default value of this setting is default which will return a predefined 7 line layout.
layout_format
(Optional)
string The format of the customized address layout. The available values are:
  • default: Address line label and content is presented as key value pairs.
  • address_lines: Address format to ease migration from other address validation services. The separate address lines follow the same structure as in Address Validate SOAP and Pro Web.
The default value of this setting is default.

Options

Name Type Description
prompt_set
(Optional)
string An address can be submitted as one or as many fields; the prompt_set property defines which address elements can be entered in each field, for example a field might be constrained so that it only accepts postcodes. The prompt set definition depends on the search type used.
You can view the definitions by using the Prompt sets API request. The available values are:
  • OneLine - All search text to be submitted upon a single line.
  • Default - The default prompt set for the engine.
  • Generic - A general data-independent prompt set.
  • Optimal - Requires the minimum possible amount of search text to perform a search.
  • Alternate - An extended country-specific set for where the information required for an optimal search is not available.
  • Alternate2 - A different alternative prompt set (USA only).
The default value of this setting is Default.
flatten
(Optional)
string Defines whether the search results will be 'flattened' to a single list of deliverable results, or output a list of suggestions that can be stepped into.
  • True - The list of suggestions will contain an item per address.
  • False - The list of suggestions might contain items that cover more than one address, for example as range of building numbers that need to be refined further to retrieve a final address.
The default value of this setting is True.
intensity
(Optional)
string Defines how hard the search engine will work to obtain a match. Higher intensity values may yield more results than lower intensity values, but will also result in longer search times. The available values are:
  • Exact - This does not allow many mistakes in the search term, but is the fastest.
  • Close - This allows some mistakes in the search term, and is the default setting.
  • Extensive - This allows many mistakes in the search term, and will take the longest.
The default value of this setting is Close.

Headers

Name Type Description
Reference-Id
(Optional)
String Identifier that was supplied by you in the request header to help you track the request.

Body

The response from the API returns the below fields within a result object. Should an error occur, an error object is returned instead.

Name Type Description
more_results_available boolean To indicate that there are more suggestions available than returned in this request.
confidence string The confidence level of the search result.
  • Verified match: The input was matched to a single deliverable address in our data. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Multiple matches: The input was matched to more than one deliverable address in our data. This can happen when the provided address doesn't contain enough information to return just one match. As a result, the returned addresses may or may not be deliverable addresses. Therefore, a list of suggestions containing all the matches will be returned and the user has to select the required address.
  • Too many matches: The input was too broad and matched too many addresses in our data. The user should be further prompted to provide additional information.
  • Interaction required: The input was matched to a single deliverable address in our data. However, user interaction is recommended as the confidence in the validity of this address is not high enough for it to be classed as a *Verified match*.
  • Premises partial: The input was partially matched to a deliverable address in our data. For example, a search on "Flat A, 63 Southerton Road, London" could be matched to "63 Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Street partial: The input was partially matched to a deliverable address in our data. For example, a search on "63 Southerton Road, London" could be matched to "Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Verified place: The input was matched to a single deliverable address in our data but the street information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Verified street: The input was matched to a single deliverable address in our data but the building information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Incomplete address: The input was matched to an address in our data, but is not deliverable. This is commonly returned when searching within data that does not contain building level information. If the user selects a suggestion with this attribute set, then they should be further prompted to provide additional building level information so that the address is deliverable.
  • Insufficient search terms: The input did not contain enough characters to provide a meaningful result.
  • No matches: The input could not be matched to any deliverable results in our data. Therefore, address validation is not possible and the address provided by the user should be used.
suggestions_key string The suggestions key for address suggestion refinement.
suggestions_prompt string The prompt to display to the user, indicating what information they should enter next.
suggestions collection The collection of the suggestions that match the address search input.
global_address_key string The ID of the address matched as part of a validation.
text string The suggestion that should be presented to the user as a possible match to their input.
matched collection A collection of the characters in the suggestion that have been matched. Integrators can use this information to highlight matched text.
format string The format URL of the suggested address.
dataset string The dataset of the suggestion.
additional_attributes collection The additional attributes of the suggestion.

Headers

Name Type Description
Reference-Id
(Optional)
String Identifier that was supplied by you in the request header to help you track the request.

Body

The response from the API returns the below fields within a result object. Should an error occur, an error object is returned instead.

Name Type Description
validation_detail object Address validation details.
  • building_firm_name_corrected: Building or Firm name has been added or changed.
  • primary_number_corrected: Primary Number has been added or changed.
  • street_corrected: Street has been (non-trivially) corrected.
  • rural_route_highway_contract_matched: Rural Route or Highway Contract has been matched.
  • city_name_corrected: City name has been added or changed.
  • city_name_alias_matched: City name has been alias matched.
  • state_corrected: State or Province has been added or changed.
  • zip_code_corrected: Postal code has been added or corrected.
  • secondary_num_retained: Secondary number has been retained.
  • iden_pre_st_info_retained: Identifiable pre-street information has been retained.
  • gen_pre_st_info_retained: General pre-street information has been retained.
  • post_st_info_retained: Post-street information has been retained.
confidence string The confidence level of the validation result.
  • Verified match: The input was matched to a single deliverable address in our data. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Multiple matches: The input was matched to more than one deliverable address in our data. This can happen when the provided address doesn't contain enough information to return just one match. As a result, the returned addresses may or may not be deliverable addresses. Therefore, a list of suggestions containing all the matches will be returned and the user has to select the required address.
  • Too many matches: The input was too broad and matched too many addresses in our data. The user should be further prompted to provide additional information.
  • Interaction required: The input was matched to a single deliverable address in our data. However, user interaction is recommended as the confidence in the validity of this address is not high enough for it to be classed as a *Verified match*.
  • Premises partial: The input was partially matched to a deliverable address in our data. For example, a search on "Flat A, 63 Southerton Road, London" could be matched to "63 Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Street partial: The input was partially matched to a deliverable address in our data. For example, a search on "63 Southerton Road, London" could be matched to "Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Verified place: The input was matched to a single deliverable address in our data but the street information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Verified street: The input was matched to a single deliverable address in our data but the building information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Incomplete address: The input was matched to an address in our data, but is not deliverable. This is commonly returned when searching within data that does not contain building level information. If the user selects a suggestion with this attribute set, then they should be further prompted to provide additional building level information so that the address is deliverable.
  • Insufficient search terms: The input did not contain enough characters to provide a meaningful result.
  • No matches: The input could not be matched to any deliverable results in our data. Therefore, address validation is not possible and the address provided by the user should be used.
address object The Address object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country.
addresses_formatted collection Customized address layouts.
components object The Components object consists of all available address components. Each individual component can be added to relevant fields in your database. Components that do not contain any values for the selected address will not be returned by the API.
This object is only returned when the Add-Components header is set to True on the request.

Address object

The Address object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. Country specific information for our most popular countries is shown below:

Address lines United Kingdom United States Canada Australia New Zealand France Rest of the World
address_line_1 Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line
address_line_2 Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line
address_line_3 Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line
locality Town City Name Municipality Locality Suburb
Lobby Name
Rural Delivery
Town Locality
region State Code Province Code State Code City Province
postal_code Postcode ZIP+4 Postal Code Postcode Postal Code Postcode Postal Code
country Country Country Country Country Country Country Country

Addresses_formatted collection

The addresses_formatted collection is only returned if a custom layout has been supplied.

Name Type Description
addresses_formatted collection Collection of formatted addresses.
layout_name string Name of the layout.
address object This object is returned if layout_format is set to default or omitted from the request.
address_lines collection This object is returned if layout_format is set to address_lines.
not_enough_lines boolean There are not enough address lines configured to display the whole address.
This object can only be returned if layout_format is set to address_lines.
has_truncated_lines boolean Truncation has occurred on one or more address lines.
This object can only be returned if layout_format is set to address_lines.
has_missing_sub_premises boolean The missing subpremise attribute specifies if the address is missing a subpremise when using the validate search type. It can be ignored when using all other engines.
This object can only be returned if layout_format is set to address_lines.

Components object

The Components object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. The full list of components with details for our most popular countries plus a rest of world column for all other supported countries can be found below.

Name United Kingdom United States Canada Australia New Zealand France Rest of the world
language Language Language Language Language Language Language Language
country_name Country name Country name Country name Country name Country Country Country name
country_iso_3 ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code ISO 3166-1 alpha-3 country code
country_iso_2 ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code* ISO 3166-2 code*

/* ISO 3166-2 standard consists of two parts: the first part is the ISO 3166-1 alpha-2 country code, the second part (when present) is a string of up to three alphanumeric characters indicating country subdivision.

Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Postcode Zip code Postal code Postal code Postcode Postcode Postcode
primary ZIP Postal code Postcode Postcode
secondary Plus4
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Delivery service Delivery service Delivery service All postal delivery types All postal delivery types All PO Box types
service_type Delivery Service type Delivery Service type Delivery Service type
service_number Delivery Service value Delivery Service value Delivery Service value
post_centre_name
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Delivery Service Delivery Service
service_type Delivery Service type Delivery Service type
service_number Delivery Service value Delivery Service value
post_centre_name
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
name Building name / Flat / Unit name (GNAF) AFNOR line 3
entrance
full_name Subbuilding number
type
value
floor
full_name Building Level
type Building Level type
value Building Level number
door
full_name Extension designation Secondary number Suite name / number Flat / Unit name Unit textual + Unit AlphaNum Secondary address unit
type Extension designation type Secondary address identifier Suite Name Flat / Unit type
value Extension designation value Secondary address number Suite number Flat / Unit number
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
building_name Building name Building name Building name Additional geographic data Building name
secondary_name Group building name (Ireland only)
building_number Street number Primary number Street number + Suffix Building number Street number Number and Number extension Address/ house number
secondary_number Secondary number and Secondary number extension
allotment_number Allotment number
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
department_name Department Department Department
secondary
_department_name
company_name Organization name Company name
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Primary thoroughfare name & type Full street name Full street name Street Street Street Full street name
prefix Street prefix Street prefix
name Primary thoroughfare name Street name Street name Street name Primary street name
type Primary thoroughfare type Street type Street type Street type Street type Primary street type
suffix Street suffix Street suffix Street type suffix
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Secondary Thoroughfare Name & Type
prefix
name Secondary thoroughfare name
type Secondary thoroughfare type
suffix
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Route service type / number
service_type
service_number
delivery_name
qualifier
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
region
name D├ępartement Region
code State Code Province Code INSEE code
description
sub_region
name County
name
Subregion
code
description
town
name Town City name Municipality Locality Suburb Town / CEDEX office Town
code
description
district
name Dependent locality Delivery area installation Lobby name Geographic town Settlement
code
description
sub_district
name Double-dependent locality PNR
Lobby
name
Postal locality / Geographic town
code
description
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
town
name town/city
code
description
district
name suburb
code
description

Metadata

The Metadata object contains additional information about the returned address, such as deliverability indicators. The metadata can be stored in your database or used to decide if the address should be rejected.
Metadata is only supported for certain countries (see table below). For all other countries, an empty metadata object will be returned.

The following metadata elements are currently available:

Name Country Description
address_info
sources Australia Indicates the source of address information:
  • PAF: Australia Post's Postal Address File
  • GNAF: Geoscape Australia's Geocoded National Address File
If the address appears in both sources, both PAF and GNAF indicators will be returned.
number_of_households United Kingdom Number of households present at the address for Royal Mail's Multiple Residence and Not Yet Built addresses.
just_built_date United Kingdom Construction date of a property, if activated within the past six months.
identifier
udprn United Kingdom Royal Mail's Unique Delivery Point Reference Number, an eight-digit code assigned to every delivery point in the Postcode Address File (PAF).
umrrn United Kingdom Royal Mail's Unique Multiple Residence Reference Number, an eight-digit code linked to UDPRNs in Royal Mail's Multiple Residence dataset.
dpid Australia
New Zealand
Delivery Point Identifier that uniquely identifies an address:
  • Australia Post's Delivery Point Identifier, an eight-digit number that uniquely identifies a physical location to which Australia Post delivers mail.
  • New Zealand Post's Delivery Point Identifier, a unique reference number of up to seven digits which is assigned to each delivery point address in the postal address file.
gnafPid Australia Geoscape Australia's Geocoded National Address File Persistent Identifier (G-NAF ID).
hin Australia Household Identification Number (HIN), unique reference ID for each household.
paf_address_key United Kingdom Royal Mail's PAF Address Key.
route_classification
id New Zealand New Zealand Post's unique numeric identifier for a street, for example 1324.
carrier_route United States Code assigned by the USPS to a group of addresses to aid mail delivery within a ZIP code. Consists of a carrier route type and carrier route code (length: 4 bytes). For example, C001.
barcode
sort_plan_number Australia Three-digit Barcode Sort Plan (BSP) number for each full address to facilitate pre-sorting of mail items.
delivery_point_barcode Australia
United States
  • Australia: Customer barcode is a 37-digit string generated from the DPID.
  • USA: Delivery point barcode (DPBC) consists of ZIP+4 followed by the last two digits of the house/box number, or if the match is made to a highrise record, the secondary unit number representing the delivery point information.
address_classification
delivery_type Australia
United Kingdom
United States
The type of mail delivery at the address:
  • business
  • residential
  • mixed
address_type
code Australia
New Zealand
United States
Record type code indicating the type of address.
description Australia
New Zealand
United States
Description of the address type code.
is_deliverable New Zealand Indicates whether the address can receive mail.
dpv
cmra_indicator United States Indicates whether selected address is a Commercial Mail Receiving Agency.
  • Y: Address listed in the table of CMRA addresses.
  • N: Address not listed in the table of CMRA addresses.
  • Blank: Address not presented to hash table.
seed_indicator United States Indicates whether selected address is a seed address. Seed records are control records placed by the USPS to prevent unauthorized tampering (e.g., creation of lists containing every single delivery point in a geographical region).
  • Y: Address matched to a seed record.
  • N: Address did not match to a seed record.
  • Blank: Address not presented to hash table.
dpv_indicator United States Indicates whether selected address is confirmed as deliverable via Delivery Point Validation process.
  • Y: Address DPV confirmed for both primary and (if present) secondary numbers.
  • D: Address DPV confirmed for the primary number only, and secondary number information was missing.
  • S: Address DPV confirmed for the primary number only, and secondary number information was present but unconfirmed.
  • N: Both Primary and (if present) Secondary number information failed to DPV Confirm.
footnotes United States Array containing zero or more of the following elements:
  • AA: Input Address Matched to the ZIP+4 file.
  • A1: Input Address Not Matched to the ZIP+4 file.
  • BB: Input Address Matched to DPV (all components).
  • CC: Input Address Primary Number Matched to DPV but Secondary Number not Matched (present but invalid).
  • N1: Input Address Primary Number Matched to DPV but Address Missing Secondary Number.
  • M1: Input Address Primary Number Missing.
  • M3: Input Address Primary Number Invalid.
  • P1: Input Address RR or HC Box number Missing.
  • P3: Input Address PO, RR, or HC Box number Invalid.
  • RR: Input Address Matched to CMRA and PMB designator present (PMB 123 or #123).
  • R1: Input Address Matched to CMRA but PMB designator not present (PMB 123 or #123).
  • F1: Input Address Matched to a Military Address.
  • G1: Input Address Matched to a General Delivery Address.
  • U1: Input Address Matched to a Unique ZIP Code.
vacancy_indicator United States Indicates whether selected address is known to be vacant and not receiving mail deliveries:
  • Y: Address listed in the table of vacant addresses.
  • N: Address not listed in the table of vacant addresses.
  • Blank: Address not presented to hash table.
no_stats_indicator United States Indicates whether selected address is not receiving mail deliveries. These addresses are not receiving delivery because a) delivery has not been established; b) customer receives mail as a part of a drop; or c) the address is no longer a possible delivery because the carrier destroys or returns all of the mail. Addresses for delivery points in gated communities may also be identified as No-Stats.
  • Y: Address listed in the table of no-stats addresses.
  • N: Address not listed in the table of no-stats addresses.
  • Blank: Address not presented to hash table.
pbsa_indicator United States Indicates whether selected address is a Post Office Box Street Address, a USPS alternative to traditional PO BOX addresses for customers who require a formal street address for delivery (as opposed to a PO BOX number).
  • Y: Address listed in the table of PBSA addresses
  • N: Address not listed in the table of PBSA addresses
  • Blank: Address not presented to hash table.

The following response codes can be returned by the API:

Status Code Reason phrase Description
200 Success Request processed successfully.
400 Bad Request Request failed due to malformed syntax.
401 Unauthorized Auth-Token provided is incorrect.
403 Forbidden Request is not authorized to use this service.
406 Not Acceptable Request is not in an acceptable format.
408 Request Timeout Response was not returned within the timeout allowance.
415 Unsupported Media Type Request is not using a Media type that is recognized by the server.
429 Too many requests Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details.
500 Internal Server Error The server has encountered an error.
503 Service Unavailable Service unavailable. Check service status for up-to-date information.

Australia

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "main ave",
      "lidcombe",
      "2141"
    ]
  },
  "datasets": [ "au-address-gnaf" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Street partial",
    "suggestions_key": "QVVHfjcuNzMwYVNBVUdIQUxtQndBQUFBQUVBVzFoYVc0Z1lYWmxMR3hwWkdOdmJXSmxMREl4TkRFQUtnTUFBQS0tfjIyfjc",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "2xrWTI5dFltVXNNakUwTVFBQUFBQUF-MjJ-Nw",
        "text": "1 Main Avenue, LIDCOMBE  NSW  2141",
        "format": "https://api.experianaperture.io/address/format/v1/2xrWTI5dFltVXNNakUwTVFBQUFBQUF-MjJ-Nw",
        "additional_attributes": [
          { "name": "picklist_display", "value": "1 Main Avenue, LIDCOMBE  NSW" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "2141" },
          { "name": "full_address", "value": "true" }
        ]
      },
      {
        "global_address_key": "BUC4uWkFBQUFBRC4uLi4uQUFBQUFBQUFBQUFBQUFBQUFBQUFiV0ZwYmlCaGRt",
        "text": "5 Main Avenue, LIDCOMBE  NSW  2141",
        "format": "https://api.experianaperture.io/address/format/v1/BUC4uWkFBQUFBRC4uLi4uQUFBQUFBQUFBQUFBQUFBQUFBQUFiV0ZwYmlCaGRt",
        "additional_attributes": [
          { "name": "picklist_display", "value": "5 Main Avenue, LIDCOMBE  NSW" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "2141" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "unit 1, 8 main ave, lidcombe"
    ]
  },
  "datasets": [ "au-address" ]
}

Response

{
  "result": {
    "confidence": "Interaction required",
    "address": {
      "address_line_1": "U 1  8 Main Ave",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "LIDCOMBE",
      "region": "NSW",
      "postal_code": "2141",
      "country": "AUSTRALIA"
    }
  }
}

Request

{
  "country_iso": "AUS",
  "components": {
    "unspecified": [
      "8 main ave",
      "lidcombe"
    ]
  },
  "datasets": [ "au-address" ],
  "layouts": [ "your layout name" ]
}

Response

{
  "result": {
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "Flat/Unit (Number)": "",
          "Building number": "8",
          "Street": "Main Ave",
          "Locality": "LIDCOMBE",
          "State code": "NSW",
          "Postcode": "2141"
        }
      }
    ]
  }
}

United Kingdom

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "160 blackfriars rd, london"
    ]
  },
  "datasets": [ "gb-address" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Premises partial",
    "suggestions_key": "R0JSfjcuNzMwNE1HQlJFZ0xtQndBQUFBQUVBUW9BQVFBQUFBR2RtR0NSQUNFZ0FnQUFBQUFBQUFBQUF",
    "suggestions_prompt": "Enter selection",
    "suggestions": [
      {
        "global_address_key": "R0JSfjcuNzMwN09HQlJFZ0xtQndBQUFBQUVBd0V",
        "text": "Axon Communications, 160 Blackfriars Road, LONDON SE1 8EZ",
        "format": "https://api.experianaperture.io/address/format/v1/R0JSfjcuNzMwN09HQlJFZ0xtQndBQUFBQUVBd0V",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Axon Communications, 160 Blackfriars Road, LONDON" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "SE1 8EZ" },
          { "name": "full_address", "value": "true" }
        ]
      },
      {
        "global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
        "text": "Experian, 160 Blackfriars Road, LONDON SE1 8EZ",
        "format": "https://api.experianaperture.io/address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps",
        "additional_attributes": [
          { "name": "picklist_display", "value": "Experian, 160 Blackfriars Road, LONDON" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "SE1 8EZ" },
          { "name": "full_address", "value": "true" }
        ]
      }
    ]
  }
}

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "Experian Data",
      "160 blackfriars rd",
      "london"
    ]
  },
  "datasets": [ "gb-address" ]
}

Response

{
  "result": {
    "confidence": "Interaction required",
    "address": {
      "address_line_1": "Experian Data Quality",
      "address_line_2": "160 Blackfriars Road",
      "address_line_3": "",
      "locality": "LONDON",
      "region": "",
      "postal_code": "SE1 8EZ",
      "country": "UNITED KINGDOM"
    }
  }
}

Request

{
  "country_iso": "GBR",
  "components": {
    "unspecified": [
      "Experian Data, 160 blackfriars rd"
      "london"
    ]
  },
  "datasets": [ "gb-address" ],
  "layouts": [ "your layout name" ]
}

Response

{
  "result": {
    "confidence": "Interaction required",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "LINE_1": "Experian Data Quality",
          "LINE_2": "160 Blackfriars Road",
          "Town": "LONDON",
          "Postcode": "SE1 8EZ"
        }
      }
    ]
  }
}

United States

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "187th St",
      "Hollis, NY 11423"
    ]
  },
  "datasets": [ "us-address" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Street partial",
    "suggestions_key": "VVNBfjcuNzMwNk1VU0FEd1BtQndBQUFBQUVBUW9BQVFBQUFBWFFmMTVTQ0NBQUFBQUFB",
    "suggestions_prompt": "Please confirm your building number",
    "suggestions": [
      {
        "global_address_key": "eE5ESXpBQUFBQUFBLX4yNn43",
        "text": "8800 ... 8898 187th St, Hollis NY 11423-1826",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMweE9VU0FEd1BtQndBQUFBQUJ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "8800 ... 8898 187th St, Hollis NY   [even]" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "11423-1826" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      },
      {
        "global_address_key": "JrZ2dnQUFBQUFBQUFBQUQuLjJRQUFBQUEuLi4uLndBQUFBQUFBQUFBQUFBQUFBQU",
        "text": "8801 ... 8899 187th St, Hollis NY 11423-1825",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMweE9VU0FEd1BtQndBQUFBQUJ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "8801 ... 8899 187th St, Hollis NY   [odd]" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "11423-1825" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      },
      {
        "global_address_key": "BQUFBQUFBQUFBQUFBQUFBREU0TjNSb0lGTjBMQ",
        "text": "9100 ... 9198 187th St, Hollis NY 11423-24ND",
        "format": "https://api.experianaperture.io/address/format/v1/VVNBfjcuNzMweE9VU0FEd1BtQndBQUFBQUJ",
        "additional_attributes": [
          { "name": "picklist_display", "value": "9100 ... 9198 187th St, Hollis NY   [even]" },
          { "name": "score", "value": "100" },
          { "name": "postcode", "value": "11423-24ND" },
          { "name": "multiples", "value": "true" },
          { "name": "unresolvable_range", "value": "true" }
        ]
      }
    ]
  }
}

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "77 Massachusetts Rd",
      "Cambridge, MA"
    ]
  },
  "datasets": [ "us-address" ]
}

Response

{
  "result": {
    "validation_detail": {
      "street_corrected": true,
      "zip_code_corrected": true
    },
    "confidence": "Verified match",
    "address": {
      "address_line_1": "77 Massachusetts Ave",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "Cambridge",
      "region": "MA",
      "postal_code": "02139-4307",
      "country": "UNITED STATES OF AMERICA"
    }
  }
}

Request

{
  "country_iso": "USA",
  "components": {
    "unspecified": [
      "8801 187th St, Hollis, 11423"
    ]
  },
  "datasets": [ "us-address" ],
  "layouts": [ "your layout name" ]
}

Response

{
  "result": {
    "validation_detail": {
      "state_corrected": true,
      "zip_code_corrected": true
    },
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "Organisation": "",
          "Street 1": "8801 187th St",
          "Street 2": "",
          "Street 3": "",
          "City": "Hollis",
          "State/Province": "NY",
          "ZIP/Postal Code": "11423",
          "Country/Region": "UNITED STATES OF AMERICA"
        }
      }
    ]
  }
}