Skip to content

pschott/Experian-Address-Validation

 
 

Repository files navigation

Experian Address Validation

GitHub version Build Status

This repository contains sample code for integrating with Experian's Address Validation API. Currently available for over 235 countries and territories.

Check out the demo.

Usage

Prerequisites

  • To use the API you need a token (You would have received this from your Experian account manager).

Integration

Options

After embedding the script tag in your webpage you can customise it by passing settings through to the API using an options object. By default you should at least pass through an elements object with the address field input(s) and country list selectors.

As well as this, you should also always provide your token.

var options = {
    token: "INSERT_TOKEN",
    elements: {
        inputs: [document.querySelector("input[name='address-input']")],
        countryList: document.querySelector("select")
    }
};

If you have your own return fields that you want a final address pasted to, you need to specify these in the elements object too.

Additional options that can be passed through include:

Property name Description Default
token Your authentication token. Recommended.
searchType The search type to use Autocomplete
location Latitude and Longitude values in a string separated by a comma (e.g. "40.52,-73.93") null
language The ISO 2 digit language code "en"
maxSuggestions The maximum number of suggestions to return 25
input.placeholderText The placeholder text for the input "Start typing an address"
input.applyFocus Whether to apply focus to the search field true
searchAgain.visible Whether the 'search again' link is shown true
searchAgain.text The text for the 'search again' link "Search again"
formattedAddressContainer.showHeading Whether to show a "Validated address" heading false
formattedAddressContainer.headingType If a heading is shown, what HTML element to use H3
formattedAddressContainer.validatedHeadingText Heading text for validated addresses "Validated address"
formattedAddressContainer.manualHeadingText Heading text if address entered manually "Manual address entered"
useSpinner Whether to display a spinner while searching false
addressLineLabels An array of 7 labels for the form fields ["addressLine1", "addressLine2", "addressLine3", "locality", "province", "postalCode", "country"]
Country list

The default sample page contains the full list of supported countries. This list should be amended to include only the countries that your integration supports. A full list of available countries and their ISO codes can also be found with our API documentation.

Tokens

For the purpose of this sample code, the tokens for the live endpoint aren't hardcoded in source control and must be appended to the query as a header parameter or set in the input field on the demo.

To get your token and a free trial, contact us via www.experian.co.uk/business/enquire

As mentioned above in Options you should pass your token through as a setting. The sample page in this repo appends it to the query string to avoid hardcoding a token in source control.

Invocation

Invoke a new instance by creating a new AddressValidation object.

var address = new AddressValidation(options);

Events

After instantiating a new instance the constructor returns an object that can be used to subscribe to events.

Event name Description Example usage
pre-search Before a typedown search takes place address.events.on("pre-search", function(term){ // ... });
pre-promptset-check Before a promptset API is called address.events.on("pre-promptset-check", function(){ // ... });
post-promptset-check After a promptset API was called address.events.on("post-promptset-check", function(data){ // ... });
pre-picklist-create Before a picklist is created address.events.on("pre-picklist-create", function(items){ // ... });
post-picklist-create After a picklist has been created address.events.on("post-picklist-create", function(items){ // ... });
post-picklist-selection After a picklist item has been selected address.events.on("post-picklist-selection", function(item){ // ... });
pre-refinement Just before a refinement takes place address.events.on("pre-refinement", function(global_address_key){ // ... });
pre-formatting-search Just before the formatting search takes place address.events.on("pre-formatting-search", function(url){ // ... });
post-formatting-search After the formatting search has returned a result address.events.on("post-formatting-search", function(data){ // ... });
post-reset After the demo has been reset address.events.on("post-reset", function(){ // ... });
post-search-type-change After the search type has been changed address.events.on("post-search-type-change", function(searchType){ // ... });
post-datasets-update To populate the authorized country dataset(s) into the country dataset dropdown address.events.on("post-datasets-update", function(){ // ... });
error-display To display error when the selected search type is not supported for the country dataset selected address.events.on("error-display", function (error){ // ... });
request-timeout A timeout occurred during the XMLHttpRequest address.events.on("request-timeout", function(xhr){ // ... });
request-error A generic error occurred initiating the XMLHttpRequest address.events.on("request-error", function(xhr){ // ... });
request-error-400 A 400 Bad Request error occurred address.events.on("request-error-400", function(xhr){ // ... });
request-error-401 A 401 Unauthorized error occurred (invalid token) address.events.on("request-error-401", function(xhr){ // ... });
request-error-403 A 403 Forbidden error occurred address.events.on("request-error-403", function(xhr){ // ... });
request-error-404 A 404 Not Found error occurred address.events.on("request-error-404", function(xhr){ // ... });

Customising labels

By default the API returns the formatted address using a global 7-line layout. This means that the field labels for every country are all the same. These are:

  • address_line_1
  • address_line_2
  • address_line_3
  • locality
  • region
  • postal_code
  • country

However, in your integration you might wish to change "locality" to "city" or "postalCode" to "post code", for example.

  1. Access the _translations.js file

  2. Add the localised labels to the existing object, following the language:country:property pattern. For example:

en: {
    gbr: {
      locality: "Town/City",
      region: "County",
      postal_code: "Post code"
    }
}

Any property you don't override will continue to use the default label.

NB. You can change the language by passing this setting through, as described in Options.

Returning results

The API returns the formatted address in json format as 7 lines.

If you have your own fields to paste the result to, you must tell the API about your fields. This is done when integrating the API and specifying your elements. As well as specifying the input and country field, you'd specify your "result" fields. e.g.

var countryMap = {"GB": "GBR","AF": "AFG","AX": "ALA","AL": "ALB","DZ": "DZA"};

var options = {
    elements: {
        inputs: [document.querySelector("input[name='address-input']")],
        countryList: document.querySelector("select"),
        countryCodeMapping : countryMap,
        address_line_1: document.querySelector("input[name='address_line_1']"),
        address_line_2: document.querySelector("input[name='address_line_2']"),
        address_line_3: document.querySelector("input[name='address_line_2']"),
        locality: document.querySelector("input[name='locality']"),
        region: document.querySelector("input[name='locality']"),
        postal_code: document.querySelector("input[name='postal_code']")
        country: document.querySelector("input[name='country']")
    }
};

A note on the country list: If you need to pass a value for the Datasets parameter to the API in order to specify a non-default dataset for a certain country, the value of the option in the country list should be in the format "{country ISO code};{dataset name}". Please see the API Reference for more details on the Datasets API parameter.

Notice how you can return multiple address lines to the same form field.

If you don't have your own fields, this sample code creates a new form field for each of the address lines and sets the value accordingly. These form fields are created for you and don't need to be specified in advance.

The form fields are wrapped in a div with a class name of "formatted-address".

The name attribute for each field is the same as the label discussed in Customising labels. That is, either the default label returned by the API, or a custom key if it's overridden.

Components and Metadata

In addition to the 7 address lines. A format request also returns an array of objects containing the individual components that make up the address and a metadata object. Currently the metadata object will return Delivery Point Validation (DPV) information for USA searches.

Components and Metadata are not designed to be returned to the user and instead should be stored separately. This will be specific to your requirements and is not included in the sample code.

More information can be found in the documentation.

Development

While you're free to take the JavaScript from the dist folder and use this in your website, should you want to contribute to this repo or make modifications to the code, you'll need to compile the new version from the src.

Make sure Node and npm installed.

Then:

  1. Fork this repo (https://github.com/experianplc/Experian-Address-Validation).
  2. Run npm install to get the configured packages.
  3. Run npm run build and ensure your changes are built to the output dist directory.
  4. Push your changes and, when ready, make a pull request for them to be added to master.

Support

At the time of writing, this sample code is currently supported in Chrome, Firefox, Safari and Edge latest, as well as IE 11.

Packages

No packages published

Languages

  • TypeScript 83.3%
  • JavaScript 9.3%
  • CSS 4.2%
  • HTML 3.2%