Skip to main content

Address Validate SOAP Sample Code

Contents

Overview

Address Validate API SOAP sample code provides best practice integration of our global address search and validation functionality.

Choose the appropriate language:

For integrators who want to access our service directly, refer to the SOAP API integration guide.

Alternatively, REST API is also available for the GBR, USA and CAN datasets.

All SOAP endpoints

Please ensure your IT infrastructure allows access to these endpoints (firewall exceptions might need to be added).

We recommend connecting to your regional endpoint (e.g. UK endpoint for UK customers) as that will reduce latency. We also recommend using V3 endpoints, although previous versions are supported as well.

V3: supports the username/password, token and SAML authentication

Region SOAP Endpoint Port Protocol
UK/EMEA  https://ws.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx


 443 

  
HTTPS 
USA  https://ws2.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx
APAC  https://ws3.ondemand.qas.com/ProOnDemand/V3/ProOnDemandService.asmx

V2: supports username/password and SAML authentication

Region SOAP Endpoint Port Protocol
UK/EMEA https://ws.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx
  443 		  
 HTTPS 
USA https://ws2.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx
APAC https://ws3.ondemand.qas.com/ProOnDemand/V2/ProOnDemandService.asmx

V1: supports username/password authentication only

Region SOAP Endpoint Port Protocol
UK/EMEA https://ws.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx


443 

  
HTTPS
USA https://ws2.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx
APAC https://ws3.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx

Authentication

To use the sample code you need to have an active account.

System Requirements

Software

Component Recommended Other Options
Operating System Windows Server 2008 R2 SP1 (64 bit) Other Windows operating system (32 or 64 bit) which supports .NET
Web Server C# and PHP: IIS version 7.5 or later IIS versions 5.1, 6 or 7
JSP: Apache Tomcat 6 or later. N/A
Web Browser

Internet Explorer versions 8
Chrome v43.0.2357.132 and later
Firefox v38.0.5 or later

Internet Explorer versions 6, 9 or 10
Software Framework C#: .NET 4.5.2 or later .NET 2.0 SP2 (ASP.NET)
JSP: Java 1.6 (JSP) or later. N/A
PHP: PHP 5.5, with FastCGI installed, and SOAP and OpenSSL extensions enabled.

PHP 5.2 or later, with FastCGI installed, and SOAP and OpenSSL extensions enabled.
Token authentication is not supported for this PHP version.
Hardware
Component Recommended Other Options
CPU Intel Core Duo Other dual-core processor
RAM 2 GB 1 GB or more
Hard disk Approximately 30 MB N/A

C#

Address Validate SOAP sample code is also available in JSP and PHP.

C# Sample Code

C# Deployment

Using the code

1.  Ensure you have set up an account with us. For details go here

2. Download the code package (.zip) specific to your region: 

UK  USA  APAC  EMEA

 3. Deploy following the steps below.

Deployment

This quick deployment will result in a functional setup which can be used as a basis for a customized address searching and validation.

1. Extract the sample code

Before you begin, ensure that:

  • you have downloaded the code package (see above) and
  • have write access to wwwroot on the machine you want to host the sample code pages on.

To extract the package and make the code accessible to IIS:

  1. Navigate to the location where you saved the package.
  2. Right-click ICV2_CSharp.zip and extract the contents to a new folder called ICV2_CSharp.zip within the wwwroot directory.
    The default location is: C:\Inetpub\wwwroot (where C is the local disk of the machine you want to host the code pages on). 
2. Enter your connection details

Before you begin, ensure that:

  • you have write access to wwwroot on the machine you want to host the code pages on and
  • you have your username/password or token for your account.

To get the code to communicate with your account, you have to enter your username/password or token with the endpoint of its web service. If you would like to connect to the code pages via a proxy server, you should also enter optional proxy information.

  1. Navigate to the location you extracted the code package to. In most cases, this will be C:\Inetpub\wwwroot\ICV2_CSharp (where C is the local disk of the machine you want to host the sample code pages on).
  2. Open web.config in a plain text editor and configure the following parameters in the <appSettings> section:
    a) Edit <add key="Experian.Qas.Capture.OnDemandUrl" value="ENDPOINT"/>
    Where ENDPOINT is the endpoint of your regional service. 

    b) Ensure that only one authentication method is used: if you are using username and password, leave the token empty and vice versa. 

    For username and password authentication:
    <add key="Experian.Qas.Capture.OnDemandUsername"
value="ONDEMAND_USERNAME"/>
<add key="Experian.Qas.Capture.OnDemandPassword"
value="ONDEMAND_PASSWORD"/>
    Where ONDEMAND_USERNAME is your username and ONDEMAND_PASSWORD is the password.

    Note that special characters are not supported, and must be replaced with the relevant Unicode reference. For example, if your password is contraseña, you should use contrase&#241;a instead.

    For token authentication:
    <add key="Experian.Qas.Capture.OnDemandAuthToken"
value="ONDEMAND_AUTH-TOKEN"/>
    Where ONDEMAND_AUTH-TOKEN is your token.

    c) If you would like to connect to the code pages via a proxy server, uncomment the following lines in <appSettings> section and configure them accordingly:
    <add key="Experian.Qas.Capture.ProxyUrl" value="PROXY_ADDRESS:PORT"/>

    Where PROXY_ADDRESS is the location of your proxy server and PORT is the port number associated with this proxy.
     
    <add key="Experian.Qas.Capture.ProxyUser"
value="PROXY_USER"/>
<add key="Experian.Qas.Capture.ProxyPassword"
value="PROXY_PASSWORD"/>
    Where PROXY_USER is the user login for this proxy and PROXY_PASSWORD is the corresponding password.
3. Configure IIS

Before you begin, ensure that:

  • you have access to IIS on the machine you want to host the code pages on and
  • at least one website has to be set up.

Configuring IIS to publish the code will make the address searching and validating pages accessible to you and other users:

  1. Access IIS Manager from the Administrative Tools menu in the Windows Control Panel.
  2. In IIS, select the machine you extracted the code package to. In most cases, this will be the local machine.
  3. If you are using IIS 7 or later:
    a. Right-click the ICV2_CSharp folder and select Convert To Application.
    b. In the Add Application dialog click OK.
  4. If you are using IIS 5.1 or 6:
    a. Right-click the ICV2_CSharp folder and select Properties.
    b. In the ICV2_CSharp Properties dialog click Create and OK.
4. Test your deployment

Check that your deployment has been successful: http://localhost/ICV2_CSharp. You will be directed to the index page if the deployment has been successful:

These web pages can be used as a basis for your own deployment. Alternatively, you can integrate address searching and validation into your own pages.

C# Integration

This section applies only if you are adding address searching and validation functionality to your existing web pages.

Copy the code in this section to the relevant areas of your HTML pages.

Integrate address capture

Add Javascript and CSS references

References to the Javascript and CSS files have to be added to all the pages you want address searching to be applied to. The following should be added to the <head> section: 

<link rel="stylesheet" href="css/qas-ic.css" type="text/css" />
<script type="text/javascript" src="js/jquery/jquery-1.6.2.min.js">
</script>
<script src="js/jquery/jquery.tmpl.min.js"></script>
<script type="text/javascript" src="js/jquery/jquery.cookie.js"></script>
<script type="text/javascript" src="js/jquery/jquery.showLoading.min.js">
</script>
<script type="text/javascript" src="js/qas-ic.js"></script>
<script type ="text/javascript" src="js/qas-ic.addresscapture.js">
</script> 

If you are modifying a page that does not exist in the same folder as the css and js folders supplied with the sample code, you should modify the paths in the above code as appropriate.

 Insert address searching fields

Input and output fields are the basis of address searching and validation. Address information is provided by the user via input fields, passed to Address Validation and then displayed via the output fields for confirmation.

  1. Insert the following Javascript at the bottom of the <head> section: 
    <script type="text/javascript">
$(function(){ 
qas.addresscapture.Initialize("div#QAS_Container");
}); 
</script>
    This will populate the address searching section while the page loads.
  2. Insert the following <div> element within the <body> section:
    <div id="QAS_Container"></div>
    This element will be dynamically populated with the input fields required to collect information from the user.
    You should place this element in the area of the page you would like the input fields to appear. For example, if you were adding address searching to the ordering page of an online shop, you might place this <div> between the first/last name and credit card number/expiry date fields. 

    3. Save the changes and load the web page in a browser to test the integration. 

Integrate address verification

Add Javascript and CSS references

References to the Javascript and CSS files have to be added to all the pages you want to address vaildation to be applied to. The following should be added to the <head> section:

<link rel="stylesheet" href="css/qas-ic.css" type="text/css" />
<script type="text/javascript" src="js/jquery/jquery-1.6.2.min.js">
</script>
<script type="text/javascript" src="js/jquery/jquery-ui-1.8.14.custom.min.js"></script>
<script type="text/javascript" src="js/jquery/jquery.cookie.js">
</script>
<script type="text/javascript" src="js/qas-ic.js"></script>
<script type="text/javascript" src="js/qas-ic.verification.js"></script>

If you are modifying a page that does not exist in the same folder as the css  and js folders supplied with the sample code, you should modify the paths in the above code as appropriate. 

Insert address validation fields

Input and output fields are the basis of address searching and validation. Address information is provided by the user via input fields, passed to Address Validation and then displayed via the output fields for confirmation.

  1. Insert the following <fieldset> element within the <body> section:
<fieldset>
<legend><span class="translation">
LANGUAGES.VERIFICATION.MailingAddress</span></legend>
<ol><li>
<label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress1</span>
</label><input id='add1' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress2</span>
</label><input id='add2' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress3</span>
</label><input id='add3' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputCity</span>
</label><input id='city' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputState</span>
</label><input id='state' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputZip</span>
</label><input id='zip' type='text' size="10" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputCountry</span>
</label><select id='country' class="countrySelector"></select>
</li></ol>
</fieldset>

You should place this element in the area of the page you would like it to appear. For example, if you are adding address validation to the contact details page of a customer management system, you might place this <fieldset> between the first/last name and the telephone number/email address fields.

  1. You can add more <fieldset> elements if required. By default, your address validation pages can contain up to 3 of these elements (although you can add more later).

    To enable the sample code to distinguish between them, you should make the following changes to any subsequent fieldsets that you add:

    • MailingAddress should become BillingAddress in a second fieldset or AlternateAddress in a third

    • All address element IDs (such as add1) should be preceded by bill in a second fieldset or alt in a third

    See verification.htm (supplied with the sample code) for an example of an sample which makes use of multiple fieldsets.
  2. Insert the following <input> elements below the <fieldset> element(s):
    <input id='subButton' name='subButton' class='translation'
type='button' value='LANGUAGES.VERIFICATION.ButtonSubmit'
onclick='qas.verification.QAS_Verify()' />

<input id='clear' name='subButton' class='translation' type='submit'
value='LANGUAGES.VERIFICATION.ButtonClear' onclick='clearforms()' />
    This will place buttons below the address entry form(s), allowing the user to submit their address information to Address Validate or clear all entries.

  3. Insert the following Javascript at the bottom of the <body> section:
    <script type="text/javascript">
$(document).ready()
{qas.verification.Init();
};
</script>
    This will allow address validation to take place, once the page has loaded.

  5. Save the changes and load the web page in a browser to test the integration.

C# Configuration

Once integrated, you can configure the pages to fully incorporate them into your existing website structure. You can add and remove below elements as necessary.

Modify the following three areas to customize your setup:

1. Set a default country and address layout

Address Validate code sets all country selection dropdowns to a default value on user's first visit. On subsequent visits, these dropdowns default to each user's last selected country (see cookie settings below for details).

To modify the default settings, open qas-ic.js from the js folder.

    1. To configure which country will be selected by default on user's first visit, locate the following line and configure it accordingly:
      qas.search.DEFAULT_COUNTRY_ID = "XYZ";
      Where XYZ is the country code. For example, using the USA code will enable Address Validate to search for addresses within United States by default.
      Note that you have to be licensed for each dataset you want to use. To remove entries from the country dropdowns see country selection options below.

    2. You can also configure the default address layout that Address Validate will use when returning addresses. To do this, locate the following line and configure it accordingly:
      qas.search.DEFAULT_LAYOUT = "LayoutName";
      Where LayoutName is the name of the layout you want to use by default. In most cases, this should be set to Database Layout which exists for every country.
      You can also set specific layouts for Address Validate to use when returning addresses for individual countries. See country specific layout settings below for details.

    3. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).
2. Set appropriate language options

If you have users from multiple countries, you should set up the appropriate language files.

You can have one language file for each language. These files are used to ensure that the prompts and messages are displayed in the appropriate language.

Creating a new language file

The sample code is provided with two language files: UK English and US English. To create a file for another language:

    1. Navigate to the location you extracted the code package to. In most cases, this will be: C:\Program Files\Apache Software Foundation\Tomcat X\webapps\ICV2_JSP (where C is the local disk of the machine you want to host the code pages on and X is the version of Apache Tomcat you want to use).
    2. Navigate to \js\lang.
    3. Make a copy of one of the Javascript files in the lang folder and name it appropriately. For example, a French language file might be called fr.js.
    4. Open qas-ic.js.
    5. In the qas.lang.Type and qas.lang.DisplayMapping sections add entries to include the new language file:
      qas.lang.Type = {
EN_UK : "en-gb",
EN_US : "en-us",
FR : "fr" };
qas.lang.DisplayMapping = {
EN_UK : "English (UK)",
EN_US : "English (US)",
FR : "Français" };
      Where FR is an internal reference for the language file, fr is its filename (the file extension is not required), and Français is how you would like this option to appear in the code pages.
      Note that the penultimate entry in each list has to end with a comma (,).
    6. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Editing a language file

To edit the prompts and messages in a language file:

    1. Open the language file you want to edit. For example, to translate messages for French users, open the fr.js file.
    2. Scroll down to the section you want to make changes to. The language files are made up of five sections:

      • INDEX and MATRIX sections control the text found on the index and comparison pages. In most cases, you will not need to edit these.

      • COMMON section controls text shared by all pages.

      • ADDRESS_CAPTURE and VERIFICATION sections control text found on the address searching and validation pages, respectively.
    3. Locate the message you would like to change and edit its value (each message has a name and a value, the name shouldn't be changed). 

      For example, to translate the first message in the address searching process for French users, you should locate this line in the ADDRESS_CAPTURE section: "PleaseSelectACountryOrDatamap" : "To begin, select your country.",

      And change it to: "PleaseSelectACountryOrDatamap" : "Pour commencer, sélectionnez votre pays.",
    4. Repeat step 3 for other messages as necessary.
    5. You can also link directly to a regional Experian Data Quality support site by editing the last two letters of the SupportLink line in the COMMON section.

      For example, editing the line below will map the support link on the sample Code pages to the French support site: "SupportLink": "http://support.qas.com/?sc=fr",

      Available options are:
      • au (Australia)
      • ca (Canada)
      • ie (Ireland)
      • nl (Netherlands)
      • nz (New Zealand)
      • sg (Singapore)
      • uk (United Kingdom)
      • us (United States)
    6. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Creating a new flag

Each language file supplied with the sample code is accompanied by an image of the relevant flag.

To create an image for your new language file:

    1. Navigate to img\flags.
    2. Make a copy of one of the .png files in the flags folder and rename it accordingly. For example, fr.png to accompany the French language file.
    3. Open the file with any photo editor and modify.
    4. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).
3. Prepare your web pages for live deployment

This section offers steps that should be taken before publishing your deployment to a live website.

Debug mode

While testing your deployment, you may receive non-critical error messages which you do not want to display to the end users.

For example, searching with too few details (e.g. house number only) will result in an error message but interaction will still be possible. To prevent this type of error message from displaying to your end users, locate the following line in the qas-ic.js file and set to false:

qas.search.DISPLAY_ERROR = false;

Debug may alert you to timeout issues affecting your deployment.

Position on page and styling

You can position the address searching and validation fields anywhere within a web page, either by placing them within the markup of an existing page or by editing the pages provided with the code. If you decide to edit the provided pages, you should remove any elements that you do not need before adding new content.

Note that nothing should be removed from the <head> sections.

Once your web pages contain the required content, you can style them by editing the qas.ic.cssstylesheet, located in the css folder. See CSS property reference for details.

C# Advanced configuration

Country specific layout settings

Address layouts define how addresses are formatted by Address Validate. You can set the default address layout using the DEFAULT_LAYOUT setting.

If you want to override the default setting when searching in one or more specific countries, locate the following lines within the qas-ic.js file and configure them accordingly:

qas.search.DEFAULT_COUNTRY_LAYOUT_MAP = {
 "XY1" : "LayoutName1",
 "XY2" : "LayoutName2"
};

Where XY1 and XY2 are the three-character identifiers of the datasets you are licensed to use; and LayoutName1 and LayoutName2 are the names of the corresponding layouts you want to be used with these countries.

You can add as many lines to this setting as you need; one for each dataset that you are licensed to use. Any datasets that do not appear in this list will use the default layout. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

 Additional address lines

This section is relevant to address validation pages only.

Some address layouts contain more information than the standard address details. For example, names information. To find out what extra information is available, refer to your data guide(s) or contact support.

To add additional address lines (this example uses GeoCodeLayout):

  1. Open qas-ic.verification.js and locate the following section:
    qas.verification.address_field_ids =
[["add1","add2","add3","city","state","zip"],
["billadd1","billadd2","billadd3","billcity","billstate","billzip"],
["altadd1","altadd2","altadd3","altcity","altstate","altzip"]];
    Configure this section to include entries for the additional information you want to be returned. For example, to accommodate returned country,latitude and longitude information within the first fieldset element, add the following entries:
    qas.verification.address_field_ids =
[["add1","add2","add3","city","state","zip","ctry","lat","long"],
["billadd1","billadd2","billadd3","billcity","billstate","billzip"],
["altadd1","altadd2","altadd3","altcity","altstate","altzip"]];
    All entries within this section have to be unique and should represent the address elements in the order that they appear in the layout.
  2. Open verification.htm and locate the first <fieldset> section. Insert the following lines immediately before the closing </ol> tag: 
    <li style="display:none">
<input id="ctry" type="text" size="10" /></li>

<li><label>
<span class="translation">LANGUAGES.VERIFICATION.Location</span>
</label>
<input class="readonly" id="lat" size="8" readonly="true" />
<input class="readonly" id="long" size="8" readonly="true" /></li>
    Note that the ctry input element is not given a label and its <li> element has not been set to display on the page. This is to reduce duplication, as the country selection dropdown already contains this information.
    However, this input element has to exist in the HTML since address elements are always returned in the order they appear in the layout.
  3. Open one of your language files and add an entry in the VERIFICATION section for the Locationlabel:
    "Location": "Location:",
    You should repeat this step for each of your language files, translating value as necessary.
  4. Save qas-ic.verification.js, verification.htm and your language files.
  5. To test these changes, reload your address validation page by clearing your browser's cache (Ctrl+F5).
Country selection options

The country selection dropdowns automatically include entries for every dataset you are licensed to use.

Sample code also includes an additional list of all countries in the country selection dropdowns (by default, this list appears under --Other--). If a user selects a country from this list, they will be asked to enter their address manually.

You may want to remove certain countries from this additional list. For example, for an online store you might remove countries which your company does not ship products to.

To remove countries:

  1. Open the qas-ic.js file in a text editor.
  2. Locate the qas.search.ALL_COUNTRIES section and highlight the entry you want to remove. For example, to remove Tuvalu:
    },{
    "Name" : "Tuvalu",
    "ID" : "TUV"
    }    ,{
  3. Delete or comment out the in bold selection.
  4. Repeat steps 2 and 3 until you have removed all the countries you do not want to include in the country selection dropdown.
  5. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).
Cookie settings

Address Validate sample code uses cookies to store users' search preferences locally.

To customize the default settings, locate the following lines in the qas-ic.js file and configure them accordingly:

qas.lang.COOKIE_NAME = "Language_Cookie";
...
qas.search.DEFAULT_COUNTRY_COOKIE_NAME = "Country_Cookie";
qas.search.DEFAULT_COUNTRY_COOKIE_EXPIRY = X;

Where:

  • Language_Cookie is the name of the cookie which stores the user's preferred language
  • Country_Cookie is the name of the cookie which stores the user's preferred country
  • X is the number of days for which Cookie_Name will be stored on the user's machine (Language_Cookie will expire at the end of the user's browser session).

To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Address Validate settings

You can configure how the requests are made by modifying the following settings and their values, found in the qas-ic.js file:

qas.search.DEFAULT_PROMPTSET_TYPE = qas.search.PromptsetType.DEFAULT;
qas.search.DEFAULT_IS_FLATTEN = false;
qas.search.DEFAULT_THRESHOLD = 25;
qas.search.DEFAULT_TIMEOUT = 5000;
qas.search.DEFAULT_INTENSITY = qas.search.IntensityType.CLOSE;
qas.search.DEFAULT_LOCALISATION = "";
qas.search.DEFAULT_REQUEST_TAG = "";
qas.search.DEFAULT_IS_FORMATTED_ADDRESS_IN_PICKLIST = false;

JSP

Address Validate SOAP sample code is also available in C# and PHP.

JSP Sample Code

JSP Deployment

Using the code

1.  Ensure you have set up an account with us. For details go to https://www.edq.com/address-verification

2. Download the code package (.zip) specific to your region: 

UK  USA  APAC  EMEA

3. Deploy following the steps below.

Deployment

This quick deployment will result in a functional setup which can be used as a basis for a customized address searching and validation.

1. Extract the sample code

Before you begin, ensure that:

  • you have downloaded the code package (see above) and
  • have write access to webapps on the machine you want to host the sample code pages on.

To extract the package and make the code accessible to Apache Tomcat:

  1. Navigate to the location where you saved the package.
  2. Right-click ICV2_JSP.zip and extract the contents to the webapps directory.

2. (Re)start Apache Tomcat to publish the implementation code

Before you begin, ensure that you have access to Apache Tomcat on the machine you want to host the code pages on.

(Re)starting Apache Tomcat will publish the implementation code, making address searching and validation pages accessible to you and your users:

    1. Access Services from the Administrative Tools menu.
    2. In the Services window right-click the Apache Tomcat X service (where X is the version you extracted the package to earlier).
    3. Click Start. If the Apache Tomcat service is already running, click Restart.

Once Apache Tomcat has restarted, the package will be extracted to a folder named ICV2_JSP within the webapps directory.

3. Add connection details to web.xml

Before you begin, ensure that:

  • you have write access to webapps on the machine you want to host the code pages on and
  • you know the username/password or token for your account.  

In order for the implementation code to communicate with your account, you have to enter your username/password or token along with the endpoint of its web service.

If you would like to connect via a proxy server, you should also enter optional proxy information.

  1. Navigate to the location where you saved the package. 
    The default location is: C:\Program Files\Apache Software Foundation\Tomcat X\webapps\ICV2_JSP(where X is the version of Apache Tomcat you want to use).
  2. From the WEB-INF folder open web.xml in a plain text editor and configure the following parameters:
    a) In the <!-- WSDL endpoint --> section, configure the following:
    <context-param>
<param-name>OnDemandProWebEndpoint</param-name>
<param-value>
ENDPOINT
</param-value>
</context-param>
    Where ENDPOINT is the endpoint of your regional service.

    b) Ensure that only one authentication method is used: if you are using username and password, leave the token empty and vice versa. 
    For username and password authentication, configure the following in the <!-- Web service authentication --> section: 
    <context-param>
<param-name>AuthenticationUsername</param-name>
<param-value>user</param-value>
</context-param>
<context-param>
<param-name>AuthenticationPassword</param-name>
<param-value>password</param-value>
</context-param>
    Where user is your username and password is the password.
    Note that special characters are not supported, and must be replaced with the relevant Unicode reference. For example, if your password is contraseña, you should use contrase&#241;a instead.

    For token authentication, configure the following in the <!-- Web service authentication --> section:
    <context-param>
<param-name>AuthenticationAuthToken</param-name>
<param-value>token</param-value>
</context-param>
    Where token is your token.
  3. If you would like to connect to the code pages via a proxy server, configure the following parameters in the <!-- Optional proxy settings --> section:

    a) 
    <context-param>
<param-name>HttpProxyHost</param-name>
<param-value>PROXY</param-value>
</context-param>
<context-param>
<param-name>HttpProxyPort</param-name>
<param-value>8080</param-value>
</context-param>
    Where PROXY is the location of your proxy server and 8080 is the port number associated with this proxy.

    b) 
     
    <context-param>
<param-name>HttpProxyHost</param-name>
<param-value>PROXY</param-value>
</context-param>
<context-param>
<param-name>HttpProxyPort</param-name>
<param-value>8080</param-value>
</context-param>
    Where proxyuser is the user login for this proxy and proxypassword is the corresponding password.
4. Test your deployment

Check that your deployment has been successful: http://localhost:8080/ICV2_JSP where 8080 is the port number associated with Apache Tomcat. You will be directed to the index page if the deployment has been successful:

These web pages can be used as a basis for your own deployment. Alternatively, you can integrate address searching and validation into your own pages.

JSP Integration

This section applies only if you are adding address searching and validation functionality to your existing web pages.

Copy the code in this section to the relevant areas of your HTML pages.

Integrate address capture

Add Javascript and CSS references

References to the Javascript and CSS files have to be added to all the pages you want address searching to be applied to. The following should be added to the <head> section: 

<link rel="stylesheet" href="css/qas-ic.css" type="text/css" />
<script type="text/javascript" src="js/jquery/jquery-1.6.2.min.js">
</script>
<script src="js/jquery/jquery.tmpl.min.js"></script>
<script type="text/javascript" src="js/jquery/jquery.cookie.js"></script>
<script type="text/javascript" src="js/jquery/jquery.showLoading.min.js">
</script>
<script type="text/javascript" src="js/qas-ic.js"></script>
<script type ="text/javascript" src="js/qas-ic.addresscapture.js">
</script> 

If you are modifying a page that does not exist in the same folder as the css and js folders supplied with the sample code, you should modify the paths in the above code as appropriate.

 Insert address searching fields

Input and output fields are the basis of address searching and validation. Address information is provided by the user via input fields, passed to Address Validation and then displayed via the output fields for confirmation.

  1. Insert the following Javascript at the bottom of the <head> section: 
    <script type="text/javascript">
$(function(){ 
qas.addresscapture.Initialize("div#QAS_Container");
}); 
</script>
    This will populate the address searching section while the page loads.
  2. Insert the following <div> element within the <body> section:
    <div id="QAS_Container"></div>
    This element will be dynamically populated with the input fields required to collect information from the user.
    You should place this element in the area of the page you would like the input fields to appear. For example, if you were adding address searching to the ordering page of an online shop, you might place this <div> between the first/last name and credit card number/expiry date fields. 

    3. Save the changes and load the web page in a browser to test the integration. 

Integrate address verification

Add Javascript and CSS references

References to the Javascript and CSS files have to be added to all the pages you want to address vaildation to be applied to. The following should be added to the <head> section:

<link rel="stylesheet" href="css/qas-ic.css" type="text/css" />
<script type="text/javascript" src="js/jquery/jquery-1.6.2.min.js">
</script>
<script type="text/javascript" src="js/jquery/jquery-ui-1.8.14.custom.min.js"></script>
<script type="text/javascript" src="js/jquery/jquery.cookie.js">
</script>
<script type="text/javascript" src="js/qas-ic.js"></script>
<script type="text/javascript" src="js/qas-ic.verification.js"></script>

If you are modifying a page that does not exist in the same folder as the css  and js folders supplied with the sample code, you should modify the paths in the above code as appropriate. 

Insert address validation fields

Input and output fields are the basis of address searching and validation. Address information is provided by the user via input fields, passed to Address Validation and then displayed via the output fields for confirmation.

  1. Insert the following <fieldset> element within the <body> section:
<fieldset>
<legend><span class="translation">
LANGUAGES.VERIFICATION.MailingAddress</span></legend>
<ol><li>
<label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress1</span>
</label><input id='add1' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress2</span>
</label><input id='add2' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress3</span>
</label><input id='add3' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputCity</span>
</label><input id='city' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputState</span>
</label><input id='state' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputZip</span>
</label><input id='zip' type='text' size="10" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputCountry</span>
</label><select id='country' class="countrySelector"></select>
</li></ol>
</fieldset>

You should place this element in the area of the page you would like it to appear. For example, if you are adding address validation to the contact details page of a customer management system, you might place this <fieldset> between the first/last name and the telephone number/email address fields.

  1. You can add more <fieldset> elements if required. By default, your address validation pages can contain up to 3 of these elements (although you can add more later).

    To enable the sample code to distinguish between them, you should make the following changes to any subsequent fieldsets that you add:

    • MailingAddress should become BillingAddress in a second fieldset or AlternateAddress in a third

    • All address element IDs (such as add1) should be preceded by bill in a second fieldset or alt in a third

    See verification.htm (supplied with the sample code) for an example of an sample which makes use of multiple fieldsets.
  2. Insert the following <input> elements below the <fieldset> element(s):
    <input id='subButton' name='subButton' class='translation'
type='button' value='LANGUAGES.VERIFICATION.ButtonSubmit'
onclick='qas.verification.QAS_Verify()' />

<input id='clear' name='subButton' class='translation' type='submit'
value='LANGUAGES.VERIFICATION.ButtonClear' onclick='clearforms()' />
    This will place buttons below the address entry form(s), allowing the user to submit their address information to Address Validate or clear all entries.

  3. Insert the following Javascript at the bottom of the <body> section:
    <script type="text/javascript">
$(document).ready()
{qas.verification.Init();
};
</script>
    This will allow address validation to take place, once the page has loaded.

  5. Save the changes and load the web page in a browser to test the integration.

JSP Configuration

Once integrated, you can configure the pages to fully incorporate them into your existing website structure. You can add and remove below elements as necessary.

Modify the following three areas to customize your setup:

1. Set a default country and address layout

Address Validate code sets all country selection dropdowns to a default value on user's first visit. On subsequent visits, these dropdowns default to each user's last selected country (see cookie settings below for details).

To modify the default settings, open qas-ic.js from the js folder.

    1. To configure which country will be selected by default on user's first visit, locate the following line and configure it accordingly:
      qas.search.DEFAULT_COUNTRY_ID = "XYZ";
      Where XYZ is the country code. For example, using the USA code will enable Address Validate to search for addresses within United States by default.
      Note that you have to be licensed for each dataset you want to use. To remove entries from the country dropdowns see country selection options below.

    2. You can also configure the default address layout that Address Validate will use when returning addresses. To do this, locate the following line and configure it accordingly:
      qas.search.DEFAULT_LAYOUT = "LayoutName";
      Where LayoutName is the name of the layout you want to use by default. In most cases, this should be set to Database Layout which exists for every country.
      You can also set specific layouts for Address Validate to use when returning addresses for individual countries. See country specific layout settings below for details.

    3. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).
2. Set appropriate language options

If you have users from multiple countries, you should set up the appropriate language files.

You can have one language file for each language. These files are used to ensure that the prompts and messages are displayed in the appropriate language.

Creating a new language file

The sample code is provided with two language files: UK English and US English. To create a file for another language:

    1. Navigate to the location you extracted the code package to. In most cases, this will be: C:\Program Files\Apache Software Foundation\Tomcat X\webapps (where X is the version of Apache Tomcat you want to use).
    2. Navigate to \js\lang.
    3. Make a copy of one of the Javascript files in the lang folder and name it appropriately. For example, a French language file might be called fr.js.
    4. Open qas-ic.js.
    5. In the qas.lang.Type and qas.lang.DisplayMapping sections add entries to include the new language file:
      qas.lang.Type = {
EN_UK : "en-gb",
EN_US : "en-us",
FR : "fr" };
qas.lang.DisplayMapping = {
EN_UK : "English (UK)",
EN_US : "English (US)",
FR : "Français" };
      Where FR is an internal reference for the language file, fr is its filename (the file extension is not required), and Français is how you would like this option to appear in the code pages.
      Note that the penultimate entry in each list has to end with a comma (,).
    6. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Editing a language file

To edit the prompts and messages in a language file:

    1. Open the language file you want to edit. For example, to translate messages for French users, open the fr.js file.
    2. Scroll down to the section you want to make changes to. The language files are made up of five sections:

      • INDEX and MATRIX sections control the text found on the index and comparison pages. In most cases, you will not need to edit these.

      • COMMON section controls text shared by all pages.

      • ADDRESS_CAPTURE and VERIFICATION sections control text found on the address searching and validation pages, respectively.
    3. Locate the message you would like to change and edit its value (each message has a name and a value, the name shouldn't be changed). 

      For example, to translate the first message in the address searching process for French users, you should locate this line in the ADDRESS_CAPTURE section: "PleaseSelectACountryOrDatamap" : "To begin, select your country.",

      And change it to: "PleaseSelectACountryOrDatamap" : "Pour commencer, sélectionnez votre pays.",
    4. Repeat step 3 for other messages as necessary.
    5. You can also link directly to a regional Experian Data Quality support site by editing the last two letters of the SupportLink line in the COMMON section.

      For example, editing the line below will map the support link on the sample Code pages to the French support site: "SupportLink": "http://support.qas.com/?sc=fr",

      Available options are:
      • au (Australia)
      • ca (Canada)
      • ie (Ireland)
      • nl (Netherlands)
      • nz (New Zealand)
      • sg (Singapore)
      • uk (United Kingdom)
      • us (United States)
    6. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Creating a new flag

Each language file supplied with the sample code is accompanied by an image of the relevant flag.

To create an image for your new language file:

    1. Navigate to img\flags.
    2. Make a copy of one of the .png files in the flags folder and rename it accordingly. For example, fr.png to accompany the French language file.
    3. Open the file with any photo editor and modify.
    4. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).
3. Prepare your web pages for live deployment

This section offers steps that should be taken before publishing your deployment to a live website.

Debug mode

While testing your deployment, you may receive non-critical error messages which you do not want to display to the end users.

For example, searching with too few details (e.g. house number only) will result in an error message but interaction will still be possible. To prevent this type of error message from displaying to your end users, locate the following line in the qas-ic.js file and set to false:

qas.search.DISPLAY_ERROR = false;

Debug may alert you to timeout issues affecting your deployment.

Position on page and styling

You can position the address searching and validation fields anywhere within a web page, either by placing them within the markup of an existing page or by editing the pages provided with the code. If you decide to edit the provided pages, you should remove any elements that you do not need before adding new content.

Note that nothing should be removed from the <head> sections.

Once your web pages contain the required content, you can style them by editing the qas.ic.cssstylesheet, located in the css folder. See CSS property reference for details.

JSP Advanced configuration

Country specific layout settings

Address layouts define how addresses are formatted by Address Validate. You can set the default address layout using the DEFAULT_LAYOUT setting.

If you want to override the default setting when searching in one or more specific countries, locate the following lines within the qas-ic.js file and configure them accordingly:

qas.search.DEFAULT_COUNTRY_LAYOUT_MAP = {
 "XY1" : "LayoutName1",
 "XY2" : "LayoutName2"
};

Where XY1 and XY2 are the three-character identifiers of the datasets you are licensed to use; and LayoutName1 and LayoutName2 are the names of the corresponding layouts you want to be used with these countries.

You can add as many lines to this setting as you need; one for each dataset that you are licensed to use. Any datasets that do not appear in this list will use the default layout. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

 Additional address lines

This section is relevant to address validation pages only.

Some address layouts contain more information than the standard address details. For example, names information. To find out what extra information is available, refer to your data guide(s) or contact support.

To add additional address lines (this example uses GeoCodeLayout):

  1. Open qas-ic.verification.js and locate the following section:
    qas.verification.address_field_ids =
[["add1","add2","add3","city","state","zip"],
["billadd1","billadd2","billadd3","billcity","billstate","billzip"],
["altadd1","altadd2","altadd3","altcity","altstate","altzip"]];
    Configure this section to include entries for the additional information you want to be returned. For example, to accommodate returned country,latitude and longitude information within the first fieldset element, add the following entries:
    qas.verification.address_field_ids =
[["add1","add2","add3","city","state","zip","ctry","lat","long"],
["billadd1","billadd2","billadd3","billcity","billstate","billzip"],
["altadd1","altadd2","altadd3","altcity","altstate","altzip"]];
    All entries within this section have to be unique and should represent the address elements in the order that they appear in the layout.
  2. Open verification.htm and locate the first <fieldset> section. Insert the following lines immediately before the closing </ol> tag: 
    <li style="display:none">
<input id="ctry" type="text" size="10" /></li>

<li><label>
<span class="translation">LANGUAGES.VERIFICATION.Location</span>
</label>
<input class="readonly" id="lat" size="8" readonly="true" />
<input class="readonly" id="long" size="8" readonly="true" /></li>
    Note that the ctry input element is not given a label and its <li> element has not been set to display on the page. This is to reduce duplication, as the country selection dropdown already contains this information.
    However, this input element has to exist in the HTML since address elements are always returned in the order they appear in the layout.
  3. Open one of your language files and add an entry in the VERIFICATION section for the Locationlabel:
    "Location": "Location:",
    You should repeat this step for each of your language files, translating value as necessary.
  4. Save qas-ic.verification.js, verification.htm and your language files.
  5. To test these changes, reload your address validation page by clearing your browser's cache (Ctrl+F5).
Country selection options

The country selection dropdowns automatically include entries for every dataset you are licensed to use.

Sample code also includes an additional list of all countries in the country selection dropdowns (by default, this list appears under --Other--). If a user selects a country from this list, they will be asked to enter their address manually.

You may want to remove certain countries from this additional list. For example, for an online store you might remove countries which your company does not ship products to.

To remove countries:

  1. Open the qas-ic.js file in a text editor.
  2. Locate the qas.search.ALL_COUNTRIES section and highlight the entry you want to remove. For example, to remove Tuvalu:
    },{
    "Name" : "Tuvalu",
    "ID" : "TUV"
    }    ,{
  3. Delete or comment out the in bold selection.
  4. Repeat steps 2 and 3 until you have removed all the countries you do not want to include in the country selection dropdown.
  5. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).
Cookie settings

Address Validate sample code uses cookies to store users' search preferences locally.

To customize the default settings, locate the following lines in the qas-ic.js file and configure them accordingly:

qas.lang.COOKIE_NAME = "Language_Cookie";
...
qas.search.DEFAULT_COUNTRY_COOKIE_NAME = "Country_Cookie";
qas.search.DEFAULT_COUNTRY_COOKIE_EXPIRY = X;

Where:

  • Language_Cookie is the name of the cookie which stores the user's preferred language
  • Country_Cookie is the name of the cookie which stores the user's preferred country
  • X is the number of days for which Cookie_Name will be stored on the user's machine (Language_Cookie will expire at the end of the user's browser session).

To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Address Validate settings

You can configure how the requests are made by modifying the following settings and their values, found in the qas-ic.js file:

qas.search.DEFAULT_PROMPTSET_TYPE = qas.search.PromptsetType.DEFAULT;
qas.search.DEFAULT_IS_FLATTEN = false;
qas.search.DEFAULT_THRESHOLD = 25;
qas.search.DEFAULT_TIMEOUT = 5000;
qas.search.DEFAULT_INTENSITY = qas.search.IntensityType.CLOSE;
qas.search.DEFAULT_LOCALISATION = "";
qas.search.DEFAULT_REQUEST_TAG = "";
qas.search.DEFAULT_IS_FORMATTED_ADDRESS_IN_PICKLIST = false;

PHP

Address Validate SOAP sample code is also available in C# and JSP.

PHP Sample Code

PHP Deployment

Using the code

1.  Ensure you have set up an account with us. For details go to https://www.edq.com/address-verification.

2. Download the code package (.zip) specific to your region: 

UK  USA  APAC  EMEA

3. Deploy following the steps below.

Deployment

This quick deployment will result in a functional setup which can be used as a basis for a customized address searching and validation.

1. Extract the sample code

Before you begin, ensure that:

  • you have downloaded the code package (see above) and
  • have write access to webapps on the machine you want to host the sample code pages on.

To extract the package and make the code accessible to Apache Tomcat:

  1. Navigate to the location where you saved the package.
  2. Right-click ICV2_PHP.zip and extract the contents to the wwwroot directory.

2. Download Address Validate WSDL

Due to a limitation in PHP which affects accessing WSDL documents over https protocols, Address Valdiate WSDL and its associated security document should be downloaded and stored locally. 

    1. Open the Pro On Demand WSDL in a web browser, depending on the endpoint of your regional service.
    2. Save the page as ProOnDemandService.wsdl on the local disk of the machine you are hosting sample code pages on. For example: C:\Inetpub\WSDLs\ProOnDemandService.wsdl
    3. Open the Oasis security documents: http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd
    4. Save the page as OasisSecurity.xsd to the same location as the Address Validate WSDL.
    5. Open your local copy of ProOnDemandService.wsdl in a plain text editor.
    6. Locate the <xs:import>line at the top of the <xs:schema> section and configure the schemaLocation parameter as below:
      <xs:import namespace="http://docs.oasis-open.org/wss/2004/01/oasis-
200401-wss-wssecurity-secext-1.0.xsd" schemaLocation="Local_Path"/>
      Where Local_Path is the location you saved the Oasis security document to (steps 2 and 4). For example, C:\Inetpub\WSDLs\OasisSecurity.xsd
    7. Save ProOnDemandService.wsdl.

3. Add connection details to web.xml

Before you begin, ensure that:

  • you have write access to  wwwroot on the machine you want to host the code pages on and
  • you know the username/password or token for your account.  

To get the code to communicate with your account, you have to enter your username/password or token along with the endpoint of its web service. If you would like to connect via a proxy server, you should also enter optional proxy information.

  1. Navigate to the location where you saved the package. 
    The default location is: C:\Inetpub\wwwroot/ICV2_PHP (where C is the local disk of the machine you want to host the sample code pages on).
  2. Open constants.inc in a plain text editor and configure the following parameters in the Configuration settings section:

    a) define("CONTROL_WSDL_URN", "WSDL_location");
    Where WSDL_location is the is the location you saved the the WSDL to earlier. For example: C:\Inetpub\WSDLs\ProOnDemandService.wsdl

    b) Ensure that only one authentication method is used: if you are using username and password, leave the token empty and vice versa. 
    For username and password authentication: 
    define("USERNAME", "your_username");
define("PASSWORD", "your_password");
    Where your_username is your username, and your_password is the password.

    Note that special characters are not supported, and must be replaced with the relevant Unicode reference. For example, if your password is contraseña, you should use contrase&#241;a instead.

    For token authentication:
    define("AUTH_TOKEN", "your_token");
    Where your_token is your token.

    1. If you would like to connect to the code pages via a proxy server, uncomment the following lines in Configuration settings section and configure them accordingly:

      a)
      define("CONTROL_PROXY_NAME", "PROXY_SERVER");
define("CONTROL_PROXY_PORT", 8080);
      Where PROXY_SERVER is the location of your proxy server and 8080 is the port number associated with this proxy.

      b)
       
      define("CONTROL_PROXY_LOGIN", "PROXY_USER");
define("CONTROL_PROXY_PASSWORD", "PROXY_PASSWORD");
      Where PROXY_USER is the user login for this proxy and PROXY_PASSWORD is the corresponding password.
4. Test your deployment

Check that your deployment has been successful: http://localhost/ICV2_PHP. You will be directed to the index page if the deployment has been successful:

These web pages can be used as a basis for your own deployment. Alternatively, you can integrate address searching and validation into your own pages.

PHP Integration

This section applies only if you are adding address searching and validation functionality to your existing web pages.

Copy the code in this section to the relevant areas of your HTML pages.

Integrate address capture

Add Javascript and CSS references

References to the Javascript and CSS files have to be added to all the pages you want address searching to be applied to. The following should be added to the <head> section: 

<link rel="stylesheet" href="css/qas-ic.css" type="text/css" />
<script type="text/javascript" src="js/jquery/jquery-1.6.2.min.js">
</script>
<script src="js/jquery/jquery.tmpl.min.js"></script>
<script type="text/javascript" src="js/jquery/jquery.cookie.js"></script>
<script type="text/javascript" src="js/jquery/jquery.showLoading.min.js">
</script>
<script type="text/javascript" src="js/qas-ic.js"></script>
<script type ="text/javascript" src="js/qas-ic.addresscapture.js">
</script> 

If you are modifying a page that does not exist in the same folder as the css and js folders supplied with the sample code, you should modify the paths in the above code as appropriate.

 Insert address searching fields

Input and output fields are the basis of address searching and validation. Address information is provided by the user via input fields, passed to Address Validation and then displayed via the output fields for confirmation.

  1. Insert the following Javascript at the bottom of the <head> section: 
    <script type="text/javascript">
$(function(){ 
qas.addresscapture.Initialize("div#QAS_Container");
}); 
</script>
    This will populate the address searching section while the page loads.
  2. Insert the following <div> element within the <body> section:
    <div id="QAS_Container"></div>
    This element will be dynamically populated with the input fields required to collect information from the user.
    You should place this element in the area of the page you would like the input fields to appear. For example, if you were adding address searching to the ordering page of an online shop, you might place this <div> between the first/last name and credit card number/expiry date fields. 

    3. Save the changes and load the web page in a browser to test the integration. 

Integrate address verification

Add Javascript and CSS references

References to the Javascript and CSS files have to be added to all the pages you want to address vaildation to be applied to. The following should be added to the <head> section:

<link rel="stylesheet" href="css/qas-ic.css" type="text/css" />
<script type="text/javascript" src="js/jquery/jquery-1.6.2.min.js">
</script>
<script type="text/javascript" src="js/jquery/jquery-ui-1.8.14.custom.min.js"></script>
<script type="text/javascript" src="js/jquery/jquery.cookie.js">
</script>
<script type="text/javascript" src="js/qas-ic.js"></script>
<script type="text/javascript" src="js/qas-ic.verification.js"></script>

If you are modifying a page that does not exist in the same folder as the css  and js folders supplied with the sample code, you should modify the paths in the above code as appropriate. 

Insert address validation fields

Input and output fields are the basis of address searching and validation. Address information is provided by the user via input fields, passed to Address Validation and then displayed via the output fields for confirmation.

  1. Insert the following <fieldset> element within the <body> section:
<fieldset>
<legend><span class="translation">
LANGUAGES.VERIFICATION.MailingAddress</span></legend>
<ol><li>
<label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress1</span>
</label><input id='add1' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress2</span>
</label><input id='add2' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputAddress3</span>
</label><input id='add3' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputCity</span>
</label><input id='city' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputState</span>
</label><input id='state' type='text' size="30" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputZip</span>
</label><input id='zip' type='text' size="10" /></li><li><label>
<span class="translation">LANGUAGES.VERIFICATION.InputCountry</span>
</label><select id='country' class="countrySelector"></select>
</li></ol>
</fieldset>

You should place this element in the area of the page you would like it to appear. For example, if you are adding address validation to the contact details page of a customer management system, you might place this <fieldset> between the first/last name and the telephone number/email address fields.

  1. You can add more <fieldset> elements if required. By default, your address validation pages can contain up to 3 of these elements (although you can add more later).

    To enable the sample code to distinguish between them, you should make the following changes to any subsequent fieldsets that you add:

    • MailingAddress should become BillingAddress in a second fieldset or AlternateAddress in a third

    • All address element IDs (such as add1) should be preceded by bill in a second fieldset or alt in a third

    See verification.htm (supplied with the sample code) for an example of an sample which makes use of multiple fieldsets.
  2. Insert the following <input> elements below the <fieldset> element(s):
    <input id='subButton' name='subButton' class='translation'
type='button' value='LANGUAGES.VERIFICATION.ButtonSubmit'
onclick='qas.verification.QAS_Verify()' />

<input id='clear' name='subButton' class='translation' type='submit'
value='LANGUAGES.VERIFICATION.ButtonClear' onclick='clearforms()' />
    This will place buttons below the address entry form(s), allowing the user to submit their address information to Address Validate or clear all entries.

  3. Insert the following Javascript at the bottom of the <body> section:
    <script type="text/javascript">
$(document).ready()
{qas.verification.Init();
};
</script>
    This will allow address validation to take place, once the page has loaded.

  5. Save the changes and load the web page in a browser to test the integration.

PHP Configuration

Once integrated, you can configure the pages to fully incorporate them into your existing website structure. You can add and remove below elements as necessary.

Modify the following three areas to customize your setup:

1. Set a default country and address layout

Address Validate code sets all country selection dropdowns to a default value on user's first visit. On subsequent visits, these dropdowns default to each user's last selected country (see cookie settings below for details).

To modify the default settings, open qas-ic.js from the js folder.

    1. To configure which country will be selected by default on user's first visit, locate the following line and configure it accordingly:
      qas.search.DEFAULT_COUNTRY_ID = "XYZ";
      Where XYZ is the country code. For example, using the USA code will enable Address Validate to search for addresses within United States by default.
      Note that you have to be licensed for each dataset you want to use. To remove entries from the country dropdowns see country selection options below.

    2. You can also configure the default address layout that Address Validate will use when returning addresses. To do this, locate the following line and configure it accordingly:
      qas.search.DEFAULT_LAYOUT = "LayoutName";
      Where LayoutName is the name of the layout you want to use by default. In most cases, this should be set to Database Layout which exists for every country.
      You can also set specific layouts for Address Validate to use when returning addresses for individual countries. See country specific layout settings below for details.

    3. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).
2. Set appropriate language options

If you have users from multiple countries, you should set up the appropriate language files.

You can have one language file for each language. These files are used to ensure that the prompts and messages are displayed in the appropriate language.

Creating a new language file

The sample code is provided with two language files: UK English and US English. To create a file for another language:

    1. Navigate to the location you extracted the code package to. In most cases, this will be: C:\Program Files\Apache Software Foundation\Tomcat X\webapps (where X is the version of Apache Tomcat you want to use).
    2. Navigate to \js\lang.
    3. Make a copy of one of the Javascript files in the lang folder and name it appropriately. For example, a French language file might be called fr.js.
    4. Open qas-ic.js.
    5. In the qas.lang.Type and qas.lang.DisplayMapping sections add entries to include the new language file:
      qas.lang.Type = {
EN_UK : "en-gb",
EN_US : "en-us",
FR : "fr" };
qas.lang.DisplayMapping = {
EN_UK : "English (UK)",
EN_US : "English (US)",
FR : "Français" };
      Where FR is an internal reference for the language file, fr is its filename (the file extension is not required), and Français is how you would like this option to appear in the code pages.
      Note that the penultimate entry in each list has to end with a comma (,).
    6. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Editing a language file

To edit the prompts and messages in a language file:

    1. Open the language file you want to edit. For example, to translate messages for French users, open the fr.js file.
    2. Scroll down to the section you want to make changes to. The language files are made up of five sections:

      • INDEX and MATRIX sections control the text found on the index and comparison pages. In most cases, you will not need to edit these.

      • COMMON section controls text shared by all pages.

      • ADDRESS_CAPTURE and VERIFICATION sections control text found on the address searching and validation pages, respectively.
    3. Locate the message you would like to change and edit its value (each message has a name and a value, the name shouldn't be changed). 

      For example, to translate the first message in the address searching process for French users, you should locate this line in the ADDRESS_CAPTURE section: "PleaseSelectACountryOrDatamap" : "To begin, select your country.",

      And change it to: "PleaseSelectACountryOrDatamap" : "Pour commencer, sélectionnez votre pays.",
    4. Repeat step 3 for other messages as necessary.
    5. You can also link directly to a regional Experian Data Quality support site by editing the last two letters of the SupportLink line in the COMMON section.

      For example, editing the line below will map the support link on the sample Code pages to the French support site: "SupportLink": "http://support.qas.com/?sc=fr",

      Available options are:
      • au (Australia)
      • ca (Canada)
      • ie (Ireland)
      • nl (Netherlands)
      • nz (New Zealand)
      • sg (Singapore)
      • uk (United Kingdom)
      • us (United States)
    6. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Creating a new flag

Each language file supplied with the sample code is accompanied by an image of the relevant flag.

To create an image for your new language file:

    1. Navigate to img\flags.
    2. Make a copy of one of the .png files in the flags folder and rename it accordingly. For example, fr.png to accompany the French language file.
    3. Open the file with any photo editor and modify.
    4. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).
3. Prepare your web pages for live deployment

This section offers steps that should be taken before publishing your deployment to a live website.

Debug mode

While testing your deployment, you may receive non-critical error messages which you do not want to display to the end users.

For example, searching with too few details (e.g. house number only) will result in an error message but interaction will still be possible. To prevent this type of error message from displaying to your end users, locate the following line in the qas-ic.js file and set to false:

qas.search.DISPLAY_ERROR = false;

Debug may alert you to timeout issues affecting your deployment.

Position on page and styling

You can position the address searching and validation fields anywhere within a web page, either by placing them within the markup of an existing page or by editing the pages provided with the code. If you decide to edit the provided pages, you should remove any elements that you do not need before adding new content.

Note that nothing should be removed from the <head> sections.

Once your web pages contain the required content, you can style them by editing the qas.ic.cssstylesheet, located in the css folder. See CSS property reference for details.

PHP Advanced configuration

Configuring prerequisites

To use the PHP sample code, FastCGI has to be installed on your system and the SOAP and OpenSSL PHP extensions have to be enabled.

Install FastCGI

  1. Open IIS Manager from the Control Panel.
  2. If you are using IIS 7 or later:
    a) Select the server that you will be hosting the code pages on (e.g. WIN2008). 
    b) Double-click Handler Mappings in the Workspace pane.
    c) Scroll down until you see *.php in the Path column. The corresponding entry in the Handler column should be FastCGIModule.
  3. If you are using IIS 5.1 or 6:
    a) Right-click on the website that you will be hosting the code pages from (e.g. Default Web Site) and select Properties.
    b) In the Properties dialog select the Home Directory tab and click Configuration...
    c) In the Application Configuration dialog scroll down until you see the .php extension. The executable path should point to a fcgiext.dll.
  4. If you can't see the .php entry, the Handler or executable path does not correspond to FastCGI, install the FastCGI module from http://www.iis.net/download/FastCGI


Enable SOAP and OpenSSL extensions

  1. Navigate to your PHP installation. For example C:\Program Files\PHP.
  2. Open PHP.ini in a plain text editor.
  3. Locate the following lines and ensure that they are not preceded by a semicolon (;): 
    extension=php_soap.dll
...
extension=php_openssl.dll


Configure IIS to use PHP

  1. Open IIS and select the server you will be hosting the code pages on, as above.
  2. Double-click on Handler Mappings in the Workspace pane.
  3. Select Add Module Mapping from the Actions pane.
  4. In the Add Module Mapping dialog fill in the details as follows:
    • Request path: *.php
    • Module: FastCgiModule
    • Executable: Directory\php-cgi.exe (Where Directory is the location of your PHP installation. E.g. C:\Program Files\PHP)
    • Name: PHP5
  5. Click OK to save changes. 

 

Country specific layout settings

Address layouts define how addresses are formatted by Address Validate. You can set the default address layout using the DEFAULT_LAYOUT setting.

If you want to override the default setting when searching in one or more specific countries, locate the following lines within the qas-ic.js file and configure them accordingly:

qas.search.DEFAULT_COUNTRY_LAYOUT_MAP = {
 "XY1" : "LayoutName1",
 "XY2" : "LayoutName2"
};

Where XY1 and XY2 are the three-character identifiers of the datasets you are licensed to use; and LayoutName1 and LayoutName2 are the names of the corresponding layouts you want to be used with these countries.

You can add as many lines to this setting as you need; one for each dataset that you are licensed to use. Any datasets that do not appear in this list will use the default layout. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

 Additional address lines

This section is relevant to address validation pages only.

Some address layouts contain more information than the standard address details. For example, names information. To find out what extra information is available, refer to your data guide(s) or contact support.

To add additional address lines (this example uses GeoCodeLayout):

  1. Open qas-ic.verification.js and locate the following section:
    qas.verification.address_field_ids =
[["add1","add2","add3","city","state","zip"],
["billadd1","billadd2","billadd3","billcity","billstate","billzip"],
["altadd1","altadd2","altadd3","altcity","altstate","altzip"]];
    Configure this section to include entries for the additional information you want to be returned. For example, to accommodate returned country,latitude and longitude information within the first fieldset element, add the following entries:
    qas.verification.address_field_ids =
[["add1","add2","add3","city","state","zip","ctry","lat","long"],
["billadd1","billadd2","billadd3","billcity","billstate","billzip"],
["altadd1","altadd2","altadd3","altcity","altstate","altzip"]];
    All entries within this section have to be unique and should represent the address elements in the order that they appear in the layout.
  2. Open verification.htm and locate the first <fieldset> section. Insert the following lines immediately before the closing </ol> tag: 
    <li style="display:none">
<input id="ctry" type="text" size="10" /></li>

<li><label>
<span class="translation">LANGUAGES.VERIFICATION.Location</span>
</label>
<input class="readonly" id="lat" size="8" readonly="true" />
<input class="readonly" id="long" size="8" readonly="true" /></li>
    Note that the ctry input element is not given a label and its <li> element has not been set to display on the page. This is to reduce duplication, as the country selection dropdown already contains this information.
    However, this input element has to exist in the HTML since address elements are always returned in the order they appear in the layout.
  3. Open one of your language files and add an entry in the VERIFICATION section for the Locationlabel:
    "Location": "Location:",
    You should repeat this step for each of your language files, translating value as necessary.
  4. Save qas-ic.verification.js, verification.htm and your language files.
  5. To test these changes, reload your address validation page by clearing your browser's cache (Ctrl+F5).

Country selection options

The country selection dropdowns automatically include entries for every dataset you are licensed to use.

Sample code also includes an additional list of all countries in the country selection dropdowns (by default, this list appears under --Other--). If a user selects a country from this list, they will be asked to enter their address manually.

You may want to remove certain countries from this additional list. For example, for an online store you might remove countries which your company does not ship products to.

To remove countries:

  1. Open the qas-ic.js file in a text editor.
  2. Locate the qas.search.ALL_COUNTRIES section and highlight the entry you want to remove. For example, to remove Tuvalu:
    },{
    "Name" : "Tuvalu",
    "ID" : "TUV"
    }    ,{
  3. Delete or comment out the in bold selection.
  4. Repeat steps 2 and 3 until you have removed all the countries you do not want to include in the country selection dropdown.
  5. To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Cookie settings

Address Validate sample code uses cookies to store users' search preferences locally.

To customize the default settings, locate the following lines in the qas-ic.js file and configure them accordingly:

qas.lang.COOKIE_NAME = "Language_Cookie";
...
qas.search.DEFAULT_COUNTRY_COOKIE_NAME = "Country_Cookie";
qas.search.DEFAULT_COUNTRY_COOKIE_EXPIRY = X;

Where:

  • Language_Cookie is the name of the cookie which stores the user's preferred language
  • Country_Cookie is the name of the cookie which stores the user's preferred country
  • X is the number of days for which Cookie_Name will be stored on the user's machine (Language_Cookie will expire at the end of the user's browser session).

To test these changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Address Validate settings

You can configure how the requests are made by modifying the following settings and their values, found in the qas-ic.js file:

qas.search.DEFAULT_PROMPTSET_TYPE = qas.search.PromptsetType.DEFAULT;
qas.search.DEFAULT_IS_FLATTEN = false;
qas.search.DEFAULT_THRESHOLD = 25;
qas.search.DEFAULT_TIMEOUT = 5000;
qas.search.DEFAULT_INTENSITY = qas.search.IntensityType.CLOSE;
qas.search.DEFAULT_LOCALISATION = "";
qas.search.DEFAULT_REQUEST_TAG = "";
qas.search.DEFAULT_IS_FORMATTED_ADDRESS_IN_PICKLIST = false;

CSS Property Reference

Below is a non-exhaustive list of CSS properties used by Address Validate SOAP sample code. You can edit these properties in the qac-ic.css stylesheet to adapt the pages to suit your requirements.

Template section

In most cases you will not need to modify properties found in the template section, with two exceptions:

.qas-container Controls the size of the container which holds the sample code elements.
.qas-content Controls the appearance of the content area.
General section

If your sample code appears on a page which references your own stylesheet, you may want to remove this section from qac-ic.css to avoid conflicts.

body Allows you to set the fonts that control the general appearance of the page.
h1, h2, h3 Controls the size, appearance, and spacing of the various headings.
a, a:hover Controls the appearance of dormant and active hyperlinks.
Tables section

In most cases you will not need to modify properties found in the tables section, with two exceptions:

table Controls the appearance of tables, allowing you to modify the spacing of containers.
tr, td These classes do not exist by default in the sample code, but you can add them to control the appearance of all table rows or cells.
Integration pages section

In most cases you will not need to modify properties found in the integration pages section, with one exception:

input.readonly Controls the appearance of read-only input elements, such as the returned country.
Fieldset section

The fieldset section controls the appearance of elements in the address validation page only.

fieldset Controls the size and appearance of the fieldsets found on the address validation page.
label Controls the alignment and appearance of the field labels within fieldsets (e.g. "City", "ZIP Code").
.first Controls the alignment and position of the first fieldset to appear on a page.
legend Controls the appearance of the legend for each fieldset (e.g. "Mailing Address", "Billing Address").
fieldset ol Controls the format and alignment of fields within each fieldset, allowing you to adjust spacing to suit your pages.
fieldset li Controls the alignment and appearance of individual list items within a fieldset (usually address fields).
.countrySelector Controls the size and appearance of the country selection dropdown in the address validation pages.
fieldset input This class does not exist by default in the sample code, but you can add it to control the appearance of all input elements in the address validation page.
Showloading section

The showloading section controls the appearance of the loading indicator in the address searching page.

.loadingindicator Controls the size, positioning and graphic used by the loading indicator on the address searching page.
.loadingindicatoroverlay Controls the appearance and position of the overlay which grays out the input areas when the address searching page is loading.
JQuery CSS section

The JQuery CSS section controls the appearance of the address validation pop up dialog.

.ui-helperclearfix Controls the alignment of title boxes, and can be used to control their size.
.ui-widgetoverlay Controls the appearance and position of the overlay which grays out the whole page when the address validation pop up is active.
.ui-widget Controls the font and size of text.
.ui-widgetcontent Controls background, border and font colors.
.ui-widgetcontent a Controls the appearance of links (e.g. "[Edit]").
.ui-widgetheader Controls the appearance of title boxes (e.g. "Verify your address details").
.ui-statedefault Controls the appearance of buttons (e.g. "Use suggested address").
.ui-statehighlight Controls the appearance of the message boxes (e.g. "We think that your address may be incorrect or incomplete").
Other sections

The Index Table and Comparison Matrix sections are used by the sample code but are unlikely to be needed in live deployments. In most cases you will not need to edit the Developer or Verification Pop up sections either but these should not be removed from the stylesheet.

Troubleshooting

Authentication

How do I switch to token authentication?

You don't need to remove your username / password credentials from the code to use token authentication. 

The token will overwrite any other credentials (username/password or SAML header).

 To switch to token authentication:

 1. Retrieve your token from Self Service Portal > Licenses.
     If you don't have one yet, go to Self Service Portal > Licenses, click Add a Token and enter the required details.

  2. Enter your token as the value for "auth-token" field under the HTTP Header. 

Error Messages

SSL certificate errors

Your SSL certificate might have expired. To manually update your deployment:
  1. Download the update files.
  2. Extract the files.
  3. Install Root.crt in the Trusted Root Certificates Authorities Store.
  4. Install Intermediate1.crt and Intermediate2.crt  in the Intermediate Certificate Authorities Store.
  5. Install api.experianmarketingservices.com.cer* in the Personal Certificate Store.

*Applies to ws2/ws3.ondemand.qas.com as well, since they are listed in this certificate as SANs (Subject Alternate Names).

For further help contact support.  

QAS On Demand server not available

 Ensure that the security token you've entered is valid. If that doesn't work, contact support.

Timeout error

 You should increase the default timeout settings. To do this, update the following lines in the qas-ic.js file: 
qas.search.DEFAULT_AJAX_TIMEOUT = 10000;
...
qas.search.DEFAULT_TIMEOUT = 10000;

Where 10000 is the time in milliseconds. Increase this by 1000 until the timeout issues are resolved.

Values of 0 will prevent requests from timing out but may lead to severely extended waiting times. 

  • DEFAULT_AJAX_TIMEOUT applies to AJAX API calls. AJAX timeouts may occur due to slow connections between a user's browser and your web server, or your web server and the Address Validate web service.
  • DEFAULT_TIMEOUT applies to the Address Validate web service itself. High settings (of more than 15000) increase the chance of a matched address being found, but also increase waiting time for users. This value should never be higher than DEFAULT_AJAX_TIMEOUT.

To test your changes, reload your deployment by clearing your browser's cache (Ctrl+F5).

Non-responsive JSP

 If the code is unresponsive or is stuck on loading, you may have to increase the amount of memory allocated to it:
  1. Run tomcatXw.exe from Apache Tomcat's \bin directory. The default location is
    C:\Program Files\Apache Software Foundation\Tomcat X\bin (where X is the version of Apache Tomcat you're using).
  2. In the General tab, click Stop to temporarily stop the Apache Tomcat service.
  3. In the Java tab, increase the Initial memory pool and Maximum memory pool to 512 MB each.
  4. Return to the General tab and Start the Apache Tomcat service.
  5. Click OK to close the dialog.

To test your changes, reload your deployment by clearing your browser's cache (Ctrl+F5).