Skip to main content

Address Validate SOAP Sample Code

Overview

Address Validate API SOAP sample code provides best practice integration of our global address search and verification 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 GBRUSA 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

RegionSOAP EndpointPortProtocol
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

RegionSOAP EndpointPortProtocol
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

RegionSOAP EndpointPortProtocol
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

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

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:

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

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.

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:

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

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.

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:

PHP Advanced configuration

Configuring prerequisites

 

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

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

Copyright ©, 2014-2017. All rights reserved.