Datasets, layouts, and prompt sets

If you are unsure what datasets you can use or which datasets can be combined in a single request, you can use our GET /datasets endpoint to find out.

Check your datasets

  1. Go to our API specification page and click the GET /address/datasets/v1, so that it expands.
    GET /datasets swagger view
  2. Click Try it out in the upper-right corner.
  3. In the Parameter section:
    • Enter your token in the Auth-Token field.
    • (Optional) Enter a 3-letter country ISO code code, if you are interested in only datasets for one country.
  4. Click Execute to send the request to the API.
  5. View the response returned by the API under Responses. This will tell you what datasets you have under your license key, as well as what datasets work together. Note that your request was successful only if the API returned an HTTP status code of 200 - Success. Check out the possible Response status codes to find out more about scenarios where the API returns errors.

There are different layouts available with Experian Address Validation. You can use a public one that is available to all users, or contact us to create your own private layout to suit your solution. To check what you have available:

  1. Go to our API specification page and click the POST /address/layouts/v1, so that it expands.
    POST /layouts swagger view
  2. Click Try it out in the upper-right corner.
  3. In the Parameter section:
    • Enter your token in the Auth-Token field.
  4. In the Request body section you can select an example request from the dropdown. You can either use it as is or update the request body with your desired values.
  5. Click Execute to send the request to the API.
  6. View the response returned by the API under Responses. This will tell you what layouts are available to you. Note that your request was successful only if the API returned an HTTP status code of 200 - Success. Check out the possible Response status codes to find out more about scenarios where the API returns errors.

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.

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

To see the prompt set definitions:

  1. Go to our API specification page and click the POST /address/promptset/v1, so that it expands.
    POST /promptsets swagger view
  2. Click Try it out in the upper-right corner.
  3. In the Parameter section:
    • Enter your token in the Auth-Token field.
  4. In the Request body section you can select an example request from the dropdown. You can either use it as is or update the request body with your desired values.
  5. Click Execute to send the request to the API.
  6. View the response returned by the API under Responses. Note that your request was successful only if the API returned an HTTP status code of 200 - Success. Check out the possible Response status codes to find out more about scenarios where the API returns errors.

Default layouts

Components

The Components collection consists of all available address components. Each individual component can be added to relevant fields in your database. Note that components vary slightly from country to country. Components that do not contain any values for the selected address will not be returned by the API. 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.

Component 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.

Sub-component level 1 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 Postal code Postcode Postcode
secondary ZIP+4
Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
full_name Delivery service Delivery service (PO Box xxx) Delivery service (PO Box xxx) All postal delivery types All postal delivery types All PO Box types
service_type Delivery service type Delivery service type e.g. PO Box Delivery service type e.g. PO Box
service_number Delivery service value Delivery service value e.g. 5020 Delivery service value e.g. 5020
post_centre_name
Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
full_name Delivery service (Box xxx) Delivery Service
service_type Delivery service type e.g. Box Delivery Service Type
service_number Delivery service value e.g. 5020 Delivery Service Value
post_centre_name
           
Sub-component
level 1
Sub-component
level 2
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 Sub-
building
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
e.g.
Apartment
or
Suite
type Extension
designation
type
Secondary
address
identifier
Suite
Name
Flat/
unit
type
value Extension
designation
value
Secondary
address
number
Suite
number
Flat/
unit
number
Sub-component level 1 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
Sub-component
slevel 1
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
Sub-component level 1 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
Sub-component level 1 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
Sub-component level 1 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
Sub-component
level 1
Sub-component
level 2
United
Kingdom
United
States
Canada Australia New Zealand France Rest
of the
World
region name Départ-
ement
Region
code State
Code
Province
Code
INSEE
code
description
sub_region name County
name
Subregion
code
description
town name Town City
name
Muni-
cipality
Locality Suburb Town/
CEDEX
office
Town
code
description
district name Dependent
locality
Delivery
area
install-
ation
Lobby
name
Geo-
graphic
town
Settlement
code
description
sub_district name Double-
dependent
locality
PNR
Lobby
name
Postal
locality/
Geo-
graphic
town
code
description
Sub-component
level 1
United
Kingdom
United
States
Canada Australia New Zealand France Rest
of the
World
town town/city
district suburb