Address Validate API SOAP sample code provides best practice integration of our global address search and verification functionality.
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.
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 |
|
|
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 |
|
|
USA | https://ws2.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx | ||
APAC | https://ws3.ondemand.qas.com/ProWebIntermediary/OnDemandProWebIntermediary.asmx |
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 |
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. |
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 |
1. Ensure you have set up an account with us. For details go to https://www.edq.com/address-verification
3. Deploy following the steps below.
This quick deployment will result in a functional setup which can be used as a basis for a customized address searching and validation.
Before you begin, ensure that:
To extract the package and make the code accessible to IIS:
Before you begin, ensure that:
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.
<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.
<add key="Experian.Qas.Capture.OnDemandAuthToken" value="ONDEMAND_AUTH-TOKEN"/>Where ONDEMAND_AUTH-TOKEN is your token.
<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.
Before you begin, ensure that:
Configuring IIS to publish the code will make the address searching and validating pages accessible to you and other users:
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.
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.
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.
<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.
<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.
<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.
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.
<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.
<fieldset>
elements if required. By default, your address validation pages can contain up to 3 of these elements (although you can add more later).fieldsets
that you add:fieldset
or AlternateAddress in a thirdadd1
) should be preceded by bill in a second fieldset
or alt in a third<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.
<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.
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:
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.
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.qas.search.DEFAULT_LAYOUT = "LayoutName";
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.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:
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.,
).Editing a language file
To edit the prompts and messages in a language file:
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.ADDRESS_CAPTURE
section: "PleaseSelectACountryOrDatamap" : "To begin, select your country.",
"PleaseSelectACountryOrDatamap" : "Pour commencer, sélectionnez votre pays.",
SupportLink
line in the COMMON
section."SupportLink": "http://support.qas.com/?sc=fr",
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:
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.
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).
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):
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.
<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.VERIFICATION
section for the Location
label:"Location": "Location:",
value
as necessary.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:
qas.search.ALL_COUNTRIES
section and highlight the entry you want to remove. For example, to remove Tuvalu: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 languageCountry_Cookie
is the name of the cookie which stores the user's preferred countryX
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).
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;
1. Ensure you have set up an account with us. For details go to https://www.edq.com/address-verification
3. Deploy following the steps below.
This quick deployment will result in a functional setup which can be used as a basis for a customized address searching and validation.
Before you begin, ensure that:
To extract the package and make the code accessible to Apache Tomcat:
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:
Once Apache Tomcat has restarted, the package will be extracted to a folder named ICV2_JSP within the webapps directory.
Before you begin, ensure that:
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.
<!-- 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.
<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.
<context-param> <param-name>AuthenticationAuthToken</param-name> <param-value>token</param-value> </context-param>Where token is your token.
<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.
<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.
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.
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.
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.
<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.
<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.
<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.
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.
<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.
<fieldset>
elements if required. By default, your address validation pages can contain up to 3 of these elements (although you can add more later).fieldsets
that you add:fieldset
or AlternateAddress in a thirdadd1
) should be preceded by bill in a second fieldset
or alt in a third<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.
<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.
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:
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.
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.qas.search.DEFAULT_LAYOUT = "LayoutName";
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.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:
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.,
).Editing a language file
To edit the prompts and messages in a language file:
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.ADDRESS_CAPTURE
section: "PleaseSelectACountryOrDatamap" : "To begin, select your country.",
"PleaseSelectACountryOrDatamap" : "Pour commencer, sélectionnez votre pays.",
SupportLink
line in the COMMON
section."SupportLink": "http://support.qas.com/?sc=fr",
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:
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.
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).
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):
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.
<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.VERIFICATION
section for the Location
label:"Location": "Location:",
value
as necessary.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:
qas.search.ALL_COUNTRIES
section and highlight the entry you want to remove. For example, to remove Tuvalu: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 languageCountry_Cookie
is the name of the cookie which stores the user's preferred countryX
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).
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;
1. Ensure you have set up an account with us. For details go to https://www.edq.com/address-verification.
3. Deploy following the steps below.
This quick deployment will result in a functional setup which can be used as a basis for a customized address searching and validation.
Before you begin, ensure that:
To extract the package and make the code accessible to Apache Tomcat:
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.
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
Before you begin, ensure that:
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.
define("USERNAME", "your_username"); define("PASSWORD", "your_password");Where your_username is your username, and your_password is the password.
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.
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.
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.
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.
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.
<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.
<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.
<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.
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.
<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.
<fieldset>
elements if required. By default, your address validation pages can contain up to 3 of these elements (although you can add more later).fieldsets
that you add:fieldset
or AlternateAddress in a thirdadd1
) should be preceded by bill in a second fieldset
or alt in a third<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.
<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.
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:
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.
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.qas.search.DEFAULT_LAYOUT = "LayoutName";
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.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:
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.,
).Editing a language file
To edit the prompts and messages in a language file:
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.ADDRESS_CAPTURE
section: "PleaseSelectACountryOrDatamap" : "To begin, select your country.",
"PleaseSelectACountryOrDatamap" : "Pour commencer, sélectionnez votre pays.",
SupportLink
line in the COMMON
section."SupportLink": "http://support.qas.com/?sc=fr",
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:
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.
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
Enable SOAP and OpenSSL extensions
extension=php_soap.dll ... extension=php_openssl.dll
Configure IIS to use PHP
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).
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):
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.
<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.VERIFICATION
section for the Location
label:"Location": "Location:",
value
as necessary.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:
qas.search.ALL_COUNTRIES
section and highlight the entry you want to remove. For example, to remove Tuvalu: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 languageCountry_Cookie
is the name of the cookie which stores the user's preferred countryX
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).
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;
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.
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. |
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. |
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. |
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. |
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. |
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. |
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"). |
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.
How do I switch to token authentication?