Address Validate REST Verification

Address Validate API provides a REST interface for accessing address searching and verification functionality. 

Address Validate API provides different address search workflows, depending on the dataset and your requirements.

GBR & USA datasets

search-address method:

With this method, the address is entered on a single line. This is the quickest and most efficient way to enter an address; allowing for partial address entry to achieve a complete and validated address.

verify-address method:

With this method, the whole address is entered first (similar to online address forms with multiple fields for address, city and postal code) and then passed on for searching. It requires the user to enter the complete address and works with your existing address forms.

GBR search examples

USA search examples

CAN dataset

verify-address method:

With this method, the whole address is entered first (similar to online address forms with multiple fields for address, city and postal code) and then passed on for searching. It requires the user to enter the complete address and works with your existing address forms.

CAN search examples

You can use our REST sample code for validating addresses, phones and emails. See Capture sample code guide for details.

Get sample code

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

In order to access address searching and verification functionality, the request has to be authenticated. 

There are two ways to make an authenticated API request:

1. The Auth-Token HTTP request header has to be passed with the GET request. For example:

GET https://api.experianmarketingservices.com/capture/v1/search-address/text?query=Clapham%20Court%2C%20Kings%20Avenue%2C%20LONDON&country=GBR HTTP/1.1

Auth-Token: 55929877-683b-856c-d3b8-7047fcf0582a  

Test your token

2. Alternatively, the token (auth-token) can be passed as a query parameter in the URL endpoint. For example: 

GET https://api.experianmarketingservices.com/capture/v1/search-address/text?query=Clapham%20Court%2C%20Kings%20Avenue%2C%20LONDON&auth-token=<your auth-token value>&country=GBR HTTP/1.1

Security

CORS

Address Validate API REST 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.

CORS Supported OS and Browsers:

• iOS devices (all versions)
• Safari, IE and Chrome

The default layouts for each country that are used when making a GET /address-layout request are listed below.

GBR: 

Line 1: auto
Line 2: auto
Line 3: auto
Line 4: Town (L21)
Line 5: County (L11)
Line 6: Postcode (C11)
Line 7: Country name (X11)

USA: 

Line 1: auto
Line 2: auto
Line 3: auto
Line 4: City name (L31)
Line 5: State Code (L11)
Line 6: ZIP code, +4 code (C11, C21)
Line 7: Country name (X11)

Canada:

Line 1: auto
Line 2: auto
Line 3: auto
Line 4: Municipality name (L31)
Line 5: Province code (L11)
Line 6: Postal code (C11)
Line 7: Country name (X11)

The threshold for the picklist (a list of suggested addresses) is set to 50, meaning that the first 50 addresses will be returned. 

However, for verify-address the results will not be affected by this threshold.

For example, if 100 results are found, then:

• 50 addresses will be returned with search-address

• 50 addresses will be returned. However, if the skip parameter is set to 50, then the remaining 51-100 addresses will be shown with verify-address

If unable to return a search result, Address Validate REST API will return an informational picklist (a list of suggested addresses).

GBR: search-address returns no match

{
  "count": 0,
  "results": [
    {
      "id": "",
      "text": "No matches",
      "grouped": false,
      "url": null
     }
  ]
}

GBR: search-address returns too many matches

{
  "count": 0,
  "results": [
    {
      "id": "",
      "text": "Search canceled (too many matches)",
      "grouped": false,
      "url": null
     }
  ]
}

USA: search-address is unable to match

{
  "count": 0,
  "results": [
    {
      "id": "",
      "text": "Continue typing",
      "grouped": false,
      "url": null
     }
  ]
}

GBR/USA/CAN: verify-address returns no match

{ 
  "prompt": "",
  "verifylevel": "None",
  "count": 0,
  "results": [
    {
      "id": "",
      "text": "No matches",
      "grouped": false,
      "url": null
     }
  ]
}

USA: verify-address is unable to refine an address

{ 
  "prompt": "",
  "count": 0,
  "results": [
    {
      "id": "",
      "text": "Address not recognized",
      "grouped": false,
      "url": null
     }
  ]
}

CAN: verify-address is unable to refine an address

{ 
  "prompt": "",
  "count": 0,
  "results": [] 
}

GBR: verify-address returns too many matches

{ 
  "prompt": "",
  "verifylevel": "None",
  "count": 0,
  "results": [] 
}