Skip to main content

AutoComplete Rest API

Overview

  • It provides address lookup and verification using standard URL requests, plus the ability to customise label formatting and retrieve extra data.
  • Service that presents the most relevant matches ‘as you type’.
  • The service follows RESTful principles – accepting HTTP requests and returning JSON or XML response documents.

Quick Start Guide

  • 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
  • An address lookup is initiated by supplying a URL for example:
https://cloud.hopewiser.com/autoc/json/uk-rm-paf?q=Downing%20Street%2CLondon
  • The AutoComplete service defaults to return a free format address label, which may contain up to seven address lines. The town is presented in uppercase and the county is only included when appropriate, for example when it is required to disambiguate town names. If this does not meet your requirements, then you can customise the layout. For example to increase the number of address lines to eight and to fix the last address line for the postcode you can supply a URL of:
https://cloud.hopewiser.com/autoc/json/uk-rm-paf?q=00000000000%24%40sid%5ESBP17424391&OutputFields=Label8&LabelFormat=FixedPostcode
  • Authentication is achieved using HTTP Basic Authentication, where both the token username and password are supplied in the HTTP header. To secure this information all requests should use the https:// protocol, in preference to standard http:// .

Basics

How do I discover my available Master Address Files?

To discover the Master Address Files (MAFs) that are configured for the authenticated user, supply a URL of the form.

https://cloud.hopewiser.com/autoc/output

where:

  • output indicates the required output format – currently this must be json>

This will return a list of available MAF identities (for example).

{
  "Status": "OK",
  "Results": {
    "MAFs": [
      {
        "ID": "uk-nspd-paf"
      },
      {
        "ID": "uk-rm-paf"
      }
    ]
  }
}

How do I lookup an address?

An address lookup is initiated by supplying a URL of the form.

https://cloud.hopewiser.com/autoc/output/maf?parameters

where:

  • output indicates the required output format – currently this must be json
  • maf is the identity of the Master Address File to which the lookup is applied
  • parameters is a set of request parameters

Only a single request parameter is required – the query string. All other parameters are optional and should only be supplied when a non-default setting is required. As is standard with URLs, each parameter must be separated by an ampersand (&) character.

The query string is denoted by a single ‘q‘ character. This is the address search criteria, which can be anything from a single character up to a full address. Please note that the search criteria must be URL encoded.

It is good practice to avoid sending multiple requests whilst the user is entering the search criteria. Delaying the request by a fraction of a second (for example 500 milliseconds) after each input character will allow for faster data entry with the request being made when the user stops typing.

Example address lookup request for “Downing Street,London”.

https://cloud.hopewiser.com/autoc/json/uk-rm-paf?q=Downing%20Street%2CLondon

This will return a pick-list of possible matches with the best predictions coming first. The client program would most likely reformat and present these to the end user as a list or tree. If the required address is not present then further input is needed to refine the list.

{
  "Status": "OK",
  "QueryStr": "Downing%20Street%2CLondon",
  "Results": {
    "NumItems": 4,
    "Items": [
      {
        "Sid": "00000000000%24%40sid%5ETHR647134",
        "ItemText": "Downing Street,London SW1A",
        "IsExpandable": true,
        "IsComplete": false,
        "Selected": false
        "ExpandsTo": 5
      },
      {
        "Sid": "00000000000%24%40sid%5ETHR656141",
        "ItemText": "Downing Court,Grenville Street,LONDON,WC1N",
        "IsExpandable": true,
        "IsComplete": false,
        "Selected": false
        "ExpandsTo": 27
      },
      ...
    ]
  }
}

When an item is selected the client program should continue the address lookup by specifying the item’s Sid (search identity) in the q (query string) parameter, along with any non-default options. Please note that the Sid is already URL encoded.

https://cloud.hopewiser.com/autoc/json/uk-rm-paf?q=00000000000%24%40sid%5ETHR647134

The previous two steps should be repeated until a single item is returned with the Selected field value true. When the Selected field is true the address lookup is complete and the requested output fields will be returned.

{
  "Status": "OK",
  "QueryStr": "00000000000%24%40sid%5ESBP17424391",
  "Results": {
    "NumItems": 1,
    "Items": [
      {
        "Sid": "00000000000%24%40sid%5ESBP17424391",
        "IsExpandable": false,
        "IsComplete": true,
        "Selected": true,
        "Label1": "Prime Minister & First Lord of The Treasury",
        "Label2": "10 Downing Street",
        "Label3": "LONDON",
        "Label4": "SW1A 2AA"
      }
    ]
  }
}

Each item in a pick-list contains three control flags:

  • IsExpandable is true when the item can be expanded
  • IsComplete is true when the item contains a complete address
  • Selected is true when a single item has been selected and the requested output fields have been returned

Please note that an item can be either expandable or complete, but not both.

Customisations

How do I customise an address label?

The AutoComplete service defaults to return a free format address label, which may contain up to seven address lines. The town is presented in uppercase and the county is only included when appropriate, for example when it meets PTT guidelines or is required to disambiguate town names.

If this does not meet your requirements, then you can customise the layout. For example to increase the number of address lines to eight add the URL parameter “OutputFields=Label8“. To fix the last address line for the postcode add the parameter “LabelFormat=FixedPostcode“.

https://cloud.hopewiser.com/autoc/json/uk-rm-paf?q=00000000000%24%40sid%5ESBP17424391&OutputFields=Label8&LabelFormat=FixedPostcode
OptionDescription
OutputFieldsThis parameter is used to specify the required output fields within a selected item.

It can be used to define the maximum number of lines in a formatted address label, by specifying a label value from Label1 to Label9. The default is Label7.

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

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

IncludeCountySelect 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 town names.

DropCountyToFitLabelSelect if the county may be dropped when it does not fit within the formatted address label. Allowed values are Never (the default) or Always.
TownFormatSelect the required town format. Allowed values are Uppercase (the default) or Lowercase.

How do I get individual address fields or data fields?

Each Master Address File (MAF) allows for the retrieval of individual address fields and common data. Some MAFs contain extra information beyond that common to all MAFs, such as National Statistics Postcode Directory (NSPD) data.

To discover the available MAF fields, specify ListOutputs as the q (query string) parameter value.

https://cloud.hopewiser.com/autoc/output/maf?q=ListOutputs

where:

  • output indicates the required output format – currently this must be json
  • maf is the identity of the Master Address File

This will return a list of all possible output fields, which are grouped on TableName. Fields with a TableName value of either Address Label, Address Fields or Data are common to all MAFs. Those with the TableName value Extra Data are MAF specific. Please note that a ToolTip is only provided for the common fields.

{
  "Status": "OK",
  "Results": {
    "Outputs": [
      {
        "Name": "Label1",
        "TableName": "Address Label",
        "Tooltip": "The first line of a formatted address label"
      },
          
      etc...      
      
      {
        "Name": "Extra_ADDRESS_KEY",
        "TableName": "Extra Data"
      }
    ]
  }
}

Please refer to the Common Output Fields section for a full list of the standard fields.

Required fields can then be requested by specifying their names as a comma separated list in the OutputFields parameter. The shorthand value Extra_ can be used to specify all Extra Data fields. Please note that adding the OutputFields parameter to the request removes its default value. Hence an appropriate label (Label1..Label9) must be included in the comma separated list when a formatted address label is required.

Example to return a seven line formatted label, plus the country and all MAF specific extra data fields.

https://cloud.hopewiser.com/autoc/json/uk-rm-paf?q=00000000000%24%40sid%5ESBP17424391&OutputFields=Label7,Country,Extra_

When the address lookup is complete (i.e. the Selected field is true), then the requested output fields will be returned. It is possible for multiple values to exist per Extra Data field. Hence the Extra Data fields are grouped into records, where the first set of values comprise the first record, the second set comprise the next record, etc. Please note that only output fields containing a value will be returned.

{
  "Status": "OK",
  "QueryStr": "00000000000%24%40sid%5ESBP17424391",
  "Results": {
    "NumItems": 1,
    "Items": [
      {
        "Sid": "00000000000%24%40sid%5ESBP17424391",
        "IsExpandable": false,
        "IsComplete": true,
        "Selected": true,
        "Label1": "Prime Minister & First Lord of The Treasury",
        "Label2": "10 Downing Street",
        "Label3": "LONDON",
        "Label4": "SW1A 2AA",
        "Country": "UNITED KINGDOM",
        "Extra": {
          "Records": [
            {
              "Extra_ADDRESS_KEY": "01626260"
              ...
            }
          ]
        }
      }
    ]
  }
}

How do I get version information?

To discover the service version information, specify ListVersions as the q (query string) parameter value.

https://cloud.hopewiser.com/autoc/output/maf?q=ListVersions

where:

  • output indicates the required output format – currently this must be json
  • maf is the identity of the Master Address File

This will return the service and underlying library versions, plus the version of the specified MAF.

{
  "Status": "OK",
  "Results": {
    "Versions": {
      "AUTOCSERVER Version": "1.0.0",
      "AUTOCOMPLETE Version": "1.2.0",
      "ATLASLIVE Version": "1.43.0",
      "ATLAS Version": "Atlas Version: 3.66.2 (fh:4.0.0 xfh:2.2.1)",
      "MAF Version": "MAF Version 94 32-bit (UU)  UNITED KINGDOM  Built 20170331"
    }
  }
}

Common Output Fields

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

Label1-Label9Formatted address label comprising up to the specified number of lines.
DepartmentDepartment associated within an organisation
OrganisationOrganisation name for a delivery point
FlatFlat – formatted as if in a label
FloorFloor – formatted as if in a label
PremisePremise number – formatted as if in a label
POBoxPO Box – formatted as if in a label
HouseName1Primary house name for a delivery point
HouseName2Secondary house name for a delivery point
StreetName1First street of an address
AdditionalPremiseAdditional premise number – formatted as if in a label
StreetName2Second street of an address
DistrictName1Minor district of an address
DistrictName2Major district of an address
TownTown
CountyCounty
PostcodePostcode
CountryCountry
DPIDThe delivery point suffix
UDPRN(UK Only) Eight digit numeric code to uniquely identify a UK delivery point
UAIDUnique address identifier
DedupeKeyKey for deduplication purposes
ExtendedDedupeKeyKey for deduplication purposes

Response Codes

The AutoComplete service will return the HTTP status 200 (OK) for all requests that it can interpret. This will be accompanied with a response document containing an application level status code.

Application Status CodeDescription
OKSuccessful.
NO_MATCHNo matching address found.
LABEL_NOT_FORMATTED_ERRORThe address will not fit within the size specified for the formatted address label.
BAD_LOOKUPEither no search criteria or invalid search criteria was provided.
BAD_SIDAn invalid search identity was provided.
BAD_PARAMAn invalid parameter value was provided.
OPEN_ERRORThe specified Master Address File is unknown, not provisioned for the user or blocked.
INTERNAL_ERRORAn unexpected internal error was encountered.

For all status codes, other than OK, a textual description of the response is also provided (for example).

{
  "Status": "BAD_PARAM",
  "QueryStr": "00000000000%24%40sid%5ESBP17424391"
  "StatusDetails": {
    "Description": "The value of TownFormat is not valid"
  }
}

Standard HTTP status codes are applied when the AutoComplete service cannot interpret the request. For example HTTP 401 (Unauthorised) is returned when the request does not contain token credentials or contains invalid credentials. HTTP 500 (Internal Server Error) is returned when the service encounters an unexpected failure.

Authorisation Code