- To use this functionality you will need to buy an Address Lookup click bundle from the Shop located in our Portal. Register for the Portal here.
- A generated service Authorisation Code is required using the service Authorisation Code Generator and a token username and password you created in registering.
- Download, unzip, and extract the JavaScript Client sample code to an appropriate directory in a web server (for HTML or PHP).
- Add the Authorisation Code from above (in the HPW.FindAddress() auth section).
- Add the MAF ID of a dataset available to the account referenced in the HPW.FindAddress() dataset section.
- Start up the servlet container publishing the sample web page giving sight of the standard functionality from any web browser.
Overview
- Provides address capture capability to a web page.
- Does not require the installation of any files (as these can be referenced on the hosted service).
- Sample code download provides a sample webpage (for HTML or PHP) illustrating the standard functionality. This can be tweaked and adapted to suit the need.
Quick Start
Basics
How do I install JavaScript Client?
In the head of your web page, add this line…
<link rel="stylesheet" href="https://cloud.hopewiser.com/jsclient2/hpw-jsclient2.css" />
Before the </body> closing tag of your web page, add these lines…
<script src="https://cloud.hopewiser.com/jsclient2/jquery.min.js"></script> <script src="https://cloud.hopewiser.com/jsclient2/bootstrap.min.js"></script> <script src="https://cloud.hopewiser.com/jsclient2/json2.min.js"></script> <script src="https://cloud.hopewiser.com/jsclient2/hpw-jsclient2.min.js"></script>
Replace ‘https://cloud.hopewiser.com/jsclient2’ with the relative path of the folder if you chose to install these files on your own web server in place of using the Hopewiser hosted resources. Details of how to obtain local JavaScript components required can be located in the Customisation section “How do I install AutoComplete JavaScript Client service files locally?”.
If your web site is already using jQuery, Bootstrap or json2, you may be able to omit the applicable lines or reference your existing installation as necessary.
Add a button with the following attributes to your web page:
<button type="button" data-toggle="modal" data-target="#hpwModal" data-backdrop="static" onclick="btnFindAddress_onclick()">Find Address</button>
In the <head> of your web page, add a script to handle the button’s onclick event. In the button’s onclick handler, call the HPW.FindAddress() function:
<script>
function btnFindAddress_onclick() {
HPW.FindAddress({...});
}
</script>
The HPW.FindAddress() function takes a JavaScript object containing:
- Your authorisation code
- The dataset to look up against
- The HTML ID of your input field
- An object containing the HTML IDs of your output fields
- Optionally, parameters to indicate if you want to include the County or any Organisation Name within the matched address, and whether you want the town in upper or lower case.
| Optional Parameter | Description |
|---|---|
| IncludeCounty | Select when the county should be included within the formatted address label. Allowed values are Always, Never or AsRequired (the default). The value AsRequired will only include the county when appropriate, for example when it meets PTT guidelines or when it is required to disambiguate UK town names. |
| ReserveOrganisationLine | Select the position of the organisation within the formatted label. Allowed values are AsRequired (the default), Always or Never. The value AsRequired includes the organisation within the address label following standard formatting rules. The value Always reserves the first line of the formatted address label for the organisation and forces it to be output on a separate line. If there is no organisation then the first line will be empty. The value Never removes the organisation from the formatted address label. |
| TownFormat | Select the required town format. Allowed values are Uppercase (the default) or Lowercase. |
If your web page has separate address fields
Specify their HTML IDs in the output object, e.g.
function btnFindAddress_onclick() {
HPW.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-rm-paf-mr", // required
input: "txtInput", // required
output: {
line1: "txtLine1", // required
line2: "txtLine2", // required
line3: "txtLine3", // optional
line4: "", // optional
town: "txtTown", // required
county: "txtCounty", // optional
postcode: "txtPostcode", // required
country: "txtCountry" // optional
},
IncludeCounty: "AsRequired", // optional (default = "AsRequired")
ReserveOrganisationLine: "AsRequired", // optional (default = "AsRequired")
TownFormat: "Uppercase" // optional (default = "Uppercase")
});
}
If your web page has a single multi-line address field
Specify its HTML ID against each address line you want to be returned, e.g.
function btnFindAddress_onclick() {
HPW.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-rm-paf-mr", // required
input: "txtInput", // required
output: {
line1: "txtAddress", // required
line2: "txtAddress", // required
line3: "txtAddress", // optional
line4: "", // optional
town: "txtAddress", // required
county: "txtAddress", // optional
postcode: "txtAddress", // required
country: "txtAddress" // optional
},
IncludeCounty: "AsRequired", // optional (default = "AsRequired")
ReserveOrganisationLine: "AsRequired", // optional (default = "AsRequired")
TownFormat: "Uppercase" // optional (default = "Uppercase")
});
}
If your web page has a mixture of multi-line and individual address fields
For each address line you want, specify the HTML ID of the field you want it returned to, e.g.
function btnFindAddress_onclick() {
HPW.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-rm-paf-mr", // required
input: "txtInput", // required
output: {
line1: "txtStreet", // required
line2: "txtStreet", // required
line3: "txtStreet", // optional
line4: "", // optional
town: "txtTown", // required
county: "txtCounty", // optional
postcode: "txtPostcode", // required
country: "txtCountry" // optional
},
IncludeCounty: "AsRequired", // optional (default = "AsRequired")
ReserveOrganisationLine: "AsRequired", // optional (default = "AsRequired")
TownFormat: "Uppercase" // optional (default = "Uppercase")
});
}
Replace yourAuthCode with your authorisation code and the example HTML IDs with your actual HTML IDs. If you do not specify an ID for line3 or line4, the returned address will be formatted to fit the available lines. The county ID should be used in conjunction with the IncludeCounty parameter, and must be specified when the county is required. If you do not specify an ID for country, then it will be omitted. The input field does not have to be a separate field; it can be one of the output fields, in which case it would most likely be the postcode field.
How do I lookup an address?
Type a postcode into your input field then click the Find Address button. Select an address from the list of possible matches then click the Select button. Repeat if necessary until you have the address you want.
How do I troubleshoot my installation?
NOTE: your web page must be served up via a web server, using the http:// or https:// protocol. The JavaScript Client will not work if you open your web page directly from the file system, using the file:// protocol.
You can set the Debug flag found in the autocomplete-javascript-client sample page to true. This will display a message box to the user if there are any missing or invalid fields
IE Compatibility Modes
The JavaScript Client uses Bootstrap, which is not supported in the old Internet Explorer compatibility modes. To be sure you’re using the latest rendering mode for IE, consider including the appropriate <meta> tag in your page:
<meta http-equiv="X-UA-Compatible" content="IE=edge">
Confirm the document mode by opening the debugging tools: press F12 and check the “Document Mode”.
Customisations
How do I install JavaScript Client service files locally?
You do not have to download anything to use the JavaScript Client because your web page can reference the necessary files on our servers. However, if you’d like to download the client files and install them on your own web server, you can. Download the JavaScript Client files from here, uncompress the downloaded JavaScriptClient.zip file and then upload the extracted files to a suitable location on your web server.
How do I customise an address label?
Variations in the appearance of an output address label are achieved, in the JavaScript Client solution, via three optional parameters in the FindAddress() function call – IncludeCounty, ReserveOrganisationLine, and TownFormat. For full details on each, please refer to the How do I install JavaScript Client? in the Basics section.
How can I return individual address elements?
This can be useful if, for example, you need delivery point information or if you want premise details separately from the street information. In the JavaScript object that you pass in to the HPW.FindAddress() function, you can include an optional detail object containing the names of the address elements that you want, and the HTML IDs of the fields that you want the values returned to. For example:
function btnFindAddress_onclick() {
HPW.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-rm-paf-mr", // required
input: "txtInput", // required
output: {
line1: "txtLine1", // required
line2: "txtLine2", // required
line3: "txtLine3", // optional
line4: "", // optional
town: "txtTown", // required
county: "txtCounty", // optional
postcode: "txtPostcode", // required
country: "txtCountry" // optional
},
detail: { // optional
Premise: "txtPremise",
UDPRN: "txtUdprn"
},
IncludeCounty: "AsRequired", // optional (default = "AsRequired")
ReserveOrganisationLine: "AsRequired", // optional (default = "NAsRequired")
TownFormat: "Uppercase" // optional (default = "Uppercase")
});
}
How can I return ‘extra data’ fields?
Depending on your dataset, you may be able to return extra data. In the JavaScript object that you pass in to the HPW.FindAddress() function, you can include an optional extra object containing the names of the extra data elements that you want, and the HTML IDs of the fields that you want the values returned to. For example:
function btnFindAddress_onclick() {
HPW.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-nspd-paf", // required
input: "txtInput", // required
output: {
line1: "txtLine1", // required
line2: "txtLine2", // required
line3: "txtLine3", // optional
line4: "", // optional
town: "txtTown", // required
county: "txtCounty", // optional
postcode: "txtPostcode", // required
country: "txtCountry" // optional
},
extra: { // optional
Extra_Grid_Latitude: "txtLatitude",
Extra_Grid_Longitude: "txtLongitude"
},
IncludeCounty: "AsRequired", // optional (default = "AsRequired")
ReserveOrganisationLine: "AsRequired", // optional (default = "AsRequired")
TownFormat: "Uppercase" // optional (default = "Uppercase")
});
}
The available extra data elements will depend on your dataset. To view the available extra data elements, visit:
https://cloud.hopewiser.com/atlaslive/json/dataset?q=listoutputs
or
https://cloud.hopewiser.com/atlaslive/xml/dataset?q=listoutputs
Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com/atlaslive/json/uk-nspd-paf?q=listoutputs or https://cloud.hopewiser.com/atlaslive/xml/uk-nspd-paf?q=listoutputs. Enter your User name and Password when prompted. The available extra data elements are those Outputs that have a TableName of Extra Data.
How can I call a function given a successful address lookup?
This can be useful if, for example, you need to enable a button or if you want to display the address on a map. In the JavaScript object that you pass in to the HPW.FindAddress() function, you can include an optional success attribute containing the function that you want to call. For example:
function btnFindAddress_onclick() {
HPW.FindAddress({
auth: "yourAuthCode", // required
dataset: "uk-rm-paf-mr", // required
input: "txtInput", // required
output: {
line1: "txtLine1", // required
line2: "txtLine2", // required
line3: "txtLine3", // optional
line4: "", // optional
town: "txtTown", // required
county: "txtCounty", // optional
postcode: "txtPostcode", // required
country: "txtCountry" // optional
},
success: EnableButton, // optional
IncludeCounty: "AsRequired", // optional (default = "AsRequired")
ReserveOrganisationLine: "AsRequired", // optional (default = "AsRequired")
TownFormat: "Uppercase" // optional (default = "Uppercase")
});
}
function EnableButton() {
document.getElementById("btnNext").disabled = false;
}
How can I style the user interface?
The Select and Cancel buttons have a class of btn. You can define this class in your CSS or you can use jQuery to add your own class:
$(".btn").addClass("myButtonClass");
The Select button has a class of btn-primary and the Cancel button has a class of btn-default. If you want to style the buttons individually, you can define these classes in your CSS or you can use jQuery to add your own classes:
$(".btn-primary").addClass("myPrimaryButtonClass");
$(".btn-default").addClass("myDefaultButtonClass");
You can also reference the Select button using its ID hpw-btnOK.
The status bar has a class hpw-info and its ID is hpw-status. The ID of the list of possible matches is hpw-possibles. Both the status bar and the list of possible matches are contained within div elements that have the class form-group.
Common Output Fields
The following table lists the output fields that can be retrieved from all Master Address Files (MAFs).
| Data Item | Description |
|---|---|
| Label1-Label9 | Formatted address label comprising up to the specified number of lines. |
| Department | Department associated within an organisation |
| Organisation | Organisation name for a delivery point |
| Flat | Flat – formatted as if in a label |
| Floor | Floor – formatted as if in a label |
| Premise | Premise number – formatted as if in a label |
| POBox | PO Box – formatted as if in a label |
| HouseName1 | Primary house name for a delivery point |
| HouseName2 | Secondary house name for a delivery point |
| StreetName1 | First street of an address |
| StreetName2 | Second street of an address |
| DistrictName1 | Minor district of an address |
| DistrictName2 | Major district of an address |
| Town | Town |
| County | County |
| Postcode | Postcode |
| Country | Country |
| DPID | The delivery point suffix |
| UDPRN | (UK Only) Eight digit numeric code to uniquely identify a UK delivery point |
| UAID | Unique address identifier |
| DedupeKey | Key for deduplication purposes |
| ExtendedDedupeKey | Key for deduplication purposes |