home/Address validation/Pro Web/API reference (REST)/Datasets, layouts, and prompt sets

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 your swagger editor 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. Click Execute to send the request to the API.
  4. View the response returned by the API under Responses. This will tell you what datasets you have under your license. 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.

Check your dataset details

  1. Go to our your swagger editor and click the GET /address/datasets/v1/{dataset_code}, so that it expands.
    GET /datasets {dataset_codes}
  2. Click Try it out in the upper-right corner.
  3. In the Parameter section:
    • Enter the dataset code in the dataset_code field.
  4. Click Execute to send the request to the API.
  5. 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.

Response body parameters

Name Type Description
dataset_code string The code used to identify the set.
description string A description of the dataset.
copyright string Copyright information.
Version string Version information.
base_country string The base country/set for this set.
status string Status text.
server string The server ID you are using.
license_warning string For information on license_warning see the license warning elements.
days_left integer The number of days left.
data_days_left integer The number of days left your dataset is available.
license_days_left integer The number of days left on your license.

License warning elements

For any addition information on your license please contact us.

Name Type Description
None string No warning.
DataExpiring string Your data is expiring.
DataUnreadable string The data you provided is incorrect.
LicenceExpiring string Your license is expiring.
ClicksLow string The metered clicks that control usage of the data are running low.
Evaluation string The license that controls the use of data is evaluation-only.
NoClicks string You do not have any clicks left.
DataExpired string Your access to this dataset has expired.
EvalLicenceExpired string Your evaluation license has expired.
FullLicenceExpired string Your full license has expired.
LicenceNotFound string We could not find a valid license.

There are different layouts available with Pro Web. 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 your swagger editor and click the GET /address/layouts/v1, so that it expands.
    GET /layouts swagger view
  2. Click Try it out in the upper-right corner.
  3. In the Parameter section:
    • Enter the dataset code in the dataset_code field.
  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 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.

Test format against layout and dataset

To test your layout against a particular dataset to see how it will be formatted:

  1. Go to our your swagger editor and click the GET /address/layouts/v1, so that it expands.
    GET /layouts swagger view
  2. Click Try it out in the upper-right corner.
  3. In the Parameter section:
    • Enter the dataset code in the dataset_code field.
    • Enter the engine in the engine field.
    • (Optional) Enter the layout name in the layout field.
  4. Click Execute to send the request to the API.
  5. View the response returned by the API under Responses. This will tell you whether this combination of dataset, engine and layout will work (either Success or ???). 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).
  • Alternate3 - A different alternative prompt set where not all address elements are present.

To see the prompt set definitions:

  1. Go to our your swagger editor and click the GET /address/layouts/v1, so that it expands.
    GET /promptset swagger view
  2. Click Try it out in the upper-right corner.
  3. In the Parameter section:
    • Enter the dataset code in the dataset_code field.
    • Enter the engine in the engine field.
    • (Optional )Enter the prompt_set in the prompt_set field.
  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 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.

To test if the given dataset, engine and layout are available for you to use for a given search:

  1. Go to our your swagger editor and click the GET /address/layouts/v1, so that it expands.
    GET /layouts swagger view
  2. Click Try it out in the upper-right corner.
  3. In the Parameter section:
    • Enter the dataset code in the dataset_code field.
    • Enter the engine in the engine field.
    • (Optional) Enter the layout name in the layout field.
  4. Click Execute to send the request to the API.
  5. View the response returned by the API under Responses. This will tell you whether this combination of dataset, engine and layout will work ( Success). 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