Skip to main content
Ecommerce

International Rest API

Overview

  • Provides international address lookup and verification using standard URL requests, plus the ability to retrieve latitude and longitude coordinates.
  • The service follows RESTful principles – accepting HTTP requests and returning JSON or XML response documents.

Quick Start

    • An Address Lookup service account, with an active International service plan and API token, is required.
    • An address lookup is initiated by supplying a URL for example:
https://cloud.hopewiser.com.au/atlaslive/json/international?country=usa&q=1600%20Pennsylvania%20Ave%20NW,%20Washington
    • The address label is obtained by expanding a pick-list item until a ‘selected’ item is returned.
https://cloud.hopewiser.com.au/atlaslive/json/international?country=usa&q=00000000000%24%40sid%5ENT_m3cTEfo4YS.7IZipciVplC_xYDMwA
    • 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 lookup an address?

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

https://cloud.hopewiser.com.au/atlaslive/output/international?parameters

where:

  • output indicates the required output format – either json or xml
  • parameters is a set of request parameters

Two request parameters are required – the country and 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 country parameter must be given either an ISO3166-1 alpha-2 or alpha-3 country code.

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. Please note that the search criteria must be URL encoded.

Example address lookup request for Downing Street,London’ in the United Kingdom.

https://cloud.hopewiser.com.au/atlaslive/json/international?country=gbr&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,
        "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>
      <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 the country and any non-default options. Please note that the Sid is already URL encoded.

https://cloud.hopewiser.com.au/atlaslive/json/international?country=gbr&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 property value true. When the Selected property is true the address lookup is complete and the requested output fields will be returned.

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%2B2%2B0%25DOWNING%20STREET%7C%7CLONDONi8",
        "IsExpandable": false,
        "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>
      <Selected>true</Selected>
      <Label1>Prime Minister & 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 two control flags.

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

How do I discover the supported countries?

The supported countries are obtained by supplying a URL of the form.

https://cloud.hopewiser.com.au/atlaslive/countries/output

where:

  • output indicates the required output format – either json or xml

This will return the list of all available countries.

{
  "Status": "OK",
  "Results": {
    "Countries": [
      {
        "Name": "Afghanistan",
        "Code2": "AF",
        "Code3": "AFG",
        "CoverageLevel": "City",
        "CustomPickList": false
      },
etc...
      {
        "Name": "Zimbabwe",
        "Code2": "ZW",
        "Code3": "ZWE",
        "CoverageLevel": "None",
        "CustomPickList": false
      }
    ]
  }
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <Countries>
      <Name>Afghanistan</Name>
      <Code2>AF</Code2>
      <Code3>AFG</Code3>
      <CoverageLevel>None</CoverageLevel>
      <CustomPickList>false</CustomPickList>
    </Countries>
	etc...
	<Countries>
      <Name>Zimbabwe</Name>
      <Code2>ZW</Code2>
      <Code3>ZWE</Code3>
      <CoverageLevel>None</CoverageLevel>
      <CustomPickList>false</CustomPickList>
</Response>

Code2 provides the ISO3166-1 alpha-2 country code and Code3 provides the ISO3166-1 alpha-3 country code.

The CoverageLevel identifies the available address precision for that country either; SubPremise, HouseNumber, HouseNumberRange (full coverage to house number based on address ranges), Street, City or None.

Given the CoverageLevel is variable, Hopewiser do not recommend performing address verification for those countries where the CoverageLevel is City or None. Doing so would consume clicks and return very little usable address details, we advise for these CoverageLevels, that it would be much better to capture the information manually.

Countries with the CustomPickList value true support the expansion of matched items to their next address level, which can be repeated until the full address details are found. They also allow you to change the appearance of the displayed pick-list. For example to automatically expand each level of the lookup and provide a single fully flattened list.

Customisations

The appearance of the pick-list can be changed for the countries that support customisations (i.e. have the CustomPickList value true).

Each required customisation should be provided as a URL query parameter within the lookup request. For example to return a single fully flattened pick-list, add the DisplayResults parameter with the value AsAList.

https://cloud.hopewiser.com.au/atlaslive/json/international?country=gbr&q=Downing%20Street%2CLondon&DisplayResults=AsAList

The following table lists the available options.

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.

How do I get individual address fields or extra data?

Individual address fields plus latitude and longitude extra data can be returned for all countries.

Each required field should be specified as a comma separated list in the query parameter OutputFields. For example to return the country plus latitude and longitude coordinates, add the OutputFields parameter with the value Country,Extra_LATITUDE,Extra_LONGITUDE.

https://cloud.hopewiser.com.au/atlaslive/json/international?country=usa&q=00000000000%24%40sid%5ENT_m3cTEfo4YS.7IZipciVplC_xYDMwA&OutputFields=Country,Extra_LATITUDE,Extra_LONGITUDE

The requested output fields will be returned along with the address label, when the address lookup is complete (i.e. the Selected property is true). Please note that extra data fields are grouped into records and fields with no value are omitted from the response.

{
  "Status": "OK",
  "Results": {
    "NumItems": 1,
    "Items": [
      {
         "Sid": "00000000000%24%40sid%5ENT_m3cTEfo4YS.7IZipciVplC_xYDMwA",
         "IsExpandable": false,
         "Selected": true,
	 "Label1": "1600 Pennsylvania Ave NW",
	 "Label2": "Washington, DC 20500",
	 "Country": "United States",
	 "Extra": {
	   "Records": [ 
             {
                "Extra_LATITUDE": "38.89768",
                "Extra_LONGITUDE": "-77.03655"
              }
            ]
          }
        }
      ]
    }
  } 
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>OK</Status>
  <Results>
    <NumItems>1</NumItems>
    <Items>
      <Sid>00000000000%24%40sid%5ENT_m3cTEfo4YS.7IZipciVplC_xYDMwA</Sid>
      <IsExpandable>false</IsExpandable>
      <Selected>true</Selected>
	  <Label1>1600 Pennsylvania Ave NW</Label1>
	  <Label2>Washington, DC 20500</Label2>
	  <Country>United States</Country>
      etc...
	  <Extra>
	  <Records>
      <Extra_LATITUDE>38.89768</Extra_LATITUDE>
      <Extra_LONGITUDE>-77.03655</Extra_LONGITUDE>
     </Records>
    </Extra>
   </Items>
  </Results>
 </Response>	

The following table lists the available address fields.

Field Description
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
State State
Postcode Postcode
Country Country

The following table lists the available extra data fields.

Field Description
Extra_LATITUDE Latitude (north-south position)
Extra_LONGITUDE Longitude (east-west position)

The shorthand Extra_ can be used to specify all extra data fields.

Response Codes

HTTP status 200 (OK) will be returned for all requests that the service 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": "NO_MATCH",
  "StatusDetails": {
    "Description": "No match"
  }
}
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<Response>
  <Status>NO_MATCH</Status>
  <StatusDetails>
    <Description>No match</Description>
  </StatusDetails>
</Response>

Standard HTTP status codes are applied when the 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.