Skip to main content

Global Intuitive

Overview

Global Intuitive 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.

Workflow

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

Authentication

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.

Security

Global Intuitive supports Cross Origin Resource Sharing (CORS). This is a specification developed by W3C that allows browsers to make cross-domain requests, thus enabling client-side integrations.

When making a request, the browser will add an origin request header. The API will then respond with a CORS specific response header denoting the origin domains allowed to make requests to the API.

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, what parameters to include with each request and the expected response values. 

https://api.edq.com/capture/address/v2

Headers

The only header field that you will need to include is the Auth-Token field. Alternatively, you can send the token as a query parameter for increased performance. 

NameExampleExplanation
Auth-Token Auth-Token=a1b234c5-a1bc-1234-a1bc-123a4567891bc Used to authenticate your account. Auth-Token can also be passed as a parameter.

GET /Search

Returns a collection of suggested addresses based on the search query and selected country. Make a search request on every keystroke to present an updated picklist of suggestions as the user types.

GET /Search?query={address}&country={country ISO code}

Request

Parameters

NameRequired?ExampleExplanation
query yes query=2-3 Clapham Common North Side The input from the user so far.
country yes country=gbr The 3 digit ISO code of the country to search against.
take no take=7 The maximum number of results to be returned. If no value is supplied, the default will be 7. The maximum value is 100.
Auth-Token no Auth-Token=a1b234c5-a1bc-1234-a1bc-123a4567891bc

Used to authenticate your account. Auth-Token can also be included in the header.

Sample request

GET https://api.edq.com/capture/address/v2/search?country=gbr&query=experian+data+quality&take=7&auth-token=a1b234c5-a1bc-1234-a1bc-123a4567891bc

 

Response

NameExplanation
count The number of suggestions returned.
results The collection of suggestions returned for your address search.
results[index of result].suggestion The suggestion that should be presented to the user as a possible match to their input.
results[index of result].matched A collection of the characters in the suggestion that have been matched. Integrators can use this information to highlight matched text.
results[index of result].format If the end user selects this suggestion, this is the call to format and finalise the address. 

Sample response

{
  "count": 1,
  "results": [
    {
      "suggestion": "Experian Data Quality, George West House, 2-3 Clapham Common North Side, London, SW4 ...",
      "matched": [
        [
          0,
          21
        ]
      ],
      "format": "https://api.edq.com/capture/address/v2/format?country=GBR&id=AVX9qKeOqLzUlnmEb6-4"
    }
  ]
}

 

GET /Format

Returns the full address and component breakdown for the chosen address.

GET /Format?id={address id}&country={country ISO code}

Request

Parameters

NameRequired?ExampleExplanation
id Yes id=c24462349064hfasioge The id returned by the search for the chosen address.
country Yes country=gbr The ISO code of the country to search against.
Auth-Token No Auth-Token=a1b234c5-a1bc-1234-a1bc-123a4567891bc

Used to authenticate your account. Auth-Token can also be passed in the header.

Sample request

GET https://api.edq.com/capture/address/v2/format?country=gbr&id=AU_hpR6P8NyavaOj1A3M&auth-token=a1b234c5-a1bc-1234-a1bc-123a4567891bc

Response

NameExplanation
address A collection of 7 address lines.
address[index of address line] Returns a key-value pair, where the key is the name of the address line and the value is the address line itself.
components A breakdown of the individual components for this address.
components[index of component] Returns a key-value pair, where the key is the name of the component and the value is the component itself.

Sample response

{
  "address": [
    {
      "addressLine1": "Experian Data Quality"
    },
    {
      "addressLine2": "George West House"
    },
    {
      "addressLine3": "2-3 Clapham Common North Side"
    },
    {
      "locality": "LONDON"
    },
    {
      "province": ""
    },
    {
      "postalCode": "SW4 0QL"
    },
    {
      "country": "UNITED KINGDOM"
    }
  ],
  "components": [
    {
      "building1": "George West House"
    },
    {
      "organisation1": "Experian Data Quality"
    },
    {
      "streetNumber1": "2-3"
    },
    {
      "street1": "Clapham Common North Side"
    },
    {
      "locality1": "LONDON"
    },
    {
      "postalCode1": "SW4 0QL"
    },
    {
      "country1": "UNITED KINGDOM"
    },
    {
      "countryISO1": "GBR"
    }
  ]
}

 

Address components

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

Address

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 KingdomUnited 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  City  Town  Locality
province    State Code Province Code  State Code      Province
postalCode Postcode Zip - Zip+4 Code Postal Code  Postcode  PostalCode  Postcode  Postal Code
country  Country  Country Country   Country Country  Country  Country

Components

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 StatesCanada 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     
subBuidling4        Building Name 2       
building1  Building      Building Name  Building Name    Building Name
organisation1  Organisation Name          Company Name   
organisation2  Department          Department Name   
organisation3               
organisation4               
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       Rural Delivery     
locality1 Town  City Name  Municipality  Locality  City  Town  Town/City
locality2 District Level 1 (dependent location 1)    Delivery Installation   Suburb  Cedex Office  Settlement
locality3 District Level 1 (dependent location 2)        Lobby Name  Additional Geographic Data   
locality4         PNR Lobby Name  Submitted Postal Locality/Geographic Town   
county1   County Name          County
province1       State Name    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   

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.

Considerations

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

Security

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.

Troubleshooting

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 https://api.edq.com/capture.
  • 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 api.edq.com. 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;

Copyright ©, 2014-2017. All rights reserved.