Rest API - Hopewiser

Overview

Provides address lookup and verification using standard URL requests, plus the ability to customise label formatting and retrieve extra data.
The service follows RESTful principles – accepting HTTP requests and returning JSON or XML response documents.
Alternatively if you prefer predicted matches ‘as you type’ then we have a like for like facility called AutoComplete API.

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.
An address lookup is initiated by supplying a URL for example:

https://cloud.hopewiser.com/atlaslive/json/uk-rm-paf?q=WA145NL

Customisations can allow you to change the appearance of displayed results for example, if you want to automatically expand each level of the lookup to provide a single fully flattened pick-list you can supply a URL of:

https://cloud.hopewiser.com/atlaslive/json/uk-rm-paf?q=WA145NL&DisplayResults=AsaList

The AtlasLive 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 always included in the label. 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/atlaslive/json/uk-rm-paf?q=00000000000%24%40sid%5E%25%2B2%2B0%25DOWNING%20STREET%7C%7CLONDONi8&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/atlaslive/output

where:

output indicates the required output format – either json or xml

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

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

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <MAFs>
      <ID>uk-nspd-paf</ID>
    </MAFs>
    <MAFs>
      <ID>uk-rm-paf</ID>
    </MAFs>
  </Results>
</Response>

How do I lookup an address?

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

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

where:

output indicates the required output format – either json or xml
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 could be a postcode, full or partial address. Splitting address elements (e.g. premise name, street, town, etc.) into a comma separated value generally yields better results. Both single character (?) and multi character (*) wild-cards are supported. Please note that the search criteria must be URL encoded.

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

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

This will return a pick-list of possible matches, which the client program would most likely reformat and present to the end user as a list or tree.

{
  "Status": "OK",
  "Results": {
    "NumItems": 1,
    "Items": [
      {
        "Sid": "00000000000%24%40sid%5E%25%2B0%25DOWNING%20STREET%7C%7CLONDON9o",
        "ItemText": "+ Downing Street,London SW1A",
        "IsExpandable": true,
        "IsComplete": false,
        "Selected": false
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <NumItems>1</NumItems>
    <Items>
      <Sid>00000000000%24%40sid%5E%25%2B0%25DOWNING%20STREET%7C%7CLONDON9o</Sid>
      <ItemText>+ Downing Street,London SW1A</ItemText>
      <IsExpandable>true</IsExpandable>
      <IsComplete>false</IsComplete>
      <Selected>false</Selected>
    </Items>
  </Results>
</Response>

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) parameter, along with any non-default options. Please note that the Sid is already URL encoded.

https://cloud.hopewiser.com/atlaslive/json/uk-rm-paf?q=00000000000%24%40sid%5E%25%2B0%25DOWNING%20STREET%7C%7CLONDON9o

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",
  "Results": {
    "NumItems": 1,
    "Items": [
      {
        "Sid": "00000000000%24%40sid%5E%25%2B2%2B0%25DOWNING%20STREET%7C%7CLONDONi8",
        "IsExpandable": false,
        "IsComplete": true,
        "Selected": true,
        "Label1": "Prime Minister & First Lord of The Treasury",
        "Label2": "10 Downing Street",
        "Label3": "LONDON",
        "Label4": "SW1A 2AA"
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <NumItems>1</NumItems>
    <Items>
      <Sid>00000000000%24%40sid%5E%25%2B2%2B0%25DOWNING%20STREET%7C%7CLONDONi8</Sid>
      <IsExpandable>false</IsExpandable>
      <IsComplete>true</IsComplete>
      <Selected>true</Selected>
      <Label1>Prime Minister &amp; First Lord of The Treasury</Label1>
      <Label2>10 Downing Street</Label2>
      <Label3>LONDON</Label3>
      <Label4>SW1A 2AA</Label4>
    </Items>
  </Results>
</Response>

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 both expandable and complete.

The SelectItem parameter can be used to obtain output fields for any pick-list item, even when that item does not contain a complete address (for example).

https://cloud.hopewiser.com/atlaslive/json/uk-rm-paf?q=00000000000%24%40sid%5E%25%2B0%25DOWNING%20STREET%7C%7CLONDON9o&SelectItem=true

Please note that the response will only contain the output fields that have a value.

{
  "Status": "OK",
  "Results": {
    "NumItems": 1,
    "Items": [
      {
        "Sid": "00000000000%24%40sid%5E%25%2B0%25DOWNING%20STREET%7C%7CLONDON9o",
        "IsExpandable": true,
        "IsComplete": false,
        "Selected": true,
        "Label1": "Downing Street",
        "Label2": "LONDON",
        "Label3": "SW1A"
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <NumItems>1</NumItems>
    <Items>
      <Sid>00000000000%24%40sid%5E%25%2B0%25DOWNING%20STREET%7C%7CLONDON9o</Sid>
      <IsExpandable>true</IsExpandable>
      <IsComplete>false</IsComplete>
      <Selected>true</Selected>
      <Label1>Downing Street</Label1>
      <Label2>LONDON</Label2>
      <Label3>SW1A</Label3>
    </Items>
  </Results>
</Response>

How do I search on index, name* or radius?

All Master Address Files (MAFs) support address searching for a given postcode, full or partial address. Some MAFs may contain additional data that also allows address searching from either a given index name and value, a personal name* or a grid reference and radius.

To discover the address searching capabilities of a Master Address File, specify ListIndexes as the q (query) parameter value.

https://cloud.hopewiser.com/atlaslive/output/maf?q=ListIndexes

where:

output indicates the required output format – either json or xml
maf is the identity of the Master Address File

The ListIndexes query will return two integer flags (NamesAvailable and RadiusSearchAllowed) which identify the MAF’s name searching and radius searching capabilities. If the MAF supports index searching, then the response will also include a list of available indexed field names.

Flag	Value	Description
NameAvailable*	0 1 2	Name* search is not supported. Supports surname* searching only. Supports both forename* and surname* searching.
RadiusSearchAllowed	0 1	Radius search is not supported. Supports radius searching.
Index	Fieldname	Indexed search is supported against the indexed Fieldname.

{
  "Status": "OK",
  "Results": {
    "NamesAvailable": 0,
    "RadiusSearchAllowed": 0,
    "Indexes": [
      {
        "Name": "Extra_LPIKEY",
        "TableName": "Extra Data"
      },
          
      etc...      
      
      {
        "Name": "Extra_USRN",
        "TableName": "Extra Data"
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <NamesAvailable>0</NamesAvailable>
    <RadiusSearchAllowed>0</RadiusSearchAllowed>
    <Indexes>
      <Name>Extra_LPIKEY</Name>
      <TableName>Extra Data</TableName>
    </Indexes>
    
    etc...
    
    <Indexes>
      <Name>Extra_USRN</Name>
      <TableName>Extra Data</TableName>
    </Indexes>
  </Results>
</Response>

Indexed Searching – allows the retrieval of an address for a given index name and value. In this instance both a SearchOn and q parameter are required. The SearchOn parameter denotes the index name and the q parameter specifies the search criteria within that index.
Name Searching* – allows the retrieval of an address for a given personal name* plus address filter. It requires either a Forename* and/or Surname* parameter as the search criteria. With name* searching the q parameter is optional, but would generally be provided as an address filter to limit the search area. This could be a postcode, full or partial address.
Radius Searching – allows the retrieval of an address for a given grid reference and search radius. It requires four mandatory parameters. The q parameter is used to denote the search method and must be assigned the fixed value RadiusSearch, GridX and GridY parameters define the grid reference and a Radius parameter specifies the search area. These values are specified in metres.

Customisations

How do I change the appearance of displayed pick lists?

The following table lists the options to change the appearance of pick lists.

Option	Description
DisplayResults	Select how to display the results. Allowed values are AsATree (the default) or AsAList The value AsATree will return a pick-list for each level of the lookup, allowing the end user to drill down a specific search path. The value AsAList will automatically expand each level of the lookup to provide a single fully flattened pick-list.
PostcodeResultLevel	Set how the results from postcode lookups are structured. Allowed values are Street (the default) or Premise. The value Street will return a pick-list at the street level, allowing the end user to drill down to the premises. The value Premise will return a pick-list at the premise level, without needing to drill down.
ResultSorting	Specify how the pick-list items are sorted. Allowed values are Intelligent (the default) or ByPostcode. The value Intelligent specifies that the pick-list items are ordered by the street name then premise.
StreetsOverMultipleDistricts	Specify how to handle streets that span multiple districts. Allowed values are SeparateByDistrict (the default) or NoSeparation. The value SeparateByDistrict will expand a street that spans several districts into a pick-list of districts, allowing the end user to drill down to the premises within that district. The value NoSeparation will expand a street into a pick-list of premises across all districts.
SubpremiseLevel	Specify how to handle listing sub-premises. Allowed values are SubpremisesOnNextLevel (the default) or SubpremisesOnSameLevel. The value SubpremisesOnNextLevel separates premise and sub-premise details into two pick-list levels, such that the end user will need to drill down from a premise to its sub-premise details. The value SubpremisesOnSameLevel returns both premise and sub-premise details within a single pick-list.
ResultFormatting	Specify the detail level within the pick-list item text. Allowed values are Intelligent (the default) or Fixed. The value Intelligent specifies that the item text only contains information that has not been presented at a higher level. The value Fixed specifies that the item text contains all available address information at each level.
IncludeCountyInPickList	Specify when counties are included within the pick-list item text. Allowed values are AsRequired (the default), Never or Always. 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.
PostcodeInPickList	Specify when postcodes are included within the pick-list item text. Allowed values are Exclude (the default) or Include.
HouseAndFlatBecomePremise	Combine the house and flat as premise details in Scottish tenements. Allowed values are Never (the default) or AsRequired.
ReturnWelshAddresses	Specify that, when available, either the English, Welsh or both versions of the address should be returned (e.g. “Westgate Street, Cardiff” and/or “Heol Y Porth,Caerdydd”). Allowed values are Never, IfAvailable, EnglishOnly (the default), WelshOnly or EnglishAndWelsh. Please note that the values Never and IfAvailable have been deprecated. Never has been replaced with EnglishOnly and IfAvailable has been replaced with WelshOnly. Please note that this option is only applicable when the search criteria is a postcode.
DisplayListLevel	Specify the pick-list level to be displayed when the DisplayResults option has the value AsAList. The allowed values are premise or name. The default value is dependent on the configuration of the service. For Hopewiser’s Address Lookup the default is premise. This parameter only has an effect when the search result is set to AsAList. The default value for this parameter is premise* which denotes that a flatten search will stop at the premise level. However, on some systems, this can be defaulted to name level when the application “FlattenToName”* attribute is set to “yes”. The value premise automatically expand each level of the lookup to provide a single fully flattened pick-list at the premise level. The value name* automatically expand each level of the lookup to provide a single fully flattened pick-list at the name* level.
Forename*	Specify the Forename* search criteria. Only applicable when the MAF supports name* searching.
Surname*	Specify the Surname* search criteria. Only applicable when the MAF supports name* searching.
SearchOn	Specify the field name to search when performing an indexed address search. When this option is provided the q (query) parameter contains the search criteria within that field. Refer to the “How do I discover the searching capabilities of a given MAF?” section in Customisations to identify the available field names.
GridX	Specify the X coordinate (in metres) of the grid-reference point when performing a radius address search.
GridY	Specify the Y coordinate (in metres) of the grid-reference point when performing a radius address search.
Radius	Specify the distance (in metres) from the grid-reference point when performing a radius address search.

How do I customise an address label?

The AtlasLive 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 always included in the label.

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/atlaslive/json/uk-rm-paf?q=00000000000%24%40sid%5E%25%2B2%2B0%25DOWNING%20STREET%7C%7CLONDONi8&OutputFields=Label8&LabelFormat=FixedPostcode

The following table lists the Label Parameter options available.

Option	Description
OutputFields	This 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.
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 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.
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 town names.
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.
DropNameFromLabel*	Remove resident name* from the formatted address label. Allowed values are Never (the default) or Always.

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

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

where:

output indicates the required output format – either json or xml
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": {
    "NamesAvailable": 0,
    "Outputs": [
      {
        "Name": "Label1",
        "TableName": "Address Label",
        "Tooltip": "The first line of a formatted address label"
      },
          
      etc...      
      
      {
        "Name": "Extra_ADDRESS_KEY",
        "TableName": "Extra Data"
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <NamesAvailable>0</NamesAvailable>
    <Outputs>
      <Name>Label1</Name>
      <TableName>Address Label</TableName>
      <Tooltip>The first line of a formatted address label</Tooltip>
    </Outputs>
    
    etc...
    
    <Outputs>
      <Name>Extra_ADDRESS_KEY</Name>
      <TableName>Extra Data</TableName>
    </Outputs>
  </Results>
</Response>

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/atlaslive/json/uk-rm-paf?q=00000000000%24%40sid%5E%25%2B2%2B0%25DOWNING%20STREET%7C%7CLONDONi8&OutputFields=Label7,Country,Extra_

When the address lookup is complete (i.e. the Selected field is true) or a specific pick-list item has been selected, 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",
  "Results": {
    "NumItems": 1,
    "Items": [
      {
        "Sid": "00000000000%24%40sid%5E%25%2B2%2B0%25DOWNING%20STREET%7C%7CLONDONi8",
        "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"
            }
          ]
        }
      }
    ]
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <NumItems>1</NumItems>
    <Items>
      <Sid>00000000000%24%40sid%5E%25%2B2%2B0%25DOWNING%20STREET%7C%7CLONDONi8</Sid>
      <IsExpandable>false</IsExpandable>
      <IsComplete>true</IsComplete>
      <Selected>true</Selected>
      <Label1>Prime Minister &amp; First Lord of The Treasury</Label1>
      <Label2>10 Downing Street</Label2>
      <Label3>LONDON</Label3>
      <Label4>SW1A 2AA</Label4>
      <Country>UNITED KINGDOM</Country>
      <Extra>
        <Records>
          <Extra_ADDRESS_KEY>01626260</Extra_ADDRESS_KEY>         
        </Records>
      </Extra>
    </Items>
  </Results>
</Response>

How do I get version information?

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

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

where

output indicates the required output format – either json or xml
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": {
      "ATLASLIVESERVERVersion": "0.0.5",
      "ATLASLIVEVersion": "1.26.0",
      "ATLASVersion": "Atlas Version: 3.53.70 (fh:3.5.0 xfh:2.0.0)",
      "MAFVersion": "MAF Version 49 (UU) UNITED KINGDOM Built 20130627"
    }
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <Versions>
      <ATLASLIVESERVERVersion>0.0.5</ATLASLIVESERVERVersion>
      <ATLASLIVEVersion>1.26.0</ATLASLIVEVersion>
      <ATLASVersion>Atlas Version: 3.53.70 (fh:3.5.0 xfh:2.0.0)</ATLASVersion>
      <MAFVersion>MAF Version 49 (UU)  UNITED KINGDOM  Built 20130627</MAFVersion>
    </Versions>
  </Results>
</Response>

Common Output Fields

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

Field	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
AdditionalPremise	Additional premise number – formatted as if in a label
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

Response Codes

The AtlasLive 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 Code	Description
OK	Successful.
NO_MATCH	No matching address found.
LABEL_NOT_FORMATTED_ERROR	The address will not fit within the size specified for the formatted address label.
TOO_MANY_MATCHES	No output was returned because too many matches were found for the given search criteria.
BAD_LOOKUP	Either no search criteria or invalid search criteria was provided.
BAD_SID	An invalid search identity was provided.
BAD_PARAM	An invalid parameter value was provided.
CANT_EXPAND	The pick-list item cannot be expanded into a lower level pick-list.
OPEN_ERROR	The specified Master Address File is unknown, not provisioned for the user or blocked.

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

{
  "Status": "BAD_PARAM",
  "StatusDetails": {
    "Description": "The value of DisplayResults is not valid"
  }
}

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>BAD_PARAM</Status>
  <StatusDetails>
    <Description>The value of DisplayResults is not valid</Description>
  </StatusDetails>
</Response>

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

Authorisation Code

Footnote: *This is not currently available via our Cloud solution.