AutoComplete JavaScript Client

Cloud Address Lookup APIs & Clients

Overview

  • The Autocomplete service offers address lookup and verification through standard URL requests. It allows for customization of label formatting and the retrieval of additional data.
  • ‘As you type’, the service shows the most relevant matches, starting to display options once the user has entered three characters. To improve usability, the number of displayed matches is limited to 20, and these options dynamically change as the user continues to type.
  • Does not require installing any files, as they can be referenced from the hosted service.
  • Our sample code download offers a demonstration webpage (for HTML or PHP) showcasing standard functionality. This code can be modified and tailored to meet your specific requirements.

Quick Start

  • 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 the token username and password you created in registering.
  • Download, unzip, and extract the AutoComplete 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.

Basics

How do I install AutoComplete JavaScript Client?

In the <head> of your web page, add the lines…

  <link rel="stylesheet" href="https://cloud.hopewiser.com/jsclient2/jquery-ui.min.css" />
  <link rel="stylesheet" href="https://cloud.hopewiser.com/jsclient2/hpw-autoc-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/jquery-ui.min.js"></script>
  <script src="https://cloud.hopewiser.com/jsclient2/json2.min.js"></script>
  <script src="https://cloud.hopewiser.com/jsclient2/hpw-autoc-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 instead of using our cloud 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, jQuery UI or json2, you may be able to omit the applicable lines or reference your existing installation as necessary.

Finally, add a script to enable the address autocomplete feature on a nominated input field by association with a HPWAUTOC.FindAddress() function:

  <script>
    HPWAUTOC.FindAddress({
      server:       X,        // optional (default = "https://cloud.hopewiser.com")
      auth:         X,        // required
      dataset:      X,        // required
      minLength:    N,        // optional numeric value (default = 1)
      delay:        N,        // optional numeric value (default = 300)
      input:        X,        // required
      outputlines:  N,        // optional range value 2-9 (default = 7)
      output: {
        line1:      X,        // required
        line2:      X,        // required
        line3:      X,        // optional
        line4:      X,        // optional
        line5:      X,        // optional
        line6:      X,        // optional
        line7:      X,        // optional
        line8:      X,        // optional
        line9:      X,        // optional
        country:    X         // optional
      },
      success:                 X,   // optional callback function
      LabelFormat:             X,   // optional (default = "Standard")
      ReserveOrganisationLine: X,   // optional (default = "AsRequired")
      IncludeCounty:           X,   // optional (default = "AsRequired")
      DropCountyToFitLabel:    X,   // optional (default = "Never")
      TownFormat:              X    // optional (default = "Uppercase")
    });
  </script>

The HPWAUTOC.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, and
  • Optionally, parameters to influence other service behaviours referenced in the below Optional Parameter table.
Mandatory Parameter Description
auth A valid authorisation code is required to access the required dataset.
dataset A dataset ID associated with the MAF and AutoComplete database files.
input The search field to invoke the AutoComplete address lookup.
output.line1 to output.line2 The first two lines of the formatted label for the selected address.
Optional Parameter Description
server This is the URL to the AutoComplete Server. It defaults to “https://cloud.hopewiser.com”.
minLength This is the minimum number of characters a user must type before a search is performed. Its default value is 1.
delay This is a delay in milliseconds between when a keystroke occurs and when a search is performed. No menu will be displayed until the typist pauses for the specified delay period after the last keystroke. Its default value is 300.
outputlines This parameter is used to specify the maximum number of formatted output lines which should to be mapped accordingly in the “output.line” block. Allowed range is 2 to 9. Its default value is 7.
output.line3 to output.line9 Configure field mappings to include additional address label lines.
output.country Configure a field mapping to include the country field information.
‘detail’ matched address output fields This optional configuration section contains mapping information for some of the common address output fields.

The available detail elements will depend on your dataset. To view the available detail elements, visit:

https://cloud.hopewiser.com/autoc/json/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com/autoc/json/uk-nspd-paf-external?q=listoutputs. Enter your User name and Password when prompted. The available detail elements are those Outputs that have a TableName of Address Fields or Data.
‘extra’ data fields This optional configuration section contains mapping information for Extra Data fields of a given matched address.

The available extra data elements will depend on your dataset. To view the available extra data elements, visit:

https://cloud.hopewiser.com/autoc/json/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com/autoc/json/uk-nspd-paf-external?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.
success Calls a callback function at the end of populating the returned address if this parameter is configured.
LabelFormat Select the position of the town, county and postcode within the formatted address label. Allowed values are Standard (the default), FixedPostcode or FixedTown.

The value FixedPostcode reserves the last line of the formatted address label for the postcode and forces it to be output on a separate line.

The value FixedTown reserves the last three lines of the formatted address label for the town, county and postcode and forces each value to be output on a separate line. Please note that a line is reserved for the county even if none is output.

When a fixed value is requested, the formatted address label will comprise the maximum allowed number of address lines, some of which may be empty.
ReserveOrganisationLine Select the position of the organisation within the formatted label. Allowed values are Always, Never or AsRequired (the default).

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.
IncludeCounty Select when the county should be included within the formatted address label. Allowed values are Always, Never or AsRequired (the default).
DropCountyToFitLabel Select if the county may be dropped when it does not fit within the formatted address label. Allowed values are Never (the default), or Always.
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.

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",          // required
    dataset: "uk-rm-paf-mr", // required
    input: "txtInput",             // required
    output: {
      line1:    "txtLine1",        // required
      line2:    "txtLine2",        // required
      line3:    "txtLine3",        // optional
      line4:    "txtLine4",        // optional
      line5:    "txtTown",         // optional
      line6:    "txtCounty",       // optional
      line7:    "txtPostcode",     // optional
      country:  "txtCountry"       // optional
    },
    LabelFormat: "FixedTown",           // optional (default = "Standard")
    ReserveOrganisationLine: "Never",   // optional (default = "AsRequired")
    IncludeCounty: "Always",            // optional (default = "AsRequired")
    TownFormat: "Lowercase"             // 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.

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",          // required
    dataset: "uk-rm-paf-mr", // required
    input: "txtInput",             // required
    outputlines:  9,               // optional range value 2-9 (default = 7)
    output: {
      line1:    "txtAddress",      // required
      line2:    "txtAddress",      // required
      line3:    "txtAddress",      // optional
      line4:    "txtAddress",      // optional
      line5:    "txtAddress",      // optional
      line6:    "txtAddress",      // optional
      line7:    "txtAddress",      // optional
      line8:    "txtAddress",      // optional
      line9:    "txtAddress",      // optional
      country:  "txtAddress"       // optional
    },
    IncludeCounty: "Always"        // optional (default = "AsRequired")
  });

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.

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",          // required
    dataset: "uk-rm-paf-mr", // required
    input: "txtInput",             // required
    output: {
      line1:    "txtAddress",      // required
      line2:    "txtAddress",      // required
      line3:    "txtAddress",      // optional
      line4:    "txtAddress",      // optional
      line5:    "txtTown",         // optional
      line6:    "txtCounty",       // optional
      line7:    "txtPostcode",     // optional
      country:  "txtCountry"       // optional
    },
    LabelFormat: "FixedTown",           // optional (default = "Standard")
    ReserveOrganisationLine: "Never",   // optional (default = "AsRequired")
    IncludeCounty: "Always",            // optional (default = "AsRequired")
    TownFormat: "Lowercase"             // optional (default = "Uppercase")
  });

Replace yourAuthCode with your authorisation code and the example HTML IDs with your actual HTML IDs. 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?

Key in a search criteria into your input field, an autocomplete menu will be automatically displayed when the minimum length and delay conditions are met and one or more matched items are returned from the AutoComplete server. You can narrow down the search by either keying in more information or select one of the returned items from the autocomplete menu. The menu will be closed automatically either by pressing the ESC key to abort the search or by selecting a fully completed address from the menu.

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

Customisations

How do I install AutoComplete JavaScript Client service files locally?

You do not have to download anything to use the AutoComplete 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 AutoComplete JavaScript Client files from here.

Uncompress the downloaded AutoCompleteJavaScriptClient.zip file and then upload the extracted files to a suitable location on your web server.

How do I customise and address label?

Variations in the appearance of an output address label are achieved, in the AutoComplete JavaScript Client solution, via five optional parameters in the FindAddress() function call – LabelFormat, IncludeCounty, DropCountyToFitLabel, ReserveOrganisationLine, and TownFormat. For full details on each, please refer to the How do I install AutoComplete JavaScript Client? 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 HPWAUTOC.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:

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",          // required
    dataset: "uk-rm-paf-mr", // required
    input: "txtInput",             // required
    output: {
      line1:    "txtLine1",        // required
      line2:    "txtLine2",        // required
      line3:    "txtLine3",        // optional
      line4:    "txtLine4",        // optional
      line5:    "txtTown",         // optional
      line6:    "txtCounty",       // optional
      line7:    "txtPostcode",     // optional
      country:  "txtCountry"       // optional
    },
    detail: {                      // optional
      Premise: "txtPremise",
      UDPRN:   "txtUdprn"
            },
    LabelFormat: "FixedTown",           // optional (default = "Standard")
    ReserveOrganisationLine: "Never",   // optional (default = "AsRequired")
    IncludeCounty: "Always",            // optional (default = "AsRequired")
    TownFormat: "Lowercase"             // optional (default = "Uppercase")
  });

The available detail elements will depend on your dataset. To view the available detail elements, visit:

https://cloud.hopewiser.com/autoc/json/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com/autoc/json/uk-nspd-paf?q=listoutputs. Enter your User name and Password when prompted. The available detail elements are those Outputs that have a TableName of “Address Fields” or “Data”.

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

  HPWAUTOC.FindAddress({
    auth: "yourAuthCode",            // required
    dataset: "uk-nspd-paf", // required
    input: "txtInput",               // required
    output: {
      line1:    "txtLine1",          // required
      line2:    "txtLine2",          // required
      line3:    "txtLine3",          // optional
      line4:    "txtLine4",          // optional
      line5:    "txtTown",           // optional
      line6:    "txtCounty",         // optional
      line7:    "txtPostcode",       // optional
      country:  "txtCountry"         // optional
    },
    extra: {                         // optional
      Extra_Grid_Latitude:  "txtLatitude",
      Extra_Grid_Longitude: "txtLongitude"
    },
    LabelFormat: "FixedTown",         // optional (default = "Standard")
    ReserveOrganisationLine: "Never", // optional (default = "AsRequired")
    IncludeCounty: "Always",          // optional (default = "AsRequired")
    TownFormat: "Lowercase"           // 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/autoc/json/dataset?q=listoutputs

Replace dataset with the dataset you want to use, e.g. https://cloud.hopewiser.com/autoc/json/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 HPWAUTOC.FindAddress() function, you can include an optional success attribute containing the function that you want to call. For example:

  function btnFindAddress_onclick() {
    HPWAUTOC.FindAddress({
      auth: "yourAuthCode",                   // required
      dataset: "uk-rm-paf-mr
",          // required
      input: "txtInput",                      // required
      output: {
        line1:    "txtLine1",                 // required
        line2:    "txtLine2",                 // required
        line3:    "txtLine3",                 // optional
        line4:    "txtLine4",                 // optional
        line5:    "txtTown",                  // optional
        line6:    "txtCounty",                // optional
        line7:    "txtPostcode",              // optional
        country:  "txtCountry"                // optional
      },
      success: EnableButton,                  // optional
      LabelFormat: "FixedTown",               // optional (default = "Standard")
      ReserveOrganisationLine: "AsRequired",  // optional (default = "AsRequired")
      IncludeCounty: "AsRequired",            // optional (default = "AsRequired")
      TownFormat: "Uppercase"                 // optional (default = "Uppercase")
    });
  }

  function EnableButton() {
    document.getElementById("btnNext").disabled = false;
  }

Common Output Fields

The following table lists the output fields that can be retrieved from all Master Address Files (MAFs).

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

Banks, Police Forces, and major Sports organisations trust us with their data validation. You can too.

Get a demo Free trial

You're in good company

Products

Integrations

Company

Developer Docs

  • OS Partner
  • FSQS
  • GDPR
  • Royal Mail Partner

We take security and privacy seriously

Learn more about security and compliance at Hopewiser

Logo
  • X
UK

© 1995 - 2026 Hopewiser Ltd. All rights reserved.

Website by Yello