Skip to main content

Global Intuitive


Global Intuitive (also referred to as REST v2) is a fast and efficient REST API for capturing validated global addresses. Get up and running in minutes with our client-side JavaScript sample code.

The API is designed and optimised to be integrated as a predictive style address capture solution. The simple workflow combined with simple API requests make integrating Global Intuitive into your system a pain-free process. With just two resources (GET /Search and GET /Format) it is easy to build your requests and get the best global address capture user experience.

This API uses TLS 1.2 encryption. Find out more.


The recommended workflow (as demonstrated by our sample code) is:

  1. Make a GET /Search request for each keystroke the user enters into your address capture field. Each request will comprise of the 3-digit ISO code of the country the user is searching on, the current text entered in the field and the number of suggestions to return. We recommend that you cancel any unfinished requests upon additional keystrokes.
  2. Display the address suggestions to the user beneath the address capture field.
  3. Make a GET /Format request when the user selects their address from the suggestions. The URL for this request is returned as part of the search suggestions.
  4. Display the selected address back to the user. You can do this by populating your relevant address fields or displaying outside of your form.
  5. Store the relevant address components in your database if required.

Sample code

Global Intuitive JavaScript sample code is hosted on our GitHub repository. The sample code is open sourced and includes information on how to get up and running quickly and how to modify and contribute to the code.

Get sample code

Postman collections

We now have pre-configured Postman collections for our APIs.

You can quickly test out the requests and responses and see how the API behaves. Simply import the relevant collections, add your token as a variable and start making requests with your desired parameters.

Get Postman collections


An Auth-Token is used to authenticate the service. Your Auth-Token must be specified in the request header or passed as a query parameter in the URL. 

Existing customers can view and manage their tokens via the Self Service Portal. For more information about tokens visit our portal help page.

Permitted URLs

We strongly recommended that you specify the permitted URLs to be used for address capture. This is essential to prevent fraudulent use of your token on another domain by ensuring that only requests made from your specified URLs are authenticated. See our portal help page for more information about tokens and instructions on how to set your permitted URLs.

API reference

The Global Intuitive API reference defines the available resources, parameters and the expected response values.  

The length and format of IDs are subject to change without prior notice. Caching or validation rules should not be implemented for IDs.


The optional dataset parameter allows you to specify the dataset the address you're searching for is sourced from.

Currently, dataset supports 3 countries:

  • Australia
  • Ireland
  • New Zealand

The table below contains information about the dataset values you can specify for each country.

Country Value Description
Australia "DataFusion" Dataset which consists of both PAF and G-NAF data. Also known as the AUE dataset.
"GNAF" Australia's Geocoded National Address File (G-NAF) dataset. Also known as the AUG dataset.
"PAF" Australia Post's Postal Address File (PAF) dataset. Also known as the AUS dataset.
Ireland "Eircode" Ireland's postcodes (Eircodes) dataset.
"PAF" Ireland's Postal Address File (PAF) dataset.
New Zealand "DataFusion" Dataset which contains additional, postally non-deliverable addresses that are not included in the PAF data. Also known as the NZD dataset.
"PAF" New Zealand's Postal Address File (PAF) dataset. Also known as the NZL dataset.

Note: The dataset you specify when sending a search request will also be used for the format call. If you don't specify a dataset, the default value, "PAF", will be used.

Format response components

When a successful Format request is made, three collections will be returned.


The Address collection comprises up to seven address lines representing a formatted address for the chosen country. The first three address lines will be comprised 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:

  United Kingdom United States  Canada  Australia  New Zealand   France  Rest of World
addressLine1 Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line
addressLine2  Auto Line Auto Line Auto Line Auto Line

Auto Line

Auto Line Auto Line
addressLine3  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
province    State Code Province Code  State Code  City   Province
postalCode Postcode Zip - Zip+4 Code Postal Code  Postcode  PostalCode  Postcode  Postal Code
country  Country  Country Country   Country Country  Country  Country


The Components collection comprises a number of specific address components. Each individual component can be added to relevant fields in your database. Each component will differ slightly from country to country. Any components that are blank 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. The components that are returned will depend on the level of coverage available in the data. 

  United Kingdom  United States Canada  Australia  New Zealand  France  Rest of World
deliveryService1 Delivery Service Identifier PO Box  Route Service Type/Number All Postal Delivery Types All Postal Delivery Types All PO Box Types  
deliveryService2     PO Box         
deliveryService3     Delivery Service Type/Name         
deliveryService4   Box Number           
deliveryPointID1        Delivery Point Identifier       
subBuilding1 Extension Designation  Secondary Number  Suite Name/Number Flat/Unit Name  Unit Textual + Unit alpha-num  Secondary Number + Secondary Number Ext  Secondary Address Units e.g. Apartments, Suites, Units etc.
subBuilding2        Building Level  Floor Number     
subBuilding3        Sub-Building Number  Sub-Building Number     
subBuilding4        Building Name 2       
building1  Building      Building Name  Building Name    Building Name
organisation1  Organisation Name          Company Name   
organisation2  Department          Department Name   
streetNumber1 Street Number  Primary Number  Street Number + Suffix  Building Number  Street Number  Number + Number Extension  Address/House Number
streetNumber2       Allotment Number       
street1 Primary Thoroughfare Name & Type Street  Street  Street  Street  Street  Street
street2 Secondary Thoroughfare Name & Type            
locality1 Town  City Name  Municipality  Locality  Suburb Town  Town/City
locality2 District Level 1 (dependent location 1)    Delivery Installation   Lobby Name Cedex Office  Settlement
locality3 District Level 1 (dependent location 2)        PNR Lobby Name  Additional Geographic Data   
locality4         Rural Delivery  Submitted Postal Locality/Geographic Town   
county1   County Name          County
province1       State Name  City  Departement  Province/State
provinceCode1   State Code  Province Code  State Code    INSEE code   
postalCode1 Postcode  Zip - Zip+4 Code  Postal Code  Postal Code  Postcode  Postcode  Postal Code
country1 Country Name  Country Name  Country Name  Country Name  Country Name   Country Name   Country Name
countryISO1 Three Character ISO Country Code  Three Character ISO Country Code   Three Character ISO Country Code    Three Character ISO Country Code     Three Character ISO Country Code      Three Character ISO Country Code       Three Character ISO Country Code   


The Metadata object contains relevant metadata for the returned address. The metadata can be stored in your database or used to decide if the address should be rejected.

The current metadata available is:

  • Delivery Point Validation (DPV). Only returned for addresses in the USA.
  • addressSource. Only returned for addresses in Australia.

For all other countries, an empty metadata object will be returned.

DPV data

The table below describes the DPV data that is returned inside the metadata object.

 Property Name Description Example
cmraIndicator Indicates whether the selected address is a Commercial Mail Receiving Agency. Y
seedIndicator Indicates if the address selected is a seed address. Y
dpvIndicator Indicates whether the selected address is DPV confirmed. Y
footnotes The footnotes contain extra information returned by the DPV lookup. AA, M3
Indicates if the address selected is known to be vacant and not receiving mail deliveries.
noStatsIndicator Indicates known addresses not receiving mail deliveries, for example an address for a house still under construction. Y
pbsaIndicator Indicates addresses known to be Post Office Box Street Addresses (PBSA). Y

addressSource data

The table below describes the addressSource data that is returned inside the metadata object.

 Property Name Description Example

Indicates whether the address is sourced from:

  • PAF data only (P).
  • G-NAF data only (G).
  • both (PG).
  • both, but the level information is exclusive to the PAF data (PGB).
description A description of the code. Address exists on both PAF and G-NAF

Response codes

Status CodeDescription
200: OK 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 the service.
404: Not Found The requested resource could not be found but may be available again in the future. Subsequent requests by the client are permissable.
500: Internal Server Error The server has encountered an error.
502: Bad Gateway Provider failure.

Upgrading from existing services

If you are looking to upgrade from Pro Web or Address Validate API SOAP (Formerly known as Pro On Demand) to Global Intuitive you will need to understand the differences in integration approach and how to prepare for this.


  • User Experience (UX) - requires a change in workflow; changes to the user input form are required.
  • Global Intuitive is much more interactive compared with previous versions of Address Validate API SOAP, therefore more requests are made.
  • Implementation change - going from SOAP to RESTful web services.
  • Global Intuitive forgoes the traditional address layout functionality in favour of returning a global 7 line address collection along with a full component breakdown. The 7 lines are for displaying back to the end user whilst the full component collection allows for specific components to be entered in to relevant database fields.
  • Pro Web customers should understand the additional security considerations of calling out to an external web service - opening ports/firewalls etc.


Experian have recently updated to token authentication instead of username/password credentials. Customers will not be able to use existing username/passwords from previous versions of Address Validate SOAP when using Global Intuitive.

A token can be passed through as a Request Header:

Auth-Token = a1b234c5-a1bc-1234-a1bc-123a4567891bc

Or appended to the GET request URL:

GET /Search?query={address}&country={country ISO code}&Auth-Token=a1b234c5-a1bc-1234-a1bc-123a4567891bc

Supported countries

The map below illustrates the level of coverage for each country and territory. The coverage levels represent how accurate the addresses are for major parts of the country. 

Delivery Point Addresses are accurate to delivery point level. e.g. a single delivery point within an apartment building, block of flats or high rise. Building/House Number Addresses are accurate to building level e.g. a single house or retail unit. Delivery point information may need to be entered manually. Street Addresses are accurate to street level. Delivery point information will need to be entered manually. Locality Addresses will be returned for some localities (e.g. cities and towns). Street and delivery point information will need to be entered manually.


Are Royal Mail postcode recodes supported by Global Intuitive?

Unfortunately postcode recodes are not supported at this time.


Are Royal Mail counties supported by Global Intuitive?

Unfortunately counties are not supported at this time.


What are the differences between older address layouts and the way addresses are returned by Global Intuitive?

Global Intuitive does not use the older layouts functionality. All addresses are returned in both a 7 line global format as well as each individual address component. The 7 line layout is designed to be displayed to the user upon selection of an address, whilst the individual address components are for storing in relevant database fields.


How are the search results ordered in Global Intuitive?

Results are ordered alphabetically by locality first.


Why am I getting exceptions when I attempt to connect to the service?

 Follow these steps to diagnose and solve your issue:
  • Firstly check that you are not having network or firewall connectivity issues by entering the URL in to an up to date browser. Make sure that the URL is correctly formatted.

    If the URL does not work then you should check your configuration so that you have access to
  • If you have ruled out connectivity issues then you may be experiencing issues with TLS compatibility. TLS 1.2 and SHA-256 support is required of the client by If your client does not know about, use or support these then you will see problems.

    In .NET you will get the following exception WebExceptions - Underlying connection closed. This is a result of .NET 4.5 and below defaulting to use TLS 1.1.

    To solve this problem in .NET, either recompile in .NET 4.6 or above (which defaults to TLS 1.2) or add the following line to your program:
    ServicePointManager.SecurityProtocol = SecurityProtocolType.Tls12;

Release notes

View the release notes for details on the latest changes to Global Intuitive.