# GBG Loqate AU & NZ
## Our Products
### Reach every customer, anywhere
Address validation powered by the most accurate global location data. Deliver exceptional experiences to every customer, wherever they are located.
## Before you begin
You will need a Loqate Harmony Account to use our Platform services. You can register a free trial to get started.
{% embed url="" %}
### Integrations
We provide an ever-increasing range of pre-built integrations so you can plug in and verify addresses on your website in minutes.
{% content-ref url="/pages/KDuAfvena7K71mgxQPKh" %}
[Integrations](/loqate-harmony-api/integrations)
{% endcontent-ref %}
## Want to deep dive?
Dive a little deeper and start exploring our API specification to get an idea of everything that's possible with the API:
{% content-ref url="/pages/XDToHRYRamcXc2lgCcVP" %}
[API Specification](/loqate-harmony-api/api-specification)
{% endcontent-ref %}
# API Specification
Loqate Harmony API Specification
Dive into the specifics of each API endpoint by checking out our complete documentation.
## Authentication
{% content-ref url="/pages/pNp2vsPEQmfbnHPzvwgn" %}
[Authentication](/loqate-harmony-api/api-specification/authentication)
{% endcontent-ref %}
## Address
Everything related to addresses:
{% content-ref url="/pages/5ylNPVUFqxzdVXGnD8kk" %}
[Address Validation & Lookup](/loqate-harmony-api/api-specification/address/address-validation-and-lookup)
{% endcontent-ref %}
{% content-ref url="/pages/NjSnzxkY97PKcUdk71DB" %}
[Address by Geocode](/loqate-harmony-api/api-specification/address/address-by-geocode)
{% endcontent-ref %}
{% content-ref url="/pages/SMyFPz9o7daempZRizy7" %}
[Address Cleanse v1](/loqate-harmony-api/api-specification/deprecated/address-cleanse)
{% endcontent-ref %}
{% content-ref url="/pages/UXWaaXwtlSoE2mgsMj2M" %}
[Address Parse](/loqate-harmony-api/api-specification/address/address-parse)
{% endcontent-ref %}
## Suburb/Postcode
Everything related to suburb/postcode
{% content-ref url="/pages/Mr9dtVymAa9CIMaNAJMX" %}
[Suburb Lookup](/loqate-harmony-api/api-specification/suburb-postcode-search)
{% endcontent-ref %}
## Business
Everything related to businesses:
{% content-ref url="/pages/VXBpoC6mGSdnonIKt82D" %}
[Business Validation and Lookup](/loqate-harmony-api/api-specification/business-validation)
{% endcontent-ref %}
## Email
Everything related to email:
{% content-ref url="/pages/jwJ0VitVUkvsQsVvs8Y6" %}
[Email Validation v1.1](/loqate-harmony-api/api-specification/deprecated/email-validation)
{% endcontent-ref %}
## Phone
Everything related to phone:
{% content-ref url="/pages/HhGDGUFD3213kXUmce24" %}
[Phone Validation](/loqate-harmony-api/api-specification/phone-validation)
{% endcontent-ref %}
## Matching
Everything related to matching:
{% content-ref url="/pages/emtsa2Jjqsev8YDKAOOH" %}
[Matching](/loqate-harmony-api/api-specification/matching)
{% endcontent-ref %}
## Suppression
Everything related to suppression:
{% content-ref url="/pages/fuGJNCGtZNekucjBFZfV" %}
[Moved Suppression](/loqate-harmony-api/api-specification/moved-suppression)
{% endcontent-ref %}
{% content-ref url="/pages/pvsLqeiP0qlPD0XMwhZI" %}
[Deceased Suppression](/loqate-harmony-api/api-specification/deceased-suppression)
{% endcontent-ref %}
## NZ Property Title
Everything related to Property Title:
{% content-ref url="/pages/eoloPzOULQhUhy5iIsMw" %}
[NZ Property Title](/loqate-harmony-api/api-specification/nz-property-title)
{% endcontent-ref %}
# Authentication
Authentication is required when making calls to our RESTful webservices. The domain is required to match the host where the JavaScript code is used.
## API keys
We use basic authentication over secure http (HTTPS). Basic authentication is a method for an HTTP user agent (e.g. a web browser) to provide a user name and password when making a request. In our case, by using basic HTTP authentication, a request contains a header field in the form of `Authorization: Basic ` where `` is the base-64 encoded string of `:`.
## Allowlist domains
Customer who has implemented our service as front end, i.e. typically from a website using JavaScript will require API users with allowlisted domains. Allowlisting of the domains ensures that access to our service is not compromised and allows only certain domains to connect to our service.
Typically customer who has implemented our service in backend using Java, C#,PHP or Curl etc. will not require any referrer domains to be allowlisted as the back end implementation is already secured enough as the call happens from server side.
However some customers may require some additional layer of security to ensure their credentials are not compromised by other internal teams or external third party etc. In such cases domains can be allowlisted so that only the JavaScript code from those domains can make successful calls to our APIs.
API users and domain allowlisting can be done by the customer once they sign up for free Trial using [Allowlisting domains](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains)
# Address
Our market leading address solutions standardises, validates and enriches your address information.
## Our address solutions
#### Address Lookup & Validation
Global Address Validation and Lookup with market leading features, search capabilities powered by Global address data.
Perfect for onboarding, checkout and customer experience journeys.
{% content-ref url="/spaces/hp3nSGDGzW6K0AYaMW45/pages/5ylNPVUFqxzdVXGnD8kk" %}
[Address Validation & Lookup](/loqate-harmony-api/api-specification/address/address-validation-and-lookup)
{% endcontent-ref %}
#### Address Cleanse
Address Cleanse uses validates that address up to 100 address per call market leading features powered by Global address data.
Perfect for database, list, data migration and ongoing data quality programs.
{% content-ref url="/pages/UARVEOi9tVehNsPnPDPU" %}
[Address Cleanse](/loqate-harmony-api/api-specification/address/address-cleanse)
{% endcontent-ref %}
#### Reverse Geocoding / Address by Geocode
Address by Geocode (Reverse Geocoding) find an addresses using latitude and longitude co-ordinates for validate addresses within a radius.
{% content-ref url="/pages/NjSnzxkY97PKcUdk71DB" %}
[Address by Geocode](/loqate-harmony-api/api-specification/address/address-by-geocode)
{% endcontent-ref %}
#### Address Parse / Standardisation
Address Parse turns unstructured address data into a structured address object.
Great for data migrations/integrations, analytics when a validation is not required.
{% content-ref url="/pages/UXWaaXwtlSoE2mgsMj2M" %}
[Address Parse](/loqate-harmony-api/api-specification/address/address-parse)
{% endcontent-ref %}
# Address Validation & Lookup
Address lookup methods take partial or complete address information search against an address Source of Truth, returning validated and enriched address information.
To complete address validation requires using 2 API's each provide a specific purpose.
1. [**Find** ](#find)- Returns a list of valid addresses based on partial or complete address information.
2. [**Retrieve** ](#retrieve)- Using the 'Find id' returns the validated and enriched address information.
**Supported Countries:** All countries including Australia and New Zealand. See our [global data coverage](https://support.loqate.com/coverage-full/).
{% hint style="info" %}
**Looking for Address by Geocode or Reverse Geocoding?** [Click here](/loqate-harmony-api/api-specification/address/address-by-geocode#reverse-geocode-methods)
{% endhint %}
## Find
Lookup addresses using a partial or complete address information in a single line address field.
You can do further lookup using the `id` when the `Type` of the result was not `Address`.
HTTP `POST` will only process the **first** record in the request.
## GET /rest/v2/address/find
> International addresses lookup using a single-line input address
```json
{"openapi":"3.0.1","info":{"title":"Harmony RightAddress REST API","version":"2.13.0"},"tags":[{"name":"findAddress","description":"Single-line address lookup"}],"servers":[{"url":"https://hosted.mastersoftgroup.com/harmony","description":"Generated server url"}],"security":[{"rightaddress":[]}],"components":{"securitySchemes":{"rightaddress":{"type":"http","scheme":"basic"}},"schemas":{"AddressRestResponse":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESS","ERROR"]},"messages":{"type":"array","items":{"type":"string"}},"payload":{"type":"array","properties":{"sourceReduced":{"type":"boolean"},"empty":{"type":"boolean"},"first":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]},"last":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"items":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}}}},"AddressAu":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"locality":{"type":"string"},"state":{"type":"string"},"_type":{"type":"string"}}}]},"Address":{"required":["_type"],"type":"object","properties":{"fullAddress":{"type":"string"},"country":{"type":"string"},"postcode":{"type":"string"},"subLocality":{"type":"string"},"street2":{"type":"string"},"street":{"type":"string"},"streetNumber":{"type":"string"},"postal":{"type":"string"},"postalType":{"type":"string"},"postalNumber":{"type":"string"},"buildingName":{"type":"string"},"subdwelling":{"type":"string"},"eid":{"type":"string"},"lotNumber":{"type":"string"},"flatUnitNumber":{"type":"string"},"flatUnitType":{"type":"string"},"floorLevelNumber":{"type":"string"},"floorLevelType":{"type":"string"},"streetSuffix":{"type":"string"},"streetType":{"type":"string"},"streetName":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"id":{"type":"string"},"sourceOfTruth":{"type":"string"},"_type":{"type":"string"}},"discriminator":{"propertyName":"_type"}},"AddressIntl":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"district":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"_type":{"type":"string"}}}]},"AddressNz":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"rdNumber":{"type":"string"},"deliveredTo":{"type":"string"},"townCity":{"type":"string"},"suburb":{"type":"string"},"_type":{"type":"string"}}}]},"AddressV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"line3":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"}}}]},"InternalParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"}]},"ParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"PDPChangedItem":{"type":"object","properties":{"componentID":{"type":"string"},"actionType":{"type":"string","enum":["ADD","MODIFY","REMOVE","INFO"]},"affectedElement":{"type":"string"},"oldValue":{"type":"string"},"newValue":{"type":"string"}}},"ValidatedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"exception":{"type":"string"}}}]},"AddressIntlV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressIntl"}]},"InternalParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"}]},"ParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"ValidatedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"exception":{"type":"string"}}}]}}},"paths":{"/rest/v2/address/find":{"get":{"tags":["findAddress"],"summary":"International addresses lookup using a single-line input address","operationId":"findAddress","parameters":[{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"fullAddress","in":"query","required":true,"schema":{"type":"string"}},{"name":"sourceOfTruth","in":"query","required":false,"schema":{"type":"string"}},{"name":"id","in":"query","required":false,"schema":{"type":"string"}},{"name":"featureOptions","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRestResponse"}}}}}}}}}
```
## POST /rest/v2/address/find
> International addresses lookup using a single-line input address
```json
{"openapi":"3.0.1","info":{"title":"Harmony RightAddress REST API","version":"2.13.0"},"tags":[{"name":"findAddress","description":"Single-line address lookup"}],"servers":[{"url":"https://hosted.mastersoftgroup.com/harmony","description":"Generated server url"}],"security":[{"rightaddress":[]}],"components":{"securitySchemes":{"rightaddress":{"type":"http","scheme":"basic"}},"schemas":{"AddressRestRequest":{"type":"object","properties":{"payload":{"type":"array","properties":{"sourceReduced":{"type":"boolean"},"empty":{"type":"boolean"},"first":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]},"last":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"items":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"sourceOfTruth":{"type":"string","enum":["AUPAF","GNAF","AUSOTS","AUPOST","NZPAF","NZAD","CNAR","ADDRESS_EXCHANGE","RIG_AU","RIG_NZ","SENDRIGHT_SOA","RIG_AU_ID","RIG_NZ_ID","RDA","MDS","ASGS","SEIFA2011","VE_INTERNAL","VE_VERIFY","VE_ALL","CUSTOM_AU_1","CUSTOM_AU_2","CUSTOM_NZ_1","CUSTOM_NZ_2"]},"featureOptions":{"type":"object","additionalProperties":{"type":"string"}},"transactionID":{"type":"string"}},"description":"The get international geocode request body: \n- `country`: the name or ISO-2 or ISO-3 country code (case-insensitive). Most country names will be recognised but the use of the ISO country code is recommended. Example: 'GB'. \n- `fullAddress`: the location to geocode. This can be a postal code or place name. Example: '13 Westdyke Terrace, Elrick, WESTHILL, AB32 6JA'."},"AddressAu":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"locality":{"type":"string"},"state":{"type":"string"},"_type":{"type":"string"}}}]},"Address":{"required":["_type"],"type":"object","properties":{"fullAddress":{"type":"string"},"country":{"type":"string"},"postcode":{"type":"string"},"subLocality":{"type":"string"},"street2":{"type":"string"},"street":{"type":"string"},"streetNumber":{"type":"string"},"postal":{"type":"string"},"postalType":{"type":"string"},"postalNumber":{"type":"string"},"buildingName":{"type":"string"},"subdwelling":{"type":"string"},"eid":{"type":"string"},"lotNumber":{"type":"string"},"flatUnitNumber":{"type":"string"},"flatUnitType":{"type":"string"},"floorLevelNumber":{"type":"string"},"floorLevelType":{"type":"string"},"streetSuffix":{"type":"string"},"streetType":{"type":"string"},"streetName":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"id":{"type":"string"},"sourceOfTruth":{"type":"string"},"_type":{"type":"string"}},"discriminator":{"propertyName":"_type"}},"AddressIntl":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"district":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"_type":{"type":"string"}}}]},"AddressNz":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"rdNumber":{"type":"string"},"deliveredTo":{"type":"string"},"townCity":{"type":"string"},"suburb":{"type":"string"},"_type":{"type":"string"}}}]},"AddressV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"line3":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"}}}]},"InternalParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"}]},"ParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"PDPChangedItem":{"type":"object","properties":{"componentID":{"type":"string"},"actionType":{"type":"string","enum":["ADD","MODIFY","REMOVE","INFO"]},"affectedElement":{"type":"string"},"oldValue":{"type":"string"},"newValue":{"type":"string"}}},"ValidatedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"exception":{"type":"string"}}}]},"AddressIntlV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressIntl"}]},"InternalParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"}]},"ParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"ValidatedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"exception":{"type":"string"}}}]},"AddressRestResponse":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESS","ERROR"]},"messages":{"type":"array","items":{"type":"string"}},"payload":{"type":"array","properties":{"sourceReduced":{"type":"boolean"},"empty":{"type":"boolean"},"first":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]},"last":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"items":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}}}}}},"paths":{"/rest/v2/address/find":{"post":{"tags":["findAddress"],"summary":"International addresses lookup using a single-line input address","operationId":"findAddress_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRestRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRestResponse"}}}}}}}}}
```
{% hint style="info" %}
**Demo available here:** [**https://www.loqate.com/anz/address-validation/**](https://www.loqate.com/anz/address-validation/)\*\*\*\*
{% endhint %}
### Resource
```
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/find
```
### Request
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object.
We have a large amount of use case based performance tuning that can be done.
\*=required field
Name
Type
Example
Description
Payload
country*
string
AU
ISO-2 or ISO-3 country
fullAddress*
string
10 High
partial address information entered by end users.
id
string
AU1235
The id from previous request indicating request from groupedAddress
state
string
NSW
AU & NZ only. Filters to address response to the state
locality
string
Sydney CBD
AU & NZ only. Filters to address response to the locality. Often used with strictValidation = 0.
postcode
string
2000
AU & NZ only. Filters to address response to the postcode. Often used with strictValidation = 0.
sourceOfTruth
sourceOfTruth*
string
AUSOTS
Within AU & NZ specifies the desired dataset for your use case. Options:
AUS: "AUPAF", "GNAF", "AUSOTS","AUPOST"
NZ: "NZPAF", "NZAD", "CNAR"
featureOptions
singleLineHitNumber
integer
5 default 20
Maximum number of results returned from the lookup.
caseType
string
TITLE default UP
Case type for the returned addresses and components. LOW = lowercase, UP = UPPERCASE, TITLE = Title Case
moreSources
string
"AUPOST,NZAD"
Lookups additional Sources of Truth and combines results. Used in conjunction with sourceOfTruth to expand address reach.
displayGnafLot
string
("0"|"1") default 1
Determines if the lot information is displayed in addresses retrieved from GNAF.
suppressLot
string
("0"|"1") default 1
Suppresses Lot information when a street# is available in the address. If Street# is not in address then Lot information is displayed. Used when displayGnafLot = 1 and suppressLot = 1.
groupAddresses
string
("0"|"1") default 0
If "1", the service will try to collapse sub-dwelling addresses within the same primary address into a group to reduce clutter. Recommended for INTL addresses.
positionFilter
string
POSTAL ROOFTOP DOORSTOP SINGLE
AU Only. Default all
Array of filters to be applied to the lookup results. Used to control which addresses you have in your serviceable network.
Using the `id` you can call retrieve function see [Retrieve Derived Address](#retrieve-request-10-derived-address)
Find AU & NZ multi search
**Request 1**: lookup addresses with AU & NZ within one search
```json
{
"payload": [ { "country": "AU", "fullAddress": "10 george " } ],
"sourceOfTruth": "AUPAF",
"featureOptions": {"moreSources":"NZAD", "singleLineHitNumber": "5" }
}
```
Response of **Request 1**:
As AUPAF country AU is the prioritised source and this prioritises results. Both AU & NZ results are returned.
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "10 GEORGE CRES, CICCONE NT 0870",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|70509953"
},
{
"_type": "AddressIntlV2",
"fullAddress": "10 GEORGE ST, SEAFORTH QLD 4741",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|52620610"
},
{
"_type": "AddressIntlV2",
"fullAddress": "10 GEORGE TCE, JUNORTOUN VIC 3551",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|68882692"
},
{
"_type": "AddressIntlV2",
"fullAddress": "10 GEORGE STREET, PICTON 7220",
"attributes": {
"Type": "Address"
},
"id": "NZ|NZAD|450727"
},
{
"_type": "AddressIntlV2",
"fullAddress": "10 GEORGE STREET, BLENHEIM 7201",
"attributes": {
"Type": "Address"
},
"id": "NZ|NZAD|1592307"
}
]
}
```
Using the `id` you can call retrieve function
## Retrieve
Retrieves validated address for the supplied `id`using the [Find ](#find)method.
## GET /rest/v2/address/retrieve
> International addresses retrieve by id
```json
{"openapi":"3.0.1","info":{"title":"Harmony RightAddress REST API","version":"2.13.0"},"tags":[{"name":"retrieveAddress","description":"Address retrieve by id"}],"servers":[{"url":"https://hosted.mastersoftgroup.com/harmony","description":"Generated server url"}],"security":[{"rightaddress":[]}],"components":{"securitySchemes":{"rightaddress":{"type":"http","scheme":"basic"}},"schemas":{"AddressRestResponse":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESS","ERROR"]},"messages":{"type":"array","items":{"type":"string"}},"payload":{"type":"array","properties":{"sourceReduced":{"type":"boolean"},"empty":{"type":"boolean"},"first":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]},"last":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"items":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}}}},"AddressAu":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"locality":{"type":"string"},"state":{"type":"string"},"_type":{"type":"string"}}}]},"Address":{"required":["_type"],"type":"object","properties":{"fullAddress":{"type":"string"},"country":{"type":"string"},"postcode":{"type":"string"},"subLocality":{"type":"string"},"street2":{"type":"string"},"street":{"type":"string"},"streetNumber":{"type":"string"},"postal":{"type":"string"},"postalType":{"type":"string"},"postalNumber":{"type":"string"},"buildingName":{"type":"string"},"subdwelling":{"type":"string"},"eid":{"type":"string"},"lotNumber":{"type":"string"},"flatUnitNumber":{"type":"string"},"flatUnitType":{"type":"string"},"floorLevelNumber":{"type":"string"},"floorLevelType":{"type":"string"},"streetSuffix":{"type":"string"},"streetType":{"type":"string"},"streetName":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"id":{"type":"string"},"sourceOfTruth":{"type":"string"},"_type":{"type":"string"}},"discriminator":{"propertyName":"_type"}},"AddressIntl":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"district":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"_type":{"type":"string"}}}]},"AddressNz":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"rdNumber":{"type":"string"},"deliveredTo":{"type":"string"},"townCity":{"type":"string"},"suburb":{"type":"string"},"_type":{"type":"string"}}}]},"AddressV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"line3":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"}}}]},"InternalParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"}]},"ParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"PDPChangedItem":{"type":"object","properties":{"componentID":{"type":"string"},"actionType":{"type":"string","enum":["ADD","MODIFY","REMOVE","INFO"]},"affectedElement":{"type":"string"},"oldValue":{"type":"string"},"newValue":{"type":"string"}}},"ValidatedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"exception":{"type":"string"}}}]},"AddressIntlV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressIntl"}]},"InternalParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"}]},"ParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"ValidatedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"exception":{"type":"string"}}}]}}},"paths":{"/rest/v2/address/retrieve":{"get":{"tags":["retrieveAddress"],"summary":"International addresses retrieve by id","operationId":"retrieveAddress","parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"featureOptions","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRestResponse"}}}}}}}}}
```
## POST /rest/v2/address/retrieve
> International addresses retrieve by id
```json
{"openapi":"3.0.1","info":{"title":"Harmony RightAddress REST API","version":"2.13.0"},"tags":[{"name":"retrieveAddress","description":"Address retrieve by id"}],"servers":[{"url":"https://hosted.mastersoftgroup.com/harmony","description":"Generated server url"}],"security":[{"rightaddress":[]}],"components":{"securitySchemes":{"rightaddress":{"type":"http","scheme":"basic"}},"schemas":{"AddressRestRequest":{"type":"object","properties":{"payload":{"type":"array","properties":{"sourceReduced":{"type":"boolean"},"empty":{"type":"boolean"},"first":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]},"last":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"items":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"sourceOfTruth":{"type":"string","enum":["AUPAF","GNAF","AUSOTS","AUPOST","NZPAF","NZAD","CNAR","ADDRESS_EXCHANGE","RIG_AU","RIG_NZ","SENDRIGHT_SOA","RIG_AU_ID","RIG_NZ_ID","RDA","MDS","ASGS","SEIFA2011","VE_INTERNAL","VE_VERIFY","VE_ALL","CUSTOM_AU_1","CUSTOM_AU_2","CUSTOM_NZ_1","CUSTOM_NZ_2"]},"featureOptions":{"type":"object","additionalProperties":{"type":"string"}},"transactionID":{"type":"string"}},"description":"The get international geocode request body: \n- `country`: the name or ISO-2 or ISO-3 country code (case-insensitive). Most country names will be recognised but the use of the ISO country code is recommended. Example: 'GB'. \n- `fullAddress`: the location to geocode. This can be a postal code or place name. Example: '13 Westdyke Terrace, Elrick, WESTHILL, AB32 6JA'."},"AddressAu":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"locality":{"type":"string"},"state":{"type":"string"},"_type":{"type":"string"}}}]},"Address":{"required":["_type"],"type":"object","properties":{"fullAddress":{"type":"string"},"country":{"type":"string"},"postcode":{"type":"string"},"subLocality":{"type":"string"},"street2":{"type":"string"},"street":{"type":"string"},"streetNumber":{"type":"string"},"postal":{"type":"string"},"postalType":{"type":"string"},"postalNumber":{"type":"string"},"buildingName":{"type":"string"},"subdwelling":{"type":"string"},"eid":{"type":"string"},"lotNumber":{"type":"string"},"flatUnitNumber":{"type":"string"},"flatUnitType":{"type":"string"},"floorLevelNumber":{"type":"string"},"floorLevelType":{"type":"string"},"streetSuffix":{"type":"string"},"streetType":{"type":"string"},"streetName":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"id":{"type":"string"},"sourceOfTruth":{"type":"string"},"_type":{"type":"string"}},"discriminator":{"propertyName":"_type"}},"AddressIntl":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"district":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"_type":{"type":"string"}}}]},"AddressNz":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"rdNumber":{"type":"string"},"deliveredTo":{"type":"string"},"townCity":{"type":"string"},"suburb":{"type":"string"},"_type":{"type":"string"}}}]},"AddressV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"line3":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"}}}]},"InternalParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"}]},"ParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"PDPChangedItem":{"type":"object","properties":{"componentID":{"type":"string"},"actionType":{"type":"string","enum":["ADD","MODIFY","REMOVE","INFO"]},"affectedElement":{"type":"string"},"oldValue":{"type":"string"},"newValue":{"type":"string"}}},"ValidatedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"exception":{"type":"string"}}}]},"AddressIntlV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressIntl"}]},"InternalParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"}]},"ParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"ValidatedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"exception":{"type":"string"}}}]},"AddressRestResponse":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESS","ERROR"]},"messages":{"type":"array","items":{"type":"string"}},"payload":{"type":"array","properties":{"sourceReduced":{"type":"boolean"},"empty":{"type":"boolean"},"first":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]},"last":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"items":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}}}}}},"paths":{"/rest/v2/address/retrieve":{"post":{"tags":["retrieveAddress"],"summary":"International addresses retrieve by id","operationId":"retrieveAddress_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRestRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRestResponse"}}}}}}}}}
```
### Resource
```
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/retrieve
```
### Request
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
\*=required field
Name
Type
Example
Description
payload
id*
string
"AU|GNAF|GANSW705038278"
ID given within the payload of the Find API response.
featureOptions
caseType
string
"TITLE" default UP
Case type for the returned addresses and components. LOW = lowercase, UP = UPPERCASE, TITLE = Title Case
displayGnafLot
string
("0"|"1") default 1
Determines if the lot information is displayed in addresses retrieved from GNAF.
suppressLot
string
("0"|"1") default 1
Suppresses Lot information when a street# is available in the address. If Street# is not in address then Lot information is displayed. Used when displayGnafLot = 1 and suppressLot = 1.
exposeAttributes
Integer
(0-7)
Enriches the data with address related attributes depending on value. Options 0,1,2,3,4,5,6,7
### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object.
### Examples
All retrieves for all countries are made using the same method as above.
Our universal fields makes country mapping core address fields easy (see guide [address field mapping](/loqate-harmony-api/guides/best-practices/address-field-mappings).) Depending on country and dataset the response packages do change particularly in available attributes.
Retrieve validated: AUPAF
**Request 1:** Retrieve address AUPAF with Find ID
```json
{
"payload": [ { "id": "AU|AUPAF|48318069" } ],
"featureOptions":{"exposeAttributes":"1","caseType":"title"}
}
```
**Response to Request 1:** Includes DPID, Barcode and Address mapping
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ValidatedAddressAu",
"fullAddress": "20 Bond St, Maroubra NSW 2035",
"country": "Australia",
"postcode": "2035",
"street2": null,
"street": "Bond St",
"streetNumber": "20",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "",
"eid": null,
"lotNumber": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "St",
"streetName": "Bond",
"attributes": {
"ProvinceName": "New South Wales",
"CountryIso2": "AU",
"Barcode": "1301011122100122002030323310101232013",
"CountryIso3": "AUS",
"DPID": "48318069",
"City": "Maroubra",
"ProvinceCode": "NSW",
"Bsp": "010",
"PAFPosition": "Single"
},
"id": "AU|AUPAF|48318069",
"sourceOfTruth": "AUPAF",
"exception": null,
"state": "NSW",
"locality": "Maroubra"
}
]
}
```
Retrieve validated: AU GNAF
**Request 1**: retrieve addresses with GNAF Source of Truth that includes address records with Lot number suppressed when Street Number exists.
* `suppressLot = 1` is the featureOption used to suppress the lot number when street number exists.
* `displayGnafLot =1`is the featureOption that displays. 1=true. This is important for address that do not have street numbers.
* Lot number will still be displayed for the records that do not have street number. Australia only, use it with sourceOfTruth:GNAF/AUSOTS.
```json
{
"payload": [{"id": "AU|GNAF|GANSW705038278"}],
"featureOptions": { "exposeAttributes": "1", "suppressLot": "1","displayGnafLot":"1" }
}
```
Response of **Request 1**:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ValidatedAddressAu",
"fullAddress": "168 LOT STAFFORD DRIVE, KALARU NSW 2550",
"country": "Australia",
"postcode": "2550",
"street2": null,
"street": "LOT STAFFORD DRIVE",
"streetNumber": "168",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "",
"eid": null,
"lotNumber": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "DRIVE",
"streetName": "LOT STAFFORD",
"attributes": {
"GNAFGroupPID": "NSW2857737",
"GNAFPIDPosition": "SINGLE",
"ParcelID": "78/870178",
"CountryIso2": "AU",
"GNAFReliability": "2",
"CountryIso3": "AUS",
"GNAFConfidence": "2",
"GNAFLocalityPID": "loc26f98008abfe",
"Latitude": "-36.72255996",
"City": "KALARU",
"Longitude": "149.92348752",
"MeshblockId": "11250630000",
"ProvinceName": "NEW SOUTH WALES",
"GNAFPointPID": "GANSW705038278",
"GNAFPID": "GANSW705038278",
"ProvinceCode": "NSW",
"GeocodeLevel": "7"
},
"id": "AU|GNAF|GANSW705038278",
"sourceOfTruth": "GNAF",
"exception": null,
"state": "NSW",
"locality": "KALARU"
}
]
}
```
Retrieve validated: NZAD
**Request 3**: retrieve an New Zealand address from NZAD Source of Truth.
```json
{
"payload": [{"id": "NZ|NZAD|1154050"}],
"featureOptions": { "exposeAttributes": "1", "caseType": "TITLE" }
}
```
Response of **Request 3**:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ValidatedAddressNz",
"fullAddress": "Flat 20 30 Bond Street, Marton 4710",
"country": "New Zealand",
"postcode": "4710",
"street2": null,
"street": "Bond Street",
"streetNumber": "30",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "Flat 20",
"eid": null,
"lotNumber": "",
"flatUnitNumber": "20",
"flatUnitType": "Flat",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "Street",
"streetName": "Bond",
"attributes": {
"ParcelId": "3940629",
"CountryIso2": "NZ",
"address_type": "Urban",
"CountryIso3": "NZL",
"DPID": "1154050",
"regional_council_id": "8",
"Latitude": "-40.06211544305106",
"source": "Nzpost",
"City": "Marton",
"Longitude": "175.3759317179828",
"MeshblockId": "4013425",
"ProvinceName": "Manawatu-Wanganui Region",
"address_line2": "Marton 4710",
"address_line1": "20/30 Bond Street",
"regional_council_name": "Manawatu-Wanganui Region",
"ta_name": "Rangitikei District",
"XCoordinate": "1802635.01420514",
"ProvinceCode": "",
"ta_id": "38",
"YCoordinate": "5562643.58308705"
},
"id": "NZ|NZAD|1154050",
"sourceOfTruth": "NZAD",
"rdNumber": null,
"deliveredTo": "Y",
"exception": null,
"suburb": "",
"townCity": "Marton"
}
]
}
```
Retrieve validated: CNAR
**Request 3**: retrieve an New Zealand address from NZAD Source of Truth.
```json
{
"payload": [{ "id": "NZ|CNAR|10519716" , "country": "NZ"}]
}
```
Response of **Request 3**:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ValidatedAddressNz",
"fullAddress": "10 LIVERPOOL STREET, DARGAVILLE 0310",
"country": "New Zealand",
"postcode": "0310",
"street2": null,
"street": "LIVERPOOL STREET",
"streetNumber": "10",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "",
"eid": null,
"lotNumber": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "STREET",
"streetName": "LIVERPOOL",
"attributes": {
"meshblock_id_2013": "117100",
"CountryIso2": "NZ",
"y_nzmg": "6582583.0",
"complete_address": "10 LIVERPOOL STREET DARGAVILLE DARGAVILLE 0310",
"CountryIso3": "NZL",
"DPID": "665017",
"l_y_nzmg": "6582583.5",
"y_webmerc": "-4294452.442632699",
"Latitude": "-35.95515442",
"x_webmerc": "19354497.632800736",
"street_number_full": "10",
"ProvinceName": "",
"sa1_2018": "7001035",
"cnar_id": "10519716",
"l_x_webmerc": "19354497.632800736",
"x_nztm": "1677952.0",
"addr_full": "10 LIVERPOOL STREET",
"l_y_wgs84": "-35.9551506",
"l_y_webmerc": "-4294451.917305179",
"ParcelId": "4966960",
"y_nztm": "6020680.0",
"l_x_nzmg": "2588586.25",
"regional_council": "NORTHLAND REGION",
"sa2_2018": "109300",
"l_y_nztm": "6020680.5",
"deprivation_index": "8",
"City": "DARGAVILLE",
"road_id": "100000636",
"ta": "KAIPARA DISTRICT",
"Longitude": "173.8644104",
"MeshblockId": "4001981",
"l_x_wgs84": "173.8644104",
"area_unit": "504600",
"quintile": "4",
"x_nzmg": "2588586.0",
"ProvinceCode": "",
"l_x_nztm": "1677952.75"
},
"id": "NZ|CNAR|10519716",
"sourceOfTruth": "CNAR",
"rdNumber": null,
"exception": null,
"suburb": "DARGAVILLE",
"townCity": "DARGAVILLE"
}
]
}
```
Retrieve validated: UK (INTL)
**Request 1**: retrieve a United Kingdom address.
```json
{
"payload": [ { "id": "GB|RM|A|12799601|ENG" , "country": "GB"} ]
}
```
Response of **Request 1**:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "C & L Timberkits, Unit 100, North Mersey Business Centre, Woodward Road, Knowsley Industrial Park, LIVERPOOL, L33 7UY, UNITED KINGDOM",
"country": "United Kingdom",
"postcode": "L33 7UY",
"street2": "North Mersey Business Centre",
"street": "Woodward Road",
"streetNumber": "",
"postal": "",
"postalType": "",
"postalNumber": null,
"buildingName": "Unit 100",
"subdwelling": "",
"attributes": {
"Line4": "Knowsley Industrial Park",
"CountryIso2": "GB",
"Company": "C & L Timberkits",
"CountryIso3": "GBR",
"City": "Liverpool",
"DomesticId": "12799601",
"DataLevel": "Premise",
"ProvinceName": "Merseyside",
"Type": "Commercial",
"Language": "ENG",
"SortingNumber1": "29142",
"LanguageAlternatives": "ENG",
"Barcode": "(L337UY3ZH)",
"ProvinceCode": "",
"CountryIsoNumber": "826",
"Line1": "Unit 100",
"Line2": "North Mersey Business Centre",
"Line3": "Woodward Road",
"AdminAreaName": "Knowsley"
},
"id": "GB|RM|A|12799601|ENG",
"sourceOfTruth": null,
"district": "Knowsley Industrial Park",
"city": "Liverpool",
"province": "Merseyside"
}
]
}
```
Retrieve validated: USA (INTL)
**Request 1**: retrieve a United States of America address.
```json
{
"payload": [ { "id": "US|LP|B|113264667|100_ENG" , "country": "UK"} ]
}
```
Response of **Request 1**:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "100 Liverpool St, EAST BOSTON MA 02128-1907, UNITED STATES",
"country": "United States",
"postcode": "02128-1907",
"street2": "",
"street": "Liverpool St",
"streetNumber": "100",
"postal": "",
"postalType": "",
"postalNumber": null,
"buildingName": "",
"subdwelling": "",
"attributes": {
"CountryIso2": "US",
"CountryIso3": "USA",
"City": "East Boston",
"DomesticId": "113264667",
"DataLevel": "Premise",
"ProvinceName": "Massachusetts",
"Type": "Residential",
"Language": "ENG",
"LanguageAlternatives": "ENG",
"AdminAreaCode": "025",
"ProvinceCode": "MA",
"CountryIsoNumber": "840",
"Line1": "100 Liverpool St",
"AdminAreaName": "Suffolk"
},
"id": "US|LP|B|113264667|100_ENG",
"sourceOfTruth": null,
"district": "",
"city": "East Boston",
"province": "MA"
}
]
}
```
Retrieve validated: Aust Post Parcel Locker Only
**Request 1**: retrieve AUPOST addresses
```json
{
"payload": [ { "id": "AU|AUPOST|RED0010639" } ],
"featureOptions": { "exposeAttributes": "1"}
}
```
**Response to Request 1:**
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ValidatedAddressAu",
"fullAddress": "Red Street Posting Box, 10 George Street, CRANBOURNE VIC 3977",
"country": "Australia",
"postcode": "3977",
"street2": null,
"street": "George Street",
"streetNumber": "10",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "Red Street Posting Box",
"subdwelling": "",
"eid": null,
"lotNumber": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "Street",
"streetName": "George",
"attributes": {
"ProvinceName": "VICTORIA",
"CountryIso2": "AU",
"CountryIso3": "AUS",
"name": "Red Street Posting Box",
"address_line_1": "10 George Street",
"Latitude": "-38.098859",
"City": "CRANBOURNE",
"ProvinceCode": "VIC",
"id": "RED0010639",
"type": "RSPB",
"Longitude": "145.280717",
"record_type": "spb"
},
"id": "AU|AUPOST|RED0010639",
"sourceOfTruth": "AUPOST",
"exception": null,
"state": "VIC",
"locality": "CRANBOURNE"
}
]
}
```
Retrieve validated: Derived Address
**Request 1**: retrieve addresses with derived sub-premises enabled.
**Response to Request 1:**
When sub-premise is derived we respond with the validated information eg premise level information including additional field `attributes.UserInferred` that describes the derived sub-premises.
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ValidatedAddressAu",
"fullAddress": "100 St Johns Road, Cabramatta NSW 2166",
"country": "Australia",
"postcode": "2166",
"street2": null,
"street": "St Johns Road",
"streetNumber": "100",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "",
"eid": null,
"lotNumber": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "Road",
"streetName": "St Johns",
"attributes": {
"GNAFGroupPID": "Nsw2916968",
"GNAFPIDPosition": "Single",
"ParcelID": "5/806670",
"CountryIso2": "AU",
"GNAFReliability": "2",
"CountryIso3": "AUS",
"GNAFConfidence": "2",
"GNAFLocalityPID": "Loc49cb12b9ef21",
"Latitude": "-33.88892945",
"City": "Cabramatta",
"Longitude": "150.92317213",
"MeshblockId": "10264210000",
"UserInferred": "Unit 888",
"ProvinceName": "New South Wales",
"GNAFPointPID": "Gansw704282071",
"GNAFPID": "Gansw704282071",
"ProvinceCode": "NSW",
"GeocodeLevel": "7"
},
"id": "AU|GNAF|GANSW704282071|Unit 888",
"sourceOfTruth": "GNAF",
"exception": null,
"state": "NSW",
"locality": "Cabramatta"
}
]
}
```
# Address by Geocode
Reverse geocode or Address by Geocode methods take a pair of latitude and longitude coordinates as an input and return addresses information that match the search parameters.
## Reverse geocode methods
Reverse geocode methods take a pair of latitude and longitude coordinates as an input and return addresses information that match the search parameters.
| [reverseGeocode](#combined) | Lookup addresses using geocode input, which invokes [auNzReverseGeocode ](/loqate-harmony-api/api-specification/deprecated/address-v1#aunzreversegeocode)for Australia or New Zealand or [internationalReverseGeocode ](#international)for other countries. |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [internationalReverseGeocode](#international) | Lookup the nearest address or location using geocode input - for all countries including Australia and New Zealand. |
### reverseGeocode
Lookup addresses using the geocode input, invoking different method based on the identified country of the **first** geocode input.
It invokes [auNzReverseGeocode ](/loqate-harmony-api/api-specification/deprecated/address-v1#aunzreversegeocode)method for Australia or New Zealand country. For other countries, it invokes [internationalReverseGeocode](#international) method.
HTTP `POST` for [internationalReverseGeocode](#international) supports multiple records in the request, while [auNzReverseGeocode ](/loqate-harmony-api/api-specification/deprecated/address-v1#aunzreversegeocode)will only process the **first** record in the request.
#### Resource URL
```
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/reverseGeocode
```
#### Request
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `attributes` with `latitude` and `longitude` is required
* The `sourceOfTruth` is optional - for Australia and New Zealand only. The supported Source of Truths are GNAF, NZPAF, NZAD, CNAR (default is GNAF for Australia and NZPAF for New Zealand).
* The `featureOptions` is optional - for Australia and New Zealand only. The supported feature options are displayGnafLot, singleLineHitNumber (default 20), caseType, exposeAttributes, radius (default 50 for 50 meters radius).
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object.
{% hint style="success" %}
See [Address Field Mapping Gui](/loqate-harmony-api/guides/best-practices/address-field-mappings)[de](/loqate-harmony-api/guides/best-practices/address-field-mappings) for integration best practices.
{% endhint %}
#### Examples
**Request 1**: the first record in below request is an Australian geocode, the second record is a New Zealand geocode, and the rest are not Australia nor New Zealand geocodes.
```
{
"payload": [
{ "attributes": { "latitude": "-16.82082713", "longitude": "145.63726544" }},
{ "attributes": { "latitude": "-36.89131346840618", "longitude": "174.61055106781905" }},
{ "attributes": { "latitude": "57.1536", "longitude": "-2.3003" }},
{ "attributes": { "latitude": "45.69312", "longitude": "-73.92453" }}
],
"featureOptions": { "singleLineHitNumber": "2", "caseType": "UPPER","radius":"50" }
}
```
Response of **Request 1**: as the first record is identified as Australia country, it invokes [auNzReverseGeocode ](/loqate-harmony-api/api-specification/deprecated/address-v1#aunzreversegeocode)method which will only process the first record. There are 2 addresses found within 50 meters radius of the first geocode input.
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressAu",
"fullAddress": "LOT 810 1 MEEROO STREET, KURANDA QLD 4881",
"country": null,
"postcode": "4881",
"street2": null,
"street": "MEEROO STREET",
"streetNumber": "1",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "LOT 810",
"eid": "52F76415F832A4B586F7811CD67E54750D064606E46C4D8414C86833B2D59CD0",
"lotNumber": "810",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "STREET",
"streetName": "MEEROO",
"attributes": null,
"id": null,
"state": "QLD",
"locality": "KURANDA"
},
{
"_type": "AddressAu",
"fullAddress": "LOT 809 3 MEEROO STREET, KURANDA QLD 4881",
"country": null,
"postcode": "4881",
"street2": null,
"street": "MEEROO STREET",
"streetNumber": "3",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "LOT 809",
"eid": "26384A508C51D25CC97B59B8405AF029420BFD597482AFE79D075E31CEB08661",
"lotNumber": "809",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "STREET",
"streetName": "MEEROO",
"attributes": null,
"id": null,
"state": "QLD",
"locality": "KURANDA"
}
]
}
```
**Request 2**: the first record in below request is not an Australian nor New Zealand geocode.
```
{
"payload": [
{ "attributes": { "latitude": "57.1536", "longitude": "-2.3003" }},
{ "attributes": { "latitude": "45.69312", "longitude": "-73.92453" }},
{ "attributes": { "latitude": "-16.82082713", "longitude": "145.63726544" }},
{ "attributes": { "latitude": "-36.89131346840618", "longitude": "174.61055106781905" }},
],
"featureOptions": { "singleLineHitNumber": "2", "caseType": "UPPER","radius":"50" }
}
```
Response of **Request 2**: it invokes [internationalReverseGeocode](#international) method which will process all records in the request. The `featureOptions` is ignored when invoking [internationalReverseGeocode](#international) method.
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": null,
"country": "GB",
"postcode": "AB32",
"street2": null,
"street": "Westdyke Terrace",
"streetNumber": "9",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "57.153645",
"Longitude": "-2.300365",
"Distance": "0.0"
},
"id": null,
"district": null,
"city": "Westhill",
"province": "SCT"
},
{
"_type": "AddressIntl",
"fullAddress": null,
"country": "CA",
"postcode": "J7J",
"street2": null,
"street": "Rue Brault",
"streetNumber": "12770",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "45.693214",
"Longitude": "-73.9244",
"Distance": "0.0"
},
"id": null,
"district": null,
"city": "Mirabel",
"province": "QC"
},
{
"_type": "AddressIntl",
"fullAddress": null,
"country": "AU",
"postcode": "4881",
"street2": null,
"street": "Thongon Street",
"streetNumber": "19",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "-16.820555",
"Longitude": "145.636826",
"Distance": "0.0"
},
"id": null,
"district": null,
"city": "Cairns",
"province": "Queensland"
},
{
"_type": "AddressIntl",
"fullAddress": null,
"country": "NZ",
"postcode": "0612",
"street2": null,
"street": "San Valentino Drive",
"streetNumber": "61",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "-36.891792",
"Longitude": "174.611069",
"Distance": "0.0"
},
"id": null,
"district": null,
"city": "Auckland",
"province": "North Island"
}
]
}
```
### internationalReverseGeocode
Lookup the nearest address or location using the WGS84 geocode input. It also returns attributes for WGS84 Latitude and Longitude coordinates of the location and the Distance in KM from the CentrePoint to this address.
It supports all countries including Australia and New Zealand. HTTP `POST` supports multiple records in the request.
**Note:** for reverse geocoding Australia and New Zealand addresses, you can use [auNzReverseGeocode ](/loqate-harmony-api/api-specification/deprecated/address-v1#aunzreversegeocode)method which will return more information.
GET[​/rest​/intl​/reverseGeocode](https://developer.mastersoftgroup.com/harmony/api/method/reverse-geocode.html#/internationalReverseGeocode/reverseGeocodeIntlUsingGET)Lookup the nearest address or location to the given latitude/longitude coordinates - international (AU/NZ and other countries)POST[​/rest​/intl​/reverseGeocode](https://developer.mastersoftgroup.com/harmony/api/method/reverse-geocode.html#/internationalReverseGeocode/reverseGeocodeIntlUsingPOST)Lookup the nearest address or location to the given latitude/longitude coordinates - international (AU/NZ and other countries)
#### Resource URL
```
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/intl/reverseGeocode
```
#### Request
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object:
* The `attributes` with WGS84 `latitude` and `longitude` is required
```
{
"payload": [
{ "attributes": { "latitude": "-33.86440996", "longitude": "151.20828704" } },
{ "attributes": { "latitude": "57.1536", "longitude": "-2.3003" } }
]
}
```
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": null,
"country": "AU",
"postcode": "2000",
"street2": null,
"street": "Abercrombie Lane",
"streetNumber": "1",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "-33.864185",
"Longitude": "151.208145",
"Distance": "0.0"
},
"id": null,
"district": null,
"city": "Sydney",
"province": "New South Wales"
},
{
"_type": "AddressIntl",
"fullAddress": null,
"country": "GB",
"postcode": "AB32",
"street2": null,
"street": "Westdyke Terrace",
"streetNumber": "9",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "57.153645",
"Longitude": "-2.300365",
"Distance": "0.0"
},
"id": null,
"district": null,
"city": "Westhill",
"province": "SCT"
}
]
}
```
# Address Cleanse
Verifies, corrects and enriches address data to the highest level of precision and confidence, globally and at scale
Validate 1 to 100 addresses per requests.
Our flexible service allows:
1. Up to 100 addresses per request
2. Each Address can be from any country.
3. Each Address can have its own schema. Reducing effort and improving results.
## Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/cleanse
```
## Request
Upto 100 addresses can be validated per request from any country with many input schemas.
This flexibility in our service enables you to call our service using your list schema to achieve optimal results.
```json
{
"payload":
[
{
"buildingName": "string",
"country": "string",
"eid": "string",
"flatUnitNumber": "string",
"flatUnitType": "string",
"floorLevelNumber": "string",
"floorLevelType": "string",
"fullAddress": "string",
"id": "string",
"lotNumber": "string",
"postal": "string",
"postalNumber": "string",
"postalType": "string",
"postcode": "string",
"street": "string",
"street2": "string",
"streetName": "string",
"streetNumber": "string",
"streetSuffix": "string",
"streetType": "string",
"subLocality": "string",
"subdwelling": "string",
"city": "string",
"line1": "string",
"line2": "string",
"line3": "string",
"province": "string",
"sourceOfTruth": "string"
}
],
"featureOptions":
{
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}
```
### Example payload schemas
We've designed our API with flexible payload schemas. Meaning you can match the way you have stored the data into the optimal schema for our service.
Reducing your overall integration effort whilst improving performance of the service.
We recommend choosing the below schemas for each address you need cleansed.
{% hint style="warning" %}
Please ensure the information is **not duplicated** in any of the address lines to achieve better validation results.
{% endhint %}
Schema 1: Line 1, Line 2, City, Province, Postcode, Country
{
"payload": [
{
"country": "AU",
"line1": "1/37A Tahnee Street",
"line2":"",
"city": "Sanctuary Point",
"province":"NSW",
"postcode": "2540"
},
{
"country":"US",
"line1":"101 California Ave",
"line2":"Unit @@1101",
"city":"Santa Mon",
"province":" CA",
"postcode":"90403-3523"
}
],
"featureOptions": {
"caseType": "UP",
"exposeAttributes":1,
"exposeChanges":"0",
"cleanseEnhance":0, // set to 1 for Premium Cleanse Service
"cleanseGeocode":0, // set to 1 for Premium Cleanse Service
"cleanseCertify":0 // set to 1 for Premium Cleanse Service
}
}
Schema 2: Line1, Line2, Line3
```json
{
"payload": [
{
"country": "AU",
"line1": "Unit 1",
"line2":"37A Tahnee Street",
"line3":"Sanctuary Point NSW 2540"
},
{
"country": "AU",
"line1": "Unit 1 37A Tahnee Street",
"line2":"",
"line3":"Sanctuary Point NSW 2540"
},
{
"country":"US",
"line1":"101 California Ave",
"line2":"Unit @@1101",
"line3":"Santa Monica, CA 90403-3523"
}
],
"featureOptions": {
"caseType": "UP",
"exposeAttributes":1,
"exposeChanges":"0",
"cleanseEnhance":0, // set to 1 for Premium Cleanse Service
"cleanseGeocode":0, // set to 1 for Premium Cleanse Service
"cleanseCertify":0 // set to 1 for Premium Cleanse Service
}
}
```
Schema 3: Full Address (Highest level detail)
```json
{
"payload": [
{
"country": "AU",
"fullAddress": "SE 202, 220 George Street, Syndey 2000",
"sourceOfTruth": "AUSOTS"
},
{
"country": "AU",
"fullAddress": "3 Orara Street, waitara nsw",
"sourceOfTruth": "AUSOTS"
},
{
"country":"US",
"fullAddress":"101 California Ave Unit @@1101 Santa Monica, CA 90403-3523"
}
],
"featureOptions":
{
"caseType": "UP",
"exposeAttributes":1,
"exposeChanges":"0",
"cleanseEnhance":0, // set to 1 for Premium Cleanse Service
"cleanseGeocode":0, // set to 1 for Premium Cleanse Service
"cleanseCertify":0 // set to 1 for Premium Cleanse Service
}
}
```
Schema 4: Each component (Lowest level detail)
{
"payload": [
{
"country": "AU",
"subdwelling": "SE 202",
"streetNumber": "220",
"streetName": "George",
"streetType": "Street",
"city": "Syndey",
"province": "NSW",
"postcode": "2000"
},
{
"country": "US",
"subdwelling": "Unit @@1101",
"streetNumber": "101",
"streetName": "California",
"streetType": "Ave",
"city": "Santa Monica",
"province":"CA",
"postcode": "90403-3523"
}
],
"featureOptions":
{
"caseType": "UP",
"exposeAttributes":1,
"exposeChanges":"0",
"cleanseEnhance":0, // set to 1 for Premium Cleanse Service
"cleanseGeocode":0, // set to 1 for Premium Cleanse Service
"cleanseCertify":0 // set to 1 for Premium Cleanse Service
}
}
Schema for USA Postal Certified
Using cleanseCertify feature option with US addresses mandates the input address presentation to be entered in the following recommended formats for best match validation results.
{
"payload": [
{
"country":"US",
"line1":"101 California Ave",
"line2":"Unit #1101",
"line3":"Santa Monica, CA 90403-3523"
},
{
"country":"US",
"line1":"101 California Ave",
"line2":"Unit 1101",
"city":"Santa Monica",
"province":"CA",
"postcode":"90403-3523"
},
],
"featureOptions": {
"cleanseCertify":1 // set to 1 for Premium Cleanse Service
}
}
Line 1: is a representation of address fields usually house sub-dwellings, street numbers, street names, buildingName etc. This is usually determined by how you have data stored.
Line 2: is a representation of address fields usually additional information not contained in Line 1 such as suite numbers or floor information or subdwellings (not contained in Line 1). This is usually determined by how you have data stored.
Line 3: is a representation of address fields usually around city, province, suburbs/locality for example "suburb postcode region".
**Note:** Please ensure the information populated in city/province/postcode is not duplicated in any of the address lines to achieve better validation results.
### Service Options
Address Cleanse V2 API leverages both Standard and Premium Address Cleanse services.
#### **Standard Cleanse Service:**
The validation data set for standard cleanse service is using our default datasets (AU: GNAF, NZ: NZPAF, INTL: INTL Standard. By default the API is set to Standard services meaning you do not need to specify within the API requests.
```json
"featureOptions":
{
"cleanseEnhance":0,
"cleanseGeocode":0,
"cleanseCertify":0
}
```
#### **Premium Cleanse Service:**
This service provides access to advanced cleanse functions.
This allows the input request to pass on specific sourceOfTruth for AU, NZ addresses and allows to enhance the international data by setting the featureOptions to 1.
To get INTL geocodes requires "cleanseGeocode":1.
Utilizing cleanse featureOptions requires access. To get access contact a member of the team.
```json
// Enabling Premium Cleanse Service
"featureOptions":
{
"cleanseEnhance":1,
"cleanseGeocode":1,
"cleanseCertify":1
}
```
#### Configurations
Name
type
example
sourceOfTruth
string
defaults
AU: GNAF
NZ: NZPAF
INTL: INTL
Premium service only.
Defines selection of premium datasets being used to Cleanse the data.
caseType
string
TITLE, default empty
caseType for returned address components and attributes. LOW = lowercase, UP = UPPERCASE, TITLE = Title Case
exposeAttributes
Integer
("0"|"1"|"7") default 1
AU only.
Enriches the data with address related attributes depending on value. Options 0,1,7
exposeChanges
Integer
("0"|"1") default 0
AU NZ only.
Determines whether to include PDP change items in response.
cleanseEnhance
boolean
("0"|"1") default 0
Premium service only.
This option when set to 1 enhances AU NZ data with additional data attributes based on sourceOfTruth set in the input.
AU: AUPAF, AUSOTS
NZ: NZAD
For International addresses this option will determine the Enhanced data pack to be used based on the country input in the request.
cleanseCertify
boolean
("0"|"1") default 0
Premium service only.
International only.
This option when set to 1 uses the country input to determine which certification data set to be used for international address validation.
cleanseGeocode
boolean
("0"|"1") default 0
Premium service only.
International only.
This option when set to 1 returns geocode information for international addresses.
## Response
{% hint style="success" %}
See [Address Field Mapping Gui](/loqate-harmony-api/guides/best-practices/address-field-mappings)[de](/loqate-harmony-api/guides/best-practices/address-field-mappings) for integration best practices.
{% endhint %}
### Response of Basic Cleanse Service
The response body is an [AddressRestResponse ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse)object:
Basic Response: Australia
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ParsedAddressAu",
"fullAddress": "37A TAHNEE STREET,SANCTUARY POINT NSW 2540",
"country": "AUSTRALIA",
"postcode": "2540",
"subLocality": "",
"street2": "",
"street": "TAHNEE STREET",
"streetNumber": "37A",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "1",
"eid": null,
"lotNumber": null,
"flatUnitNumber": "1",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "STREET",
"streetName": "TAHNEE",
"attributes": {
"AddressMessage": "POINT",
"AddressQuality": "9",
"City": "SANCTUARY POINT",
"CountryIso2": "AU",
"CountryIso3": "AUS",
"CountryIsoNumber": "036",
"GeocodeLevel": "7",
"GNAFConfidence": "2",
"GNAFGroupPID": "NSW2928419",
"GNAFLocalityPID": "LOCFFAAAEA80667",
"GNAFPID": "GANSW720384012",
"GNAFPIDPosition": "SINGLE",
"GNAFPointPID": "GANSW720384012",
"GNAFReliability": "2",
"is_principal": "P",
"Latitude": "-35.09635821",
"Longitude": "150.61885685",
"MeshblockId": "11221970000",
"MeshBlockID2016": "11205649900",
"MeshBlockID2021": "11221970000",
"ParcelID": "1/SP103571",
"ProvinceCode": "NSW",
"ProvinceName": "NSW",
"UserInferred": "1"
},
"id": null,
"careOf": "",
"exception": null,
"unknown": "",
"changedItems": [
{
"componentID": "GNAFValidation",
"actionType": "INFO",
"affectedElement": "PointSubdwellingAddress",
"oldValue": "",
"newValue": ""
},
{
"componentID": "GNAFValidation",
"actionType": "INFO",
"affectedElement": "RecordMatch",
"oldValue": "",
"newValue": "POINT"
},
.........
],
"state": "NSW",
"locality": "SANCTUARY POINT"
}
]
}
```
Basic Response: New Zealand
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ParsedAddressNz",
"fullAddress": "FLAT 1F, 1C QUEEN MARY AVENUE, EPSOM, AUCKLAND 1023",
"country": "NEW ZEALAND",
"postcode": "1023",
"subLocality": "",
"street2": "",
"street": "QUEEN MARY AVENUE",
"streetNumber": "1C",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "L 1 FLAT 1F",
"eid": null,
"lotNumber": null,
"flatUnitNumber": "1f",
"flatUnitType": "FLAT",
"floorLevelNumber": "1",
"floorLevelType": "L",
"streetSuffix": "",
"streetType": "AVENUE",
"streetName": "QUEEN MARY",
"attributes": {
"AddressQuality": "9",
"AddressType": "URBAN",
"City": "AUCKLAND",
"CountryIso2": "NZ",
"CountryIso3": "NZL",
"CountryIsoNumber": "554",
"DPID": "3074094",
"GeocodeLevel": "2",
"Latitude": "-36.892132",
"Longitude": "174.774021",
"MatchedRule": "NZPAF_URBAN_ADDRESS: NAME_BASED_MATCH_RULE(EXACT_MATCH)",
"MeshblockId": "4001695",
"NZMapGrid": "2668501 6477320",
"NZTM": "1758075.229551 5915624.334052",
"ParcelId": "4801242",
"PostalID": "3074094",
"ProvinceCode": "",
"ProvinceName": "",
"UserInferred": "L 1",
"XCoordinate": "2668501",
"XNztm": "1758075.229551",
"YCoordinate": "6477320",
"YNztm": "5915624.334052"
},
"id": null,
"rdNumber": "",
"careOf": "",
"exception": null,
"unknown": "",
"changedItems": null,
"suburb": "EPSOM",
"townCity": "AUCKLAND"
}
]
}
```
Basic Response: International
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "101 CALIFORNIA AVE UNIT 1101,SANTA MONICA CA 90403-3523",
"country": "UNITED STATES",
"postcode": "90403-3523",
"street2": null,
"street": "CALIFORNIA AVE",
"streetNumber": "101",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": "UNIT 1101",
"attributes": {
"CountryIso2": "US",
"PremiseNumber": "101",
"HyphenClass": "C",
"CountryIso3": "USA",
"DeliveryAddress": "101 CALIFORNIA AVE UNIT 1101",
"City": "SANTA MONICA",
"Sequence": "1",
"AVC": "V55-I55-P8-099",
"PostalCodeSecondary": "3523",
"DeliveryAddress1": "101 CALIFORNIA AVE UNIT 1101",
"ProvinceName": "CA",
"SubAdministrativeArea": "LOS ANGELES",
"AQI": "B",
"ProvinceCode": "CA",
"CountryIsoNumber": "840",
"PostalCodePrimary": "90403",
"Line1": "101 CALIFORNIA AVE UNIT 1101",
"Line2": "SANTA MONICA CA 90403-3523",
"MatchRuleLabel": "1",
"SubBuildingLeadingType": "UNIT"
},
"id": null,
"district": null,
"city": "SANTA MONICA",
"province": "CA"
}
]
}
```
### Response of Premium Cleanse Service
The response body is an [AddressRestResponse ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse)object:
Attributes for Australia and NewZealand address samples may vary based on the input sourceOfTruth chosen.
{% hint style="info" %}
**Reduce integration effort**. See [Address Field Mappings](/loqate-harmony-api/guides/best-practices/address-field-mappings) to use the Universal Response objects (same fields in every response).
{% endhint %}
Premium Response: Australia
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ParsedAddressAu",
"fullAddress": "37 TAHNEE ST,SANCTUARY POINT NSW 2540",
"country": "AUSTRALIA",
"postcode": "2540",
"subLocality": "",
"street2": "",
"street": "TAHNEE ST",
"streetNumber": "37",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "UNIT 1",
"eid": null,
"lotNumber": null,
"flatUnitNumber": "1",
"flatUnitType": "UNIT",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "ST",
"streetName": "TAHNEE",
"attributes": {
"Accuracy": "PPM",
"AddressQuality": "9",
"advertising_mail_ind": "N",
"Barcode": "1301011211001001012110322111221321013",
"Bsp": "020",
"City": "SANCTUARY POINT",
"CountryIso2": "AU",
"CountryIso3": "AUS",
"CountryIsoNumber": "036",
"deliver_mail_ind": "Y",
"DPID": "54031173",
"non_residential_ind": "N",
"PAFPosition": "SINGLE",
"PostalID": "54031173",
"PostalIDPosition": "SINGLE",
"ProvinceCode": "NSW",
"ProvinceName": "NSW",
"residential_ind": "Y",
"UserInferred": "UNIT 1"
},
"id": null,
"careOf": "",
"exception": null,
"unknown": "",
"changedItems": [
{
"componentID": "AMASHAVE",
"actionType": "INFO",
"affectedElement": "PointSubdwellingAddress",
"oldValue": "",
"newValue": ""
},
{
"componentID": "AMASHAVE",
"actionType": "MODIFY",
"affectedElement": "PostalId",
"oldValue": "00000000",
"newValue": "54031173"
},
......
],
"state": "NSW",
"locality": "SANCTUARY POINT"
}
]
}
```
Premium Response: New Zealand
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ParsedAddressNz",
"fullAddress": "1C QUEEN MARY AVENUE, EPSOM, AUCKLAND 1023",
"country": "NEW ZEALAND",
"postcode": "1023",
"subLocality": "",
"street2": "",
"street": "QUEEN MARY AVENUE",
"streetNumber": "1C",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "L 1 FLAT 1F",
"eid": null,
"lotNumber": null,
"flatUnitNumber": "1f",
"flatUnitType": "FLAT",
"floorLevelNumber": "1",
"floorLevelType": "L",
"streetSuffix": "",
"streetType": "AVENUE",
"streetName": "QUEEN MARY",
"attributes": {
"AddressQuality": "9",
"AddressType": "URBAN",
"City": "AUCKLAND",
"CountryIso2": "NZ",
"CountryIso3": "NZL",
"CountryIsoNumber": "554",
"DeliveredTo": "N",
"DPID": "3663896",
"ExtraAddressLine1": "1C QUEEN MARY AVENUE",
"ExtraAddressLine2": "EPSOM",
"ExtraAddressLine3": "AUCKLAND 1023",
"GeocodeLevel": "1",
"Latitude": "-36.8920929147149",
"Longitude": "174.77399503296274",
"MatchedRule": "NZPAF_URBAN_ADDRESS: NAME_BASED_MATCH_RULE(EXACT_MATCH)",
"MeshblockId": "4001695",
"NZMapGrid": "2668499 6477324",
"NZTM": "1758072.99109137 5915628.69698302",
"ParcelId": "4801242",
"PostalID": "3663896",
"ProvinceCode": "",
"ProvinceName": "AUCKLAND REGION",
"RegionalCouncilId": "2",
"RegionalCouncilName": "AUCKLAND REGION",
"Source": "NZPOST",
"TaId": "76",
"TaName": "AUCKLAND",
"UserInferred": "L 1 FLAT 1F",
"XCoordinate": "2668499",
"XNztm": "1758072.99109137",
"YCoordinate": "6477324",
"YNztm": "5915628.69698302"
},
"id": null,
"rdNumber": "",
"deliveredTo": "N",
"careOf": "",
"exception": null,
"unknown": "",
"changedItems": [
{
"componentID": "CaseConversion",
"actionType": "MODIFY",
"affectedElement": "Address Line",
"oldValue": "1C QUEEN MARY AVENUE, EPSOM, AUCKLAND 1023",
"newValue": "1c Queen Mary Avenue, Epsom, Auckland 1023"
},
{
"componentID": "CaseConversion",
"actionType": "MODIFY",
"affectedElement": "Street Number",
"oldValue": "1C",
"newValue": "1c"
},
...............
],
"suburb": "EPSOM",
"townCity": "AUCKLAND"
}
]
}
```
Attributes for International addresses may vary based on the cleanseXXX feature options chosen.
Premium Response: International with cleanseCertify set to 1.:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "101 CALIFORNIA AVE UNIT 1101,SANTA MONICA CA 90403-3523",
"country": "UNITED STATES",
"postcode": "90403-3523",
"street2": null,
"street": "CALIFORNIA AVE",
"streetNumber": "101",
"postal": null,
"postalType": null,
"postalNumber": "",
"buildingName": null,
"subdwelling": "UNIT 1101",
"attributes": {
"CountryIso2": "US",
"eLOTNumber": "0070",
"CongressionalDistrict": "36",
"CountryIso3": "USA",
"eLOTCode": "A",
"DropCount": "",
"DropSiteIndicator": " ",
"AutoZoneIndicator": "D",
"DeliveryAddress1": "101 CALIFORNIA AVE UNIT 1101",
"BusinessIndicator": " ",
"Footnotes": "N#",
"OtherIndicator": "",
"PostalCodeSecondaryRangeHigh": "3523",
"CarrierRoute": "C030",
"LACSLinkIndicator": " ",
"AQI": "B",
"DPVConfirmedIndicator": "Y",
"CountryIsoNumber": "840",
"CentralizedIndicator": "",
"PMBType": "",
"CurbIndicator": "",
"DPVLACSIndicator": " ",
"PrimaryNumRangeLow": "0000000101",
"ReturnCode": "31",
"PostalCodeSecondaryRangeLow": "3523",
"VacantIndicator": "N",
"City": "SANTA MONICA",
"Sequence": "1",
"AVC": "V55-I55-P8-097",
"PostalCodeSecondary": "3523",
"DependentLocality": "",
"FalsePositiveIndicator": " ",
"SUITELinkFootnote": "",
"SecondaryNumRangeCode": "B",
"NDCBUIndicator": "",
"ThoroughfarePreDirection": "",
"ThoroughfareTrailingType": "AVE",
"PMBNumber": "",
"PrimaryNumRangeCode": "O",
"Organization": "",
"PremiseNumber": "101",
"SecondaryNumRangeLow": "00001004",
"PrimaryNumRangeHigh": "0000000101",
"DeliveryAddress": "101 CALIFORNIA AVE UNIT 1101",
"ThrowbackIndicator": "N",
"ResidentialDelivery": "Y",
"CheckDigit": "8",
"ProvinceName": "CA",
"CMRAIndicator": "N",
"DeliveryPointBarCode": "768",
"RecordType": "H",
"NoStatIndicator": "N",
"SecondaryAddressLine": "SANTA MONICA CA 90403-3523",
"PostBoxType": "",
"PostalCodePrimary": "90403",
"DPVFootnotes": "AABB",
"FIPSCountyCode": "037",
"EducationalIndicator": " ",
"SecondaryNumRangeHigh": "00001102",
"PrimaryAddressLine": "101 CALIFORNIA AVE UNIT 1101",
"Finance": "056978",
"SeasonalIndicator": " ",
"ThoroughfarePostDirection": "",
"SubAdministrativeArea": "LOS ANGELES",
"DefaultFlag": " ",
"ProvinceCode": "CA",
"LACSLinkCode": "",
"Line1": "101 CALIFORNIA AVE UNIT 1101",
"Line2": "SANTA MONICA CA 90403-3523",
"SubBuildingLeadingType": "UNIT"
},
"id": null,
"district": null,
"city": "SANTA MONICA",
"province": "CA"
}
]
}
```
Premium Response: International with cleanseEnhance set to 1.
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "101 CALIFORNIA AVE UNIT 1101,SANTA MONICA CA 90403-3523",
"country": "UNITED STATES",
"postcode": "90403-3523",
"street2": null,
"street": "CALIFORNIA AVE",
"streetNumber": "101",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": "UNIT 1101",
"attributes": {
"CensusClassCode": "C1",
"CountryIso2": "US",
"PremiseNumber": "101",
"CountryIso3": "USA",
"DeliveryAddress": "101 CALIFORNIA AVE UNIT 1101",
"AdministrativeAreaISO2": "US-CA",
"DeliveryAddress1": "101 CALIFORNIA AVE UNIT 1101",
"ProvinceName": "CA",
"TimeZone_DST": "-07:00",
"AQI": "B",
"CountryIsoNumber": "840",
"PostalCodePrimary": "90403",
"GNISFeatureID": "2411825",
"CensusIndicator": "LOCALITY",
"HyphenClass": "C",
"City": "SANTA MONICA",
"Sequence": "1",
"AVC": "V55-I55-P8-099",
"PostalCodeSecondary": "3523",
"CensusCode": "70000",
"TimeZone_UTC": "-08:00",
"SubAdministrativeArea": "LOS ANGELES",
"ProvinceCode": "CA",
"MetropolitanDivision": "LOS ANGELES-LONG BEACH-GLENDALE, CA=31084",
"Line1": "101 CALIFORNIA AVE UNIT 1101",
"CBSAMetropolitanStatisticalArea": "LOS ANGELES-LONG BEACH-ANAHEIM, CA=31080",
"TimeZone_Name": "PACIFIC STANDARD TIME",
"Line2": "SANTA MONICA CA 90403-3523",
"MatchRuleLabel": "1 D1 D1 D1",
"SubBuildingLeadingType": "UNIT"
},
"id": null,
"district": null,
"city": "SANTA MONICA",
"province": "CA"
}
]
}
```
Premium Response: International with cleanseGeocode set to 1.
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "101 CALIFORNIA AVE UNIT 1101,SANTA MONICA CA 90403-3523",
"country": "UNITED STATES",
"postcode": "90403-3523",
"street2": null,
"street": "CALIFORNIA AVE",
"streetNumber": "101",
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": "UNIT 1101",
"attributes": {
"CountryIso2": "US",
"PremiseNumber": "101",
"HyphenClass": "C",
"CountryIso3": "USA",
"DeliveryAddress": "101 CALIFORNIA AVE UNIT 1101",
"Latitude": "34.018630",
"City": "SANTA MONICA",
"Sequence": "1",
"Longitude": "-118.502740",
"AVC": "V55-I55-P8-099",
"PostalCodeSecondary": "3523",
"DeliveryAddress1": "101 CALIFORNIA AVE UNIT 1101",
"ProvinceName": "CA",
"GeoAccuracy": "P4",
"SubAdministrativeArea": "LOS ANGELES",
"AQI": "B",
"GeoDistance": "0.0",
"ProvinceCode": "CA",
"CountryIsoNumber": "840",
"PostalCodePrimary": "90403",
"Line1": "101 CALIFORNIA AVE UNIT 1101",
"Line2": "SANTA MONICA CA 90403-3523",
"MatchRuleLabel": "1",
"SubBuildingLeadingType": "UNIT"
},
"id": null,
"district": null,
"city": "SANTA MONICA",
"province": "CA"
}
]
}
```
### Exception Message
**Failed to Parse:**
Exception message for AU NZ "failed to parse record" looks like the following.
```
"Exception": "H112 : No pattern matched for this input - VRI BUILDING BLDG 403 30 FLEMINGTON ROAD, PARKVILLE VIC 3052. Check for punctuation errors, duplicate fields, incorrect input format and incorrect input data."
```
Exception Response: Australia and NewZealand
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressV2",
"fullAddress": "VRI BUILDING BLDG 403 30 FLEMINGTON ROAD, PARKVILLE VIC 3052",
"country": "AU",
"attributes": {
"Exception": "H112 : No pattern matched for this input - VRI BUILDING BLDG 403 30 FLEMINGTON ROAD, PARKVILLE VIC 3052. Check for punctuation errors, duplicate fields, incorrect input format and incorrect input data."
}
},
{
"_type": "AddressV2",
"fullAddress": "PRESTIGE BUILDING FLAT 2F 31 PIRIE STREET, MOUNT VICTORIA, WELLINGTON 6011",
"country": "NZ",
"attributes": {
"Exception": "H112 : No pattern matched for this input - PRESTIGE BUILDING FLAT 2F 31 PIRIE STREET, MOUNT VICTORIA, WELLINGTON 6011. Check for punctuation errors, duplicate fields, incorrect input format and incorrect input data."
}
}
]
}
```
**Failed to Validate**
For AU ad NZ: ChangedItems in the response will indicate the records not validated. "affectedElement": "ParsedWithoutMatchInPaf"
For International address: AVC code indicates the address match level. Records with AVC codes prefixed with "U" are unverified matches.
Records failed to validate: Australia, NewZealand and International
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ParsedAddressAu",
"fullAddress": "XYZ BUNGARRIBEE QLD 2807",
"country": "AUSTRALIA",
"postcode": "2807",
"subLocality": "",
"street2": "",
"street": "",
"streetNumber": "",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "",
"eid": null,
"lotNumber": null,
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "",
"streetName": "",
"attributes": {
"AddressQuality": "4",
"City": "XYZ BUNGARRIBEE",
"CountryIso2": "AU",
"CountryIso3": "AUS",
"CountryIsoNumber": "036",
"ProvinceCode": "QLD",
"ProvinceName": "QLD"
},
"id": null,
"careOf": "",
"exception": null,
"unknown": "",
"changedItems": [
{
"componentID": "GNAFValidation",
"actionType": "INFO",
"affectedElement": "ParsedWithoutMatchInPaf",
"oldValue": "",
"newValue": ""
},
{
"componentID": "GNAFValidation",
"actionType": "INFO",
"affectedElement": "HE019",
"oldValue": "",
"newValue": ""
}
],
"state": "QLD",
"locality": "XYZ BUNGARRIBEE"
},
{
"_type": "ParsedAddressNz",
"fullAddress": "UNIT 1 G 86 VICTORIA STREET, WELLINGTON CENTRAL, WELLINGTON 6011",
"country": "NEW ZEALAND",
"postcode": "6011",
"subLocality": "",
"street2": "",
"street": "VICTORIA ST",
"streetNumber": "86",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "G UNIT 1",
"eid": null,
"lotNumber": null,
"flatUnitNumber": "1",
"flatUnitType": "UNIT",
"floorLevelNumber": "G",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "ST",
"streetName": "VICTORIA",
"attributes": {
"AddressQuality": "9",
"City": "WELLINGTON",
"CountryIso2": "NZ",
"CountryIso3": "NZL",
"CountryIsoNumber": "554",
"MatchedRule": "NZPAF_URBAN_ADDRESS: WIDE_MATCH_RULE(NO_MATCH)",
"ProvinceCode": "",
"ProvinceName": ""
},
"id": null,
"rdNumber": "",
"careOf": "",
"exception": null,
"unknown": "",
"changedItems": [
{
"componentID": "NZHAVEGeoPAF",
"actionType": "INFO",
"affectedElement": "PointUrbanSubdwellingAddress",
"oldValue": "",
"newValue": ""
},
{
"componentID": "NZHAVEGeoPAF",
"actionType": "INFO",
"affectedElement": "ParsedWithoutMatchInPaf",
"oldValue": "",
"newValue": ""
},
{
"componentID": "NZHAVEGeoPAF",
"actionType": "ADD",
"affectedElement": "HE003",
"oldValue": "",
"newValue": ""
},
{
"componentID": "NZAddressStandardization",
"actionType": "MODIFY",
"affectedElement": "StreetType",
"oldValue": "STREET",
"newValue": "ST"
}
],
"suburb": "WELLINGTON CENTRAL",
"townCity": "WELLINGTON"
},
{
"_type": "AddressIntl",
"fullAddress": null,
"country": "UNITED STATES",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"CountryIso2": "US",
"eLOTNumber": "",
"CongressionalDistrict": "",
"CountryIso3": "USA",
"eLOTCode": "",
"DropCount": "",
"DropSiteIndicator": " ",
"AutoZoneIndicator": "",
"BusinessIndicator": " ",
"Footnotes": "C#",
"OtherIndicator": "",
"PostalCodeSecondaryRangeHigh": "0000",
"CarrierRoute": "",
"LACSLinkIndicator": " ",
"AQI": "E",
"DPVConfirmedIndicator": " ",
"CountryIsoNumber": "840",
"CentralizedIndicator": "",
"PMBType": "",
"CurbIndicator": "",
"DPVLACSIndicator": " ",
"PrimaryNumRangeLow": "",
"ReturnCode": "12",
"PostalCodeSecondaryRangeLow": "0000",
"VacantIndicator": " ",
"City": "",
"Sequence": "1",
"AVC": "U00-I00-P0-100",
"PostalCodeSecondary": "",
"DependentLocality": "",
"FalsePositiveIndicator": " ",
"SUITELinkFootnote": "",
"SecondaryNumRangeCode": " ",
"NDCBUIndicator": "",
"PMBNumber": "",
"PrimaryNumRangeCode": " ",
"Organization": "",
"SecondaryNumRangeLow": "",
"PrimaryNumRangeHigh": "",
"ThrowbackIndicator": " ",
"ResidentialDelivery": " ",
"CheckDigit": "",
"ProvinceName": "",
"CMRAIndicator": " ",
"DeliveryPointBarCode": "",
"RecordType": " ",
"NoStatIndicator": " ",
"SecondaryAddressLine": "",
"PostalCodePrimary": "",
"DPVFootnotes": "A1M1",
"FIPSCountyCode": "",
"EducationalIndicator": " ",
"SecondaryNumRangeHigh": "",
"PrimaryAddressLine": "",
"Finance": "000000",
"SeasonalIndicator": " ",
"DefaultFlag": " ",
"ProvinceCode": "",
"LACSLinkCode": ""
},
"id": null,
"district": null,
"city": "",
"province": ""
}
]
}
```
# Address Parse
Parse methods convert unstructured input data into structured component parts output.
## Parse methods (AU/NZ)
### address
The parse method takes one or more addresses as the input and parse them into component parts, returning a list of the parsed results. The maximum number of input addresses is 100 per call.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/parse/address
```
#### Request
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object:
```
{
"payload": [ { "fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000" } ],
"sourceOfTruth": "AUPAF"
}
```
#### Response
The response body is an [AddressRestResponse ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse)object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"attributes": null,
"buildingName": "",
"careOf": "",
"fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
"country": "",
"postcode": "2000",
"street2":"",
"street": "GEORGE ST",
"streetName": "GEORGE",
"streetSuffix": "",
"streetType": "ST",
"streetNumber": "220",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "L 2 SE 202",
"flatUnitNumber": "202",
"flatUnitType": "SE",
"floorLevelNumber": "2",
"floorLevelType": "L",
"lotNumber": null,
"eid": null,
"id": null,
"exception": null,
"state": "NSW",
"locality": "SYDNEY"
}
]
}
]
}
```
# Geocode Intl
Retrieves WGS84 geocode information for international address and locations.
## Get Geocode methods
GET or POST methods
POST method it can allow to send a list of addresses (maximum 100 per request) and return the geocodes to each address.
For processing multiple addresses, it returns null for the address that encounters an exception.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/intl/address/geocode
```
```
GET https://hosted.mastersoftgroup.com/harmony/rest/intl/address/geocode?country={country}&fullAddress={location}
```
#### Request
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object:
Name
Type
Example
Description
country*
country*
GB
ISO-2 or ISO-3 country
fullAddress*
string
Knowsley Industrial Park, LIVERPOOL, L33 7UY
The location to geocode. This can be a address, postal code or place name.
```
{
"payload":[
{ "fullAddress": "CA22 4SE", "country": "GB" },
{ "fullAddress": "20 Bond Street, Walker Flat SA 5238", "country": "AU" },
{ "fullAddress": "N6B 3L5", "country": "CA" },
{ "fullAddress": "Knowsley Industrial Park, LIVERPOOL, L33 7UY", "country": "GB" },
{ "fullAddress": "08550", "country": "US" },
{ "fullAddress": "19 Meado", "country": "IE" }
]
}
```
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object. With the enriched information being
| Name | Type | Description |
| -------------------- | ------ | ------------------------------------------ |
| fullAddress | string | The name of the location found |
| attributes.Latitude | string | the Latitude of the full address in WSG84 |
| attributes.Longitude | string | the Longitude of the full address in WSG84 |
### Example
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "22 Highlands Close, Finsbury Park, London, N4 4SE",
"country": "GB",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "51.57366",
"Longitude": "-0.12047"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "20 Bond Street, Walker Flat, South Australia, 5238",
"country": "AU",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "-34.77875",
"Longitude": "139.55431"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "Dundas Street, London ON N0M, N5V, N5W, N5X, N5Y, N5Z, N6A, N6B, N6C, N6E, N6G, N6H, N6J, N6K, N6M, N6P",
"country": "CA",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "43.00336",
"Longitude": "-81.18079"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "North Mersey Business Centre,Woodward Road, Knowsley Industrial Park, Liverpool",
"country": "GB",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "53.4892",
"Longitude": "-2.8515"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "Princeton Junction, NJ 08550",
"country": "US",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "40.29213",
"Longitude": "-74.61926"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "",
"country": "IE",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "52.40025",
"Longitude": "-9.286"
},
"id": null,
"district": null,
"city": null,
"province": null
}
]
}
```
# Address Insights
Address insights provide valuable data on enabling businesses to optimize operations and improve customer targeting by leveraging accurate and actionable geographic information
### What is Address Insights?
Address insights encompass various types of data that reveal valuable information about specific locations, demographics, and consumer behaviors. Geocoding, for example, converts physical addresses into geographic coordinates, allowing businesses to map out customer locations and identify spatial patterns. This can be particularly useful for optimizing delivery routes, selecting new store locations, and targeting marketing campaigns based on the proximity of potential customers. Additionally, demographic insights derived from addresses can provide details about the population density, average income levels, and household compositions in a particular area, enabling businesses to tailor their products and services to meet the needs of specific communities.
Another type of address insight involves property data, which includes information on property values, types of buildings, and historical transaction records. This is especially useful for real estate professionals, investors, and urban planners who need to assess market trends and property development opportunities. Furthermore, risk assessment insights related to addresses can identify areas prone to natural disasters, crime rates, and environmental hazards, aiding insurance companies and emergency services in better managing risks and allocating resources. By leveraging these various address insights, businesses and organizations can make more informed decisions, improve operational efficiency, and enhance customer satisfaction.
### Need Address Insights?
Contact us via customer support. Not all insights are published here and often we can assist, linking data with various suppliers.
# Australian Insights
# SEIFA Australia
SEIFA is a suite of four summary measures that reflect the socio-economic wellbeing of geographic areas based on social and economic information from the 2021 Census of Population and Housing.
### Getting Access
To access please contact us or your account manager.
### T**he Four SEIFA Indexes:**
* **Index of Relative Socio-economic Advantage and Disadvantage (IRSAD/RESEAD)**: Measures relative advantage and disadvantage based on factors like income, education, employment, occupation, housing, and family structure.
* **Index of Economic Resources (IER/ER)**: Focuses on income, wealth, and access to material resources.
* **Index of Education and Occupation (IEO/EO)**: Examines educational attainment and occupation.
* **Index of Social Disadvantage (ISD/RESED)**: Captures aspects related to social disadvantage, such as low income, unemployment, and low educational attainment.
### SEIFA Fields
Fields are appended to with attributes array as key value pairs
NAME
DESCRIPTION
EXAMPLES VALUES
eo_national_decile
National decile for Education and Occupation (IEO/EO)
6
eo_national_percentile
National percentile for Education and Occupation (IEO/EO)
51
eo_national_rank
National rank for Education and Occupation (IEO/EO)
27826
eo_score
The score for Education and Occupation (IEO/EO)
1000
eo_state_decile
State decile for Education and Occupation (IEO/EO)
5
eo_state_percentile
State percentile for Education and Occupation (IEO/EO)
49
eo_state_rank
State rank for Education and Occupation (IEO/EO)
8491
er_national_decile
National decile for Economic Resources (IER/ER)
8
er_national_percentile
National percentile for Economic Resources (IER/ER)
77
er_national_rank
National rank for Economic Resources (IER/ER)
42169
er_score
The score for Economic Resources (IER/ER)
1074
er_state_decile
State decile for Economic Resources (IER/ER)
8
er_state_percentile
State percentile for Economic Resources (IER/ER)
74
er_state_rank
State rank for Economic Resources (IER/ER)
12971
resead_national_decile
National decile for Socio-economic Advantage and Disadvantage (IRSAD/RESEAD)
6
resead_national_percentile
National percentile for Socio-economic Advantage and Disadvantage (IRSAD/RESEAD)
51
resead_national_rank
National rank for Socio-economic Advantage and Disadvantage (IRSAD/RESEAD)
27640
resead_score
The score for Socio-economic Advantage and Disadvantage (IRSAD/RESEAD)
1021
resead_state_decile
State decile for Socio-economic Advantage and Disadvantage (IRSAD/RESEAD)
6
resead_state_percentile
State percentile for Socio-economic Advantage and Disadvantage (IRSAD/RESEAD)
51
resead_state_rank
State rank for Socio-economic Advantage and Disadvantage (IRSAD/RESEAD)
8975
resed_national_decile
National decile for Social Disadvantage (ISD/RESED)
7
resed_national_percentile
National percentile for Social Disadvantage (ISD/RESED)
63
resed_national_rank
National rank for Social Disadvantage (ISD/RESED)
34229
resed_score
The score for Social Disadvantage (ISD/RESED)
1038
resed_state_decile
State decile for Social Disadvantage (ISD/RESED)
6
resed_state_percentile
State percentile for Social Disadvantage (ISD/RESED)
60
resed_state_rank
State rank for Social Disadvantage (ISD/RESED)
10398
# ASGS Australia Statistical Geography Standard
The Australian Statistical Geography Standard (ASGS) (ABS Australian Statistical Geography Standard (ASGS)) is the main geographical framework for the 2021 Census.
### Getting Access
To access please contact us or your account manager.
### What is ASGS?
The ASGS is a collection of geography regions used for social geography, developed to reflect the location of people and communities, and used for the release and analysis of statistics and other data. The ASGS is updated every 5 years to account for growth and change in Australia's population, economy and infrastructure.
### ASGS Fields
NAME
DESCRIPTION
EXAMPLES VALUES
sa1_code_main
Statistical area 1 main code
11701132213
sa1_population
Statistical area 1 population
433
sa2_code_main
Statistical area 2 main code
117011322
sa2_name
Statistical area name
Mascot - Eastlakes
sa3_code
Statistical areas level 3 (SA3) are geographical areas built from whole statistical areas level 2 (SA2
11701
sa3_name
SA 3 name
Botany
sa4_code
Statistical area level 4 (SA4) is one of the spatial units defined under the Australian statistical geography standard (ASGS)
117
sa4_name
Statistical area 4 name code
Sydney - City and Inner South
sed_code
State electoral division code
10035
sed_name
State electoral division name
Heffron
state_code
The state code
1
state_name
The state name
New South Wales
gcc_sa_code
Greater capital city statistical area code
1GSYD
gcc_sa_name
Greater capital city statistical area name
Greater Sydney
lga_code
Local government area code
10500
lga_name
Local government area name
Bayside (A)
ra_code
Remoteness area code
10
ra_name
Remoteness area name
Major Cities of Australia
area_sqkm
The Square KM measurement of the Statistical Area 1 (SA1)
0.1218
ced_code
The Commonwealth electoral division code
122
ced_name
The Commonwealth electoral division name
Kingsford Smith
# Residential / Commercial
Our address data package includes a powerful feature that distinguishes between residential and commercial addresses.
### Residential/Commercial indicator
A Residential/Commercial indicator is a classification system used to differentiate between properties designated for residential or commercial use. The indicator helps in property management, zoning regulations, and taxation by specifying the primary purpose of a property, whether for living spaces, such as houses and apartments, or for business purposes, like offices and retail spaces.
### Benefits
1. **Cost Efficiency**: By identifying whether an address is residential or commercial, you can choose the most cost-effective shipping options. Many shipping companies charge different rates based on the type of address.
2. **Improved Deliverability**: Ensure your packages reach the right destination by validating address types. This reduces the risk of returns due to incorrect address classification.
3. **Enhanced Customer Experience**: Provide accurate delivery estimates and improve customer satisfaction by using precise address data.
4. **Operational Efficiency**: Streamline your logistics and delivery operations by understanding your address data better.
### Getting Access
To access please contact us or your account manager.
{% embed url="" %}
### Data
| Field | Description | Example |
| --------------------- | ----------------------------------------------------- | -------- |
| residential\_ind | indicates if the address is residential | "Y", "N" |
| non\_residential\_ind | Indicates if the address is commercial or industrial. | "Y", "N" |
# Deliverable address
Know an address is deliverable before ever shipping a package.
### Deliverable Address indicator
Deliverable address indicator helps determine whether an address is deliverable. Used to verify the deliverability of addresses, ensuring that mail and parcels can be successfully delivered to the specified location.
### Benefits
1. **Enhanced Accuracy**: By verifying the deliverability of addresses, you can significantly reduce the number of undeliverable shipments, saving time and resources.
2. **Cost Savings**: Avoid the costs associated with returned shipments and re-delivery attempts by ensuring addresses are deliverable before dispatch.
3. **Improved Customer Satisfaction**: Deliver packages on time and to the correct location, enhancing the overall customer experience.
4. **Operational Efficiency**: Streamline your logistics and delivery operations with reliable address data, reducing manual checks and errors.
### Getting Access
To access please contact us or your account manager.
{% embed url="" %}
### Data
| Name | Description | Example |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| deliver\_mail\_ind | Used to verify the deliverability of addresses, ensuring that mail and parcels can be successfully delivered to the specified location. | "Y","N" |
# Suburb Lookup
Typeahead service for Searching for Suburbs and Postcodes
## GET /rest/v2/suburb/find
> Suburb lookup
```json
{"openapi":"3.0.1","info":{"title":"Harmony RightAddress REST API","version":"2.13.0"},"tags":[{"name":"findSuburb","description":"Find suburb under a country/state"}],"servers":[{"url":"https://hosted.mastersoftgroup.com/harmony","description":"Generated server url"}],"security":[{"rightaddress":[]}],"components":{"securitySchemes":{"rightaddress":{"type":"http","scheme":"basic"}},"schemas":{"AddressRestResponse":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESS","ERROR"]},"messages":{"type":"array","items":{"type":"string"}},"payload":{"type":"array","properties":{"sourceReduced":{"type":"boolean"},"empty":{"type":"boolean"},"first":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]},"last":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"items":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}}}},"AddressAu":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"locality":{"type":"string"},"state":{"type":"string"},"_type":{"type":"string"}}}]},"Address":{"required":["_type"],"type":"object","properties":{"fullAddress":{"type":"string"},"country":{"type":"string"},"postcode":{"type":"string"},"subLocality":{"type":"string"},"street2":{"type":"string"},"street":{"type":"string"},"streetNumber":{"type":"string"},"postal":{"type":"string"},"postalType":{"type":"string"},"postalNumber":{"type":"string"},"buildingName":{"type":"string"},"subdwelling":{"type":"string"},"eid":{"type":"string"},"lotNumber":{"type":"string"},"flatUnitNumber":{"type":"string"},"flatUnitType":{"type":"string"},"floorLevelNumber":{"type":"string"},"floorLevelType":{"type":"string"},"streetSuffix":{"type":"string"},"streetType":{"type":"string"},"streetName":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"id":{"type":"string"},"sourceOfTruth":{"type":"string"},"_type":{"type":"string"}},"discriminator":{"propertyName":"_type"}},"AddressIntl":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"district":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"_type":{"type":"string"}}}]},"AddressNz":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"rdNumber":{"type":"string"},"deliveredTo":{"type":"string"},"townCity":{"type":"string"},"suburb":{"type":"string"},"_type":{"type":"string"}}}]},"AddressV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"line3":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"}}}]},"InternalParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"}]},"ParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"PDPChangedItem":{"type":"object","properties":{"componentID":{"type":"string"},"actionType":{"type":"string","enum":["ADD","MODIFY","REMOVE","INFO"]},"affectedElement":{"type":"string"},"oldValue":{"type":"string"},"newValue":{"type":"string"}}},"ValidatedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"exception":{"type":"string"}}}]},"AddressIntlV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressIntl"}]},"InternalParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"}]},"ParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"ValidatedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"exception":{"type":"string"}}}]}}},"paths":{"/rest/v2/suburb/find":{"get":{"tags":["findSuburb"],"summary":"Suburb lookup","operationId":"findSuburb","parameters":[{"name":"country","in":"query","description":"country/region ISO2 code","required":true,"schema":{"type":"string"}},{"name":"sourceOfTruth","in":"query","description":"optional source of truth for certain country/region","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","description":"state that narrrows down the search","required":false,"schema":{"type":"string"}},{"name":"locality","in":"query","description":"search input for suburb, locality or postcode","required":true,"schema":{"type":"string"}},{"name":"featureOptions","in":"query","description":"feature options","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRestResponse"}}}}}}}}}
```
#### Resource URL
```
GET https://hosted.mastersoftgroup.com/harmony/rest/v2/suburb/find?country=AU&locality=XXXX&
```
#### Required Parameters
Name
Description
Type
country*
country/region ISO2 code
string
locality*
search input for suburb, locality or postcode
string
#### Resource URL with optional parameters
```
GET https://hosted.mastersoftgroup.com/harmony/rest/v2/suburb/find?country=AU&locality=3004&sourceOfTruth=AUPAF&state=VIC
```
**Optional Parameters**
Name
Description
Type
featureOptions
Set featureOptions
string
sourceOfTruth
Set source of truth for certain country/region
string
state
Filter to a particular State
string
#### Response AU
The response body is a JSON object. The following is an example:
```json
{
"status":"SUCCESS",
"messages":[],
"payload":[
{
"_type":"LocalityAu",
"fullAddress":"BRISBANE CITY QLD 4000",
"country":"AU",
"postcode":"4000",
"attributes":{
"GNAFReliability":"5",
"GNAFPID":"QLD3356",
"GNAFLocalityPID":"QLD3356",
"Latitude":"-27.46977630",
"Longitude":"153.02514222"
},
"state":"QLD",
"locality":"BRISBANE CITY"
},
{
"_type":"LocalityAu",
"fullAddress":"BRISBANE AIRPORT QLD 4008",
"country":"AU",
"postcode":"4008",
"attributes":{
"GNAFReliability":"5",
"GNAFPID":"QLD3377",
"GNAFLocalityPID":"QLD3377",
"Latitude":"-27.38836933",
"Longitude":"153.11320402"
},
"state":"QLD",
"locality":"BRISBANE AIRPORT"
},
{
"_type":"LocalityAu",
"fullAddress":"SOUTH BRISBANE QLD 4101",
"country":"AU",
"postcode":"4101",
"attributes":{
"GNAFReliability":"5",
"GNAFPID":"QLD2652",
"GNAFLocalityPID":"QLD2652",
"Latitude":"-27.47806742",
"Longitude":"153.01941190"
},
"state":"QLD",
"locality":"SOUTH BRISBANE"
},
{
"_type":"LocalityAu",
"fullAddress":"EAST BRISBANE QLD 4169",
"country":"AU",
"postcode":"4169",
"attributes":{
"GNAFReliability":"5",
"GNAFPID":"QLD933",
"GNAFLocalityPID":"QLD933",
"Latitude":"-27.48334169",
"Longitude":"153.04671989"
},
"state":"QLD",
"locality":"EAST BRISBANE"
},
{
"_type":"LocalityAu",
"fullAddress":"PORT OF BRISBANE QLD 4178",
"country":"AU",
"postcode":"4178",
"attributes":{
"GNAFReliability":"5",
"GNAFPID":"QLD2413",
"GNAFLocalityPID":"QLD2413",
"Latitude":"-27.38999869",
"Longitude":"153.17820559"
},
"state":"QLD",
"locality":"PORT OF BRISBANE"
}
]
}
```
#### Response NZ
The response body is a JSON object. The following is an example:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "LocalityNz",
"fullAddress": "AVONDALE, AUCKLAND 0600",
"country": "NZ",
"postcode": "0600",
"attributes": {
"ProvinceName": "AUCKLAND REGION",
"regional_council_name": "AUCKLAND REGION",
"City": "AUCKLAND",
"ProvinceCode": ""
},
"suburb": "AVONDALE",
"townCity": "AUCKLAND"
},
{
"_type": "LocalityNz",
"fullAddress": "BLOCKHOUSE BAY, AUCKLAND 0600",
"country": "NZ",
"postcode": "0600",
"attributes": {
"ProvinceName": "AUCKLAND REGION",
"regional_council_name": "AUCKLAND REGION",
"City": "AUCKLAND",
"ProvinceCode": ""
},
"suburb": "BLOCKHOUSE BAY",
"townCity": "AUCKLAND"
},
{
"_type": "LocalityNz",
"fullAddress": "MOUNT ALBERT, AUCKLAND 0600",
"country": "NZ",
"postcode": "0600",
"attributes": {
"ProvinceName": "AUCKLAND REGION",
"regional_council_name": "AUCKLAND REGION",
"City": "AUCKLAND",
"ProvinceCode": ""
},
"suburb": "MOUNT ALBERT",
"townCity": "AUCKLAND"
}
]
}
```
# Business Validation and Lookup
Business lookup methods take partial or complete business information to search against the business Source of Truth, returning validated and enriched business information.
To complete business validation requires using 2 API's each provide a specific purpose.
1. [**Find**](#find) - Returns a list of valid business based on partial or complete business information.
2. [**Retrieve**](#retrieve) - Uses the Id value from Find API or clear text business/company number to return the validated and enriched business information available for each country.
**Supported Countries:** Australia, New Zealand
## Find
Lookup businesses using a partial or complete business information in a single line business field.
The name to be searched can be a business number, company or any entity names.
HTTP `POST` will only process the **first** record in the request.
{% openapi src="" path="/v1/find" method="get" %}
{% endopenapi %}
{% openapi src="" path="/v1/find" method="post" %}
{% endopenapi %}
### Resource
```
GET/POST https://hosted.mastersoftgroup.com/business/v1/find
```
### Request
The request body is a [BusinessRestRequest](/loqate-harmony-api/api-specification/objects/business-objects#businessrequest) object:
required field\*
Name
Type
Example
Description
country*
string
AU
ISO 2 country AU or NZ
name*
string
"gbg aust"
partial business name being searched
nameTypes
string
"TRD,BN,OTN"
Filters for specific or multiple Entity types depending on country.
Australia
MN-->Main Entity name;
LGL-->Legal Entity Name (individuals/sole traders). Use with MN;
TRD-->Trading name in Other Entity;
BN-->Business name in Other Entity; DGR-->Deductible Gift Recipient;
OTN-->Other name in Other Entity.
New Zealand
MN-->Main Entity name;
TRD-->Trading name in Other Entity;
OTN-->Other name in Other Entity.
bnStatus
string
"ACT" default blank
Filters based on business number status. Options ACT = Active, CAN = Cancelled
taxStatus
string
"ACT" default blank
Filters based on business tax status. Options ACT = Active, CAN = Cancelled, NON = None
State
string
"NSW, QLD" default blank
Filters for specific or multiple states the business is located. Blank is all.
hits
integer
5 default 20
Number of results to be returned from the Find response.
caseType
string
"TITLE" default UP
The case type for the returned information UP,LOW,TITLE
### Response
The response body is a [BusinessRestResponse ](/loqate-harmony-api/api-specification/objects/business-objects#hostedbusinessrestresponse)object.
Response will be a combination of Main Entity name, Trading Name and Business names etc.
### Examples
**Request 1**: Lookup for active business names from multiple states
**Response 1**: Please note that the records with the same id pertains to same business. For e.g. Mastersoft Pty. Ltd. is the Main entity name while Mastersoft Pty Ltd is the Trading Name
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "Mastersoft Superannuation Fund",
"bn": "xxxxx2590",
"postcode": "3006",
"id": "UosAkx9hhtTIwxWz7n3Dng=="
},
{
"name": "Mastersoft Superannuation Fund",
"bn": "xxxxx2590",
"postcode": "3006",
"id": "UosAkx9hhtTIwxWz7n3Dng=="
},
{
"name": "Mastersoft Pty. Ltd.",
"bn": "xxxxx2029",
"postcode": "3144",
"id": "66qwO7IwxUgfyh4m3GoeIg=="
},
{
"name": "Mastersoft Pty Ltd",
"bn": "xxxxx2029",
"postcode": "3144",
"id": "66qwO7IwxUgfyh4m3GoeIg=="
},
{
"name": "Mastersoft Group Pty Ltd",
"bn": "xxxxx5800",
"postcode": "2000",
"id": "zwrNW9AAywaVsPbJmqhByg=="
}
]
}
```
**Request 2:** Lookup for active business names against Main Entity names
```json
{
"name": "Mastersoft",
"country": "au",
"bnStatus":"ACT",
"nameTypes":["MN"],
"state": [
"NSW","VIC"
],
"caseType": "TITLE"
}
```
**Response 2:**
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "Mastersoft Superannuation Fund",
"bn": "xxxxx2590",
"postcode": "3006",
"id": "UosAkx9hhtTIwxWz7n3Dng=="
},
{
"name": "Mastersoft Pty. Ltd.",
"bn": "xxxxx2029",
"postcode": "3144",
"id": "66qwO7IwxUgfyh4m3GoeIg=="
},
{
"name": "Mastersoft Group Pty Ltd",
"bn": "xxxxx5800",
"postcode": "2000",
"id": "zwrNW9AAywaVsPbJmqhByg=="
}
]
}
```
**Request 3:** Lookup for active business names with cancelled tax status
```json
{
"name": "Mastersoft",
"country": "au",
"bnStatus":"ACT",
"nameTypes":["MN"],
"taxStatus":"CAN",
"state": [
"NSW","VIC"
],
"caseType": "UP"
}
```
**Response 3:**
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "MASTERSOFT PTY. LTD.",
"bn": "xxxxx2029",
"postcode": "3144",
"id": "66qwO7IwxUgfyh4m3GoeIg=="
}
]
}
```
**Request 4**: Lookup business name using ABN number
```json
{
"name": "15 007 342 029",
"country": "au"
}
```
**Response 4**:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "MASTERSOFT PTY. LTD.",
"bn": "xxxxx2029",
"postcode": "3144",
"id": "66qwO7IwxUgfyh4m3GoeIg=="
}
]
}
```
## Retrieve
Retrieves the validated and enriched business information for the supplied Id value from Find API or clear text business or company number.
{% openapi src="" path="/v1/retrieve" method="post" %}
{% endopenapi %}
### Resource
```
GET/POST https://hosted.mastersoftgroup.com/business/v1/retrieve
```
### Request
The request body is a [BusinessRestRequest](/loqate-harmony-api/api-specification/objects/business-objects#businessrequest) object.
required fields\*
Name
Type
Example
Description
country*
string
"AU"
ISO-2 country AU or NZ
name*
string
"Ebu2PZ/Xdr3wef9MilFasw=="
Id value from Find API response OR clear text business OR clear text company number.
caseType
string
"LOW"
Case Type of text returned in the response.
selectedName
string
"AUGUSTA 4WD"
The 'selectedName' parameter utilized in the 'retrieve' request is used to assign either the business name or trading name to the 'display_name' field within the response payload. For instance, in the context of the 'Find' API, the name chosen by the user might not necessarily represent the primary entity name, it could be a trading name or business name etc.
When invoking the 'retrieve' request, users can pass on this 'selectedName,' resulting in the 'display_name' being rendered as 'main entity name trading as BN/main entity name trading as TRD'.
When 'selectedName' is not used in the retrieve request,' 'display_name' and 'name' both represent main entity name.
Determines if the syntax of the email address is valid.
true/false
email_valid
Attribute of the email format validation. Determines if the email format is valid or not.
Valid - format is valid.
(blank) - format is invalid and API timeout.
VALID, (blank)
domain_exists
Attribute of the domain validation. Determines if the domain exists and can receive email.
Valid - domain exists.
Invalid - domain does not exist or can't receive email.
Unknown - unable to determine if valid or not, check email.
VALID, INVALID, UNKNOWN
mailserver_exists
Attribute of the mailserver validation. Determines if the mailserver is valid or not.
Valid - mailserver exists.
Invalid - there is no mail server present at this domain.
Unknown - unable to determine if valid or not, check email.
VALID, INVALID, UNKNOWN
email_exists
Attribute of the mailbox validation.
Valid - email is verified.
Invalid - email address does not exist on mail server.
Unknown - unable to verify email address.
VALID, INVALID, UNKNOWN
message
additional information
Email verified.
Domain does not exist or cannot receive email.
Email address does not exist on mail server.
Please check email, unable to determine if valid or invalid.
This mail server accepts all requests. Unable to verify email address.
do_not_send
Often these emails cause you reputation damage on email sending platforms.
true/false
disposable
Known Temporary email address that is used to hide the real email address of the user. These usual last 15 min to 6 months.
true/false
rolebased
Role based email (e.g., sales@, marketing@) and not an individual's email address.
true/false
catchAll
Catch all based email (e.g., donotreply@ client@) and not an individual's email address.
true/false
subdomain
email is subdomain email.
true/false
account
The portion of the email address before the "@" symbol.
jim
domain
The portion of the email address after the "@" symbol.
hotmail.com
risk
Potential impact on sender reputation score depending on all aspects.
LOW, MEDIUM, HIGH, UNKNOWN
suggested_email
Suggestive Fix for an email typo
jim@hotmail.com
deliverable
status type field
deliverable, undeliverable, do_not_send, catch_all or unknown
reason
List of reasons validation was unsuccessful
see reason list
hashsha256
Hashed using sha256
4c93fb55adc02....
### Reason List
Reason
Description
catch_all
The validity of the recipient address cannot be determined as the provider accepts any and all email regardless of whether or not the recipient’s mailbox exists.
disallow_list
Email is on your disallow list.
failed custom grammar check
The mailbox failed our local-part grammar check.
format_failed
Failed format syntax check.
high_risk_domain
Information obtained about the domain indicates it is high risk to send email to.
immature_domain
The domain is newly created based on the WHOIS information.
long_term_disposable
The mailbox has been identified as a long term disposable address. Long term disposable addresses can be quickly and easily deactivated by users, but they will not expire without user intervention.
mailbox_does_not_exist
The mailbox is undeliverable or does not exist.
mailbox_is_disposable_address
The mailbox has been identified to be a disposable address. Disposable address are temporary, generally one time use, addresses.
mailbox_is_role_address
The mailbox is a role based address (ex. support@…, marketing@…).
no_mx / No MX host found
The recipient domain does not have a valid MX host.
req_timeout
Timed out by request timeout setting e.g. your timeout setting. You may need to increase your timeout setting.
smtp_timeout
Timed out by smtp provider.
subdomain_mailer
The recipient domain is identified to be a subdomain and is not on our exception list. Subdomains are considered to be high risk as many spammers and malicious actors utilize them.
tld_risk
The domain has a top-level-domain (TLD) that has been identified as high risk.
unknown_provider
The MX provider is an unknown provider.
### Response timings
We make live calls to domains located all around the world that have variable protocols and capacities. The vast majority of calls, in particular to major ISP's operate within the desire response times. A small amount a domains will result in network, server latency and security protocols variables like mail transfer agents that can impact the overall latency of the service.
This is an industry wide issue when sending requests to domains around the world. Our expected ranges of performance results are:
* 96%-98% of all domains sit between 1 to 5 seconds.
* All the major ISP's are 1 to 3 secs.
* 2%-4% will take longer than 5 seconds.
This can cause impacts in your customer experience. If this is an issue for your implementation we recommend implementing a timeout function when calling our Email Validation API and handling as an 'unknown' response to the end user.
### Depreciated Attributes
In August 2023, the following attributes have been depreciated.
**do\_not\_mail:** depreciated and replaced with **do\_not\_send** because of naming confusion with anti-spam compliance. do\_not\_mail and do\_not\_send is a recommendation to protect your sender reputation score.
**spamtrap:** Depreciated due to privacy compliance.
**abuse:** Depreciated due to privacy compliance.
**domain\_age\_days:** Depreciated and superseded with new attributes contained within reason being high\_risk\_domain, immature\_domain, tld\_risk.
# Phone Validation
Takes one or more mobile phone numbers as an input and performs validation, returning a list of the results. The maximum number of input phone numbers is 100 per call.
### Phone Validation Version 1.1
Takes one or more mobile phone numbers as an input and performs validation, returning a list of the results. The maximum number of input phone numbers is 100 per call.
Phone Validation coverage is global when full **international number format (ITU E.123)** is used. As example includes the '+' with the country code e.g. '+61 412 123 456' or '+22 607 123 4567'.
See phone coverage to understand country coverage.
**Changes from 16th October 2025:** Phone validation was expanded to include landline and VoIP numbers, in addition to the current mobile phone validation for both business and personal use.
**Added attributes:** RequestProcessed, NumberType, PhoneNumber, NetworkCode, and IsValid.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/au/validate/phone
```
#### Request
The request body is a[ PhoneRestRequest ](/loqate-harmony-api/api-specification/objects/phone-objects#phonerestrequest)object:
```
{
"payload": [ { "fullPhone": "0412345678", "country": "AU" } ]
}
```
#### Response
The response body is a [PhoneRestResponse](/loqate-harmony-api/api-specification/objects/phone-objects#phonerestresponse) object:
```markup
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullPhone": "0412345678",
"country": "AU",
"countryCode": "61",
"areaCode": "",
"localNumber": "0412 345 678",
"operatorName": "Vodafone Australia",
"phoneStatus": "connected|Network confirmed connection",
"exception": "",
"attributes": {
"RequestProcessed": "true",
"NumberType": "Mobile",
"PhoneNumber": "+61412345678",
"NetworkCode": "02",
"IsValid": "Yes"
}
}
]
}
```
**Response Elements**
The response attributes are listed below. These are listed in the order expected when validating phones.
Element Name
Description
Example
fullPhone
The input phone number being validated.
0412345678
country
The ISO 3166-1 2-letter country code.
AU, NZ, GB, US
countryCode
Telephone number prefix.
+61
areaCode
No longer used as it is part of the localNumber.
null
localNumber
Local number is in the national format of the country,
0412 345 678
operatorName
Network name.
Vodafone Australia
phone Status
There are only three phone status returned. Connected - validated phone number and connected. Disconnected - validated number but not connected or cannot be reached. Indeterminate - number is invalid and returned error codes.
The request validation request has been processed.
true false
NumberType
The number type can be mobile, landline or VOIP and includes special numbers.
Mobile Landline VOIP
PhoneNumber
Input number with the country code prefix.
+61412345678
NetworkCode
Network code assigned to the mobile provider.
03
IsValid
Yes - number is valid and connected. No - several cases: (1) valid number but disconnected; (2) not a valid number and network cannot be determined.
Yes No
# Matching
Match methods match data sets and return the relevant matching results.
### match
The match method takes the first Customer Record (CR) data set against one or many Reference Record (RR) data set as the input. One data set can be any of these combinations: one address (single-line or components) and/or one email address and/or one phone. It returns a list of matched data set pair with its matching results, such as match class, confidence level, and match category. The maximum number of CR data set is 1, the maximum number of RR data sets is 100, and id must be present.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/match
```
#### Request
The request body is an [MatchRestRequest](/loqate-harmony-api/api-specification/objects/match-objects#matchrestrequest) object:
```json
{
"payload": {
"from": [
{
"addresses": [ { "fullAddress": "220 george street, sydney nsw 2000" } ],
"id": "c1",
"phones": [ { "fullPhone": "12345678" } ]
}
],
"to": [
{
"addresses": [ { "fullAddress": "220 george street, sydney nsw 2000" } ],
"id": "r1",
"phones": [ { "fullPhone": "12345678" } ]
},
{
"addresses": [ { "fullAddress": "level 2, 220 george street, sydney nsw 2000" } ],
"id": "r2"
}
]
}
}
```
With address components:
```
{
"payload": {
"from": [
{
"addresses": [ { "fullAddress": "level 2, 220 george street, sydney nsw 2000" } ],
"id": "c1",
"phones": [ { "fullPhone": "12345678" } ]
}
],
"to": [
{
"addresses": [ {
"floorLevelNumber": "2",
"floorLevelType": "level",
"streetName": "george",
"streetNumber": "220",
"streetType": "street",
"locality":"sydney",
"state":"nsw"
} ],
"id": "r2"
}
]
}
}
```
#### Response
The response body is an [MatchResultRestResponse ](/loqate-harmony-api/api-specification/objects/match-objects#companyrestresponse)object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fromId": "c1",
"toId": "r1",
"entityResults": [ {
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [ 0, 0 ],
"assignedMatchClass": "H1",
"confidenceLevel": "10",
"description": "Household Match Class H1",
"matchCategory": "MATCH_CLASS"
} ]
},
{
"fromId": "c1",
"toId": "r2",
"entityResults": [ {
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [],
"assignedMatchClass": "G2",
"confidenceLevel": "8",
"description": "Address Match Class G2",
"matchCategory": "MATCH_CLASS"
} ]
}
]
}
```
# NZ Property Title
Takes an single line address or semi-structure address or latitude, longitude as an input and performs property ownership validation, return validated result as passed or failed.
### nzPropertyTitle
Takes an single line address or semi-structure address or latitude, longitude as an input and performs property ownership validation, return validated result as passed or failed.
#### Resource URLs
```
POST(component)
https://hosted.mastersoftgroup.com/harmony/rest/nz/validate/propertyTitle/component
GET(component)
https://hosted.mastersoftgroup.com/harmony/rest/nz/validate/propertyTitle/component?firstName=John&lastName=Doe&streetNumber=000&street=xxx&suburb=MT EDEN&townCity=ACUKLAND&postcode=1024
POST(singleLine)
https://hosted.mastersoftgroup.com/harmony/rest/nz/validate/propertyTitle/address
GET(singleLine)
https://hosted.mastersoftgroup.com/harmony/rest/nz/validate/propertyTitle/address?firstName=John&lastName=Doe&fullAddress=000 xxxx st, wellington central, wellington&showDetails=true
POST(latLong)
https://hosted.mastersoftgroup.com/harmony/rest/nz/validate/propertyTitle/latlong
GET(latLong)
https://hosted.mastersoftgroup.com/harmony/rest/nz/validate/propertyTitle/latlong?firstName=John&lastName=Doe&latitude=-41.xxxxxxx&longitude=174.xxxxxx&showDetails=true
```
#### Request
The request body is a [PropertyTitleRestRequest ](/loqate-harmony-api/api-specification/objects/property-title-objects#propertytitlerestrequest)object:
```
{
"payload": {
"firstName":"John",
"lastName":"Doe",
"streetNumber":"000",
"street":"xxxxx st",
"suburb":"wellington central",
"townCity":"wellington"
},
"showDetails":"true"
}
```
#### Response
The response body is a [PropertyTitleRestResponse ](/loqate-harmony-api/api-specification/objects/property-title-objects#propertytitlerestresponse)object:
```
{
{
"status":"SUCCESS",
"messages":[],
"payload":{
"response":"fail",
"attributes":[
{
"type":"NZ_PROPERTY_TITLE",
"attributes":{
"guaranteeStatus":"Guarantee",
"status":"LIVE",
"descrption":"Fee Simple, 1/1, Lot x Deposited Plan xxx, 401 m2",
"spatialExtensShared":"T",
"ownsNumber":"1",
"issueDate":"1986/09/10 00:00:00",
"titleNo":"xxxx",
"type":"Freehold",
"owners":"xxxx",
"titleId":"xxxx",
"landDistrict":"Wellington"
}
}
]
}
}
}
```
# Moved Suppression
Enriches address with know moved suppressions
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/movedSuppression
```
#### Request
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
```
{
"payload": [ { "id": "12345678" } ], "sourceOfTruth": "AUPAF"
}
```
#### Response
The response body is an [AddressRestResponse ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse)object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress":null,
"country":null,
"postcode":null,
"street2":null,
"street":null,
"streetNumber":null,
"postal":null,
"postalType":null,
"postalNumber":null,
"buildingName":null,
"subdwelling":null,
"eid":null,
"lotNumber":null,
"flatUnitNumber":null,
"flatUnitType":null,
"floorLevelNumber":null,
"floorLevelType":null,
"streetSuffix":null,
"streetType":null,
"streetName":null,
"attributes": {
"moved_suppression_date":"2004-05-27",
"moved_suppression_consent_indicator":"N"
},
"id":"12345678",
"state":null,
"locality":null
}
]
}
```
If the moved suppression data is not found using the supplied id (DPID):
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress":null,
"country":null,
"postcode":null,
"street2":null,
"street":null,
"streetNumber":null,
"postal":null,
"postalType":null,
"postalNumber":null,
"buildingName":null,
"subdwelling":null,
"eid":null,
"lotNumber":null,
"flatUnitNumber":null,
"flatUnitType":null,
"floorLevelNumber":null,
"floorLevelType":null,
"streetSuffix":null,
"streetType":null,
"streetName":null,
"attributes":{"moved_suppression":"not.found"},
"id":"12345678",
"state":null,
"locality":null
}
]
}
```
# Deceased Suppression
Retrieves deceased suppression data using the supplied id (DPID). This API is only for AUPAF Source of Truth.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/deceasedSuppression
```
#### Request
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
```
{
"payload": [ { "id": "12345678" } ], "sourceOfTruth": "AUPAF"
}
```
#### Response
The response body is an [AddressRestResponse ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse)object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress":null,
"country":null,
"postcode":null,
"street2":null,
"street":null,
"streetNumber":null,
"postal":null,
"postalType":null,
"postalNumber":null,
"buildingName":null,
"subdwelling":null,
"eid":null,
"lotNumber":null,
"flatUnitNumber":null,
"flatUnitType":null,
"floorLevelNumber":null,
"floorLevelType":null,
"streetSuffix":null,
"streetType":null,
"streetName":null,
"attributes":{"deceased_suppression_date":"2018-09-26"},
"id":"12345678",
"state":null,
"locality":null
}
]
}
```
If the deceased suppression data is not found using the supplied id (DPID):
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress":null,
"country":null,
"postcode":null,
"street2":null,
"street":null,
"streetNumber":null,
"postal":null,
"postalType":null,
"postalNumber":null,
"buildingName":null,
"subdwelling":null,
"eid":null,
"lotNumber":null,
"flatUnitNumber":null,
"flatUnitType":null,
"floorLevelNumber":null,
"floorLevelType":null,
"streetSuffix":null,
"streetType":null,
"streetName":null,
"attributes":{"deceased_suppression":"not.found"},
"id":"12345678",
"state":null,
"locality":null
}
]
}
```
# Objects
Detail data Objects (Data Models) of all our services.
{% content-ref url="/pages/hjuNMnm4pGWi7WuYPKMS" %}
[Address Objects](/loqate-harmony-api/api-specification/objects/address-objects)
{% endcontent-ref %}
{% content-ref url="/pages/0kCUfBORLcrmn88mcyiT" %}
[Address Type Objects](/loqate-harmony-api/api-specification/objects/address-objects-1)
{% endcontent-ref %}
{% content-ref url="/pages/Fix2NUwiYgU9dB7c7Gq5" %}
[Suburb Objects](/loqate-harmony-api/api-specification/objects/suburb-objects)
{% endcontent-ref %}
{% content-ref url="/pages/G19pSo0z9Esse3W7Hz76" %}
[Parse Objects](/loqate-harmony-api/api-specification/objects/parse-objects)
{% endcontent-ref %}
{% content-ref url="/pages/SD55jFUYViVatjrJ9uAu" %}
[Email Objects](/loqate-harmony-api/api-specification/objects/email-objects)
{% endcontent-ref %}
{% content-ref url="/pages/5HnnVYPTPx82paaxi5NU" %}
[Phone Objects](/loqate-harmony-api/api-specification/objects/phone-objects)
{% endcontent-ref %}
{% content-ref url="/pages/YssjkGwVphBjFNUqC5jY" %}
[Property Title Objects](/loqate-harmony-api/api-specification/objects/property-title-objects)
{% endcontent-ref %}
{% content-ref url="/pages/VIO6ePd3m4Yo1eOQ6sXH" %}
[Match Objects](/loqate-harmony-api/api-specification/objects/match-objects)
{% endcontent-ref %}
{% content-ref url="/pages/8XMhs7wpwfFaDad18Wr9" %}
[Business Objects](/loqate-harmony-api/api-specification/objects/business-objects)
{% endcontent-ref %}
# Address Objects
We have three different types of objects suited to primary business regions being Australia, New Zealand and International (rest of world).
## Address Objects
| [Universal Response Objects](#universal) | Objects that are part of every response object |
| ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [AddressAu](#addressau) | Australian Address. |
| [AddressNz](#addressnz) | New Zealand Address. |
| [ValidatedAddressAu](#validatedaddressau) | An Australian address for validation. |
| [ValidatedAddressNz](#validatedaddressnz) | A New Zealand address for validation. |
| [AddressIntl](#addressintl) | International Address. |
| [AddressIntlV2](#addressintlv2) | International Address with `non-null` attributes only - for address [find ](/loqate-harmony-api/api-specification/address/address-validation-and-lookup#find)method. |
| [AddressList](#addresslist) | Address container. |
| [AddressRestRequest](#addressrestrequest) | Request wrapper for address REST methods. |
| [AddressRestResponse](#addressrestresponse) | Response wrapper for address REST methods. |
| [FeatureOption](#featureoption) | Options applied for each request. |
### Universal Response Objects
We have three different types of objects suited to primary business regions being Australia, New Zealand and International (rest of world). However, if you need to integrate your global business need a set of universal objects.
We've created universal response components to enable consistent information no matter which address object best suits your business need.
When integrating to a platform we recommend using the universal response objects for consistency and scale.
{% hint style="info" %}
See [Address Field Mappings Guide](/loqate-harmony-api/guides/best-practices/address-field-mappings) for recommendations.
{% endhint %}
### AddressAu
The AddressAu object is used when sending and receiving data from the address lookup API methods. For receiving data validated using Australian Sources of Truth (SoTs), see [ValidatedAddressAu ](#addressau)object.
#### \_type
Type: `String`
The Address type object for the returned response (e.g. 'AddressAu').
#### eid
Type: `String`
The encrypted ID (e.g. 'fGBUVVdCntAu6wgNVcv0ePuSac7kAbUP').
#### fullAddress
Type: `String`
The concatenated address (e.g. 'SE 202 220 George St, Sydney, NSW 2000').
#### country
Type: `String`
Not currently implemented.
#### state
Type: `String`
The abbreviated State component of the address (e.g. 'NSW').
#### postcode
Type: `String`
The Postcode component of the address (e.g. '2000').
#### locality
Type: `String`
The Locality component of the address (e.g. 'NORTH SYDNEY').
#### street
Type: `String`
The Street component of the address (e.g. 'GEORGE STREET').
#### postal
Type: `String`
The Postal address (e.g. 'PO BOX 123').
#### postalNumber
Type: `String`
The Postal Number component of the Postal address (e.g. '123').
#### postalType
Type: `String`
The Postal Type component of the Postal address (e.g. 'PO BOX').
#### streetNumber
Type: `String`
The Street Number component of the address (e.g. '45A').
#### streetName
Type: `String`
The Street Name component of the address (e.g. 'GEORGE').
#### streetType
Type: `String`
The Street Type component of the address (e.g. 'STREET').
#### streetSuffix
Type: `String`
The Street Suffix component of the address (e.g. 'E').
#### buildingName
Type: `String`
The Building Name component of the address (e.g. 'ANZAC HOUSE').
#### subdwelling
Type: `String`
The Subdwelling component of the address (e.g. 'SE 202'). This includes subdwelling, floor, block and lot information.
#### flatUnitNumber
Type: `String`
The Flat Unit Number component of the address (e.g. '7A').
#### flatUnitType
Type: `String`
The Flat Unit Type component of the address (e.g. 'U').
#### floorLevelNumber
Type: `String`
The Floor Level Number component of the address (e.g. '2').
#### floorLevelType
Type: `String`
The Floor Level Type component of the address (e.g. 'FL').
#### lotNumber
Type: `String`
The Lot Number component of the address (e.g. '1').
#### attributes
Type: `Map`
A map of name/value pairs representing additional information from the Address in the Source of Truth (e.g. `{"Longitude": "12.34", "Latitude": "12.34" }`).
For example, sample attributes returned from "AUPAF" are shown below: `{"Barcode":"1301012101021000002110322210012201313","Bsp":"015","DPID":"71230073"}`
Sample attributes returned from "GNAF" are shown below: `{"GNAFConfidence":"0","ParcelID":"1//DP75111","GNAFPointPID":"GANSW718616256", "MeshblockId":"10743811000","Latitude":"-33.86307089", "GNAFPID":"GANSW718616256","Longitude":"151.20781474", "GNAFReliability":"2","GNAFLocalityPID":"NSW3749", "GNAFGroupPID":"NSW2845405","GeocodeLevel":"7"}`
Sample attributes are shown below, if "GNAF Plus" is active:
`{"GNAFConfidence": "0","ParcelID": "CANB/BRAD/7/9/","GNAFPointPID": "GAACT718021569", "MeshblockId": "80003983000","Latitude": "-35.26134209", "GNAFPID": "GAACT718021569","Longitude": "149.13239137", "GNAFReliability": "2","GNAFLocalityPID": "ACT106", "GNAFGroupPID": "ACT346","GeocodeLevel": "7", "GNAFPIDPosition": "DOORSTOP","area_sqkm": "0.0468", "state_name": "AUSTRALIAN CAPITAL TERRITORY","state_code": "8", "lga_name": "UNINCORPORATED ACT","lga_code": "89399", "gcc_sa_name": "AUSTRALIAN CAPITAL TERRITORY","gcc_sa_code": "8ACTE", "ced_name": "FENNER","ced_code": "802", "sed_name": "KURRAJONG","sed_code": "80003", "sa1_code_7d": "8105118","sa1_code_main": "80105105118", "sa2_name": "BRADDON","sa2_code_main": "801051051","sa2_code_5d": "81051", "sa3_name": "NORTH CANBERRA","sa3_code": "80105", "sa4_name": "AUSTRALIAN CAPITAL TERRITORY","sa4_code": "801"}`
#### JSON Representation
```json
{
"_type": "AddressAu",
"eid": "fGBUVVdCntAu6wgNVcv0ePuSac7kAbUP",
"fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
"country": null,
"state": "NSW",
"postcode": "2000",
"locality": "SYDNEY",
"street": "GEORGE ST",
"postal": "",
"postalNumber": "",
"postalType": "",
"streetNumber": "220",
"streetName": "GEORGE",
"streetType": "ST",
"streetSuffix": "",
"buildingName": "",
"subdwelling": "L 2 SE 202",
"flatUnitNumber": "202",
"flatUnitType": "SE",
"floorLevelNumber": "2",
"floorLevelType": "L",
"lotNumber": "",
"attributes": {
"Barcode": "1301012101021000002110322210012201313",
"Bsp": "015",
"DPID": "12345678"
}
}
```
### AddressNz
The AddressNz object is used when sending and receiving data from the address lookup API methods. For receiving data validated using New Zealand Sources of Truth (SoTs), see [ValidatedAddressNz ](#validatedaddressnz)object.
#### \_type
Type: `String`
The Address type object for the returned response (e.g. 'AddressNz').
#### eid
Type: `String`
The encrypted ID (e.g. 'O4zqtEf98jsqhJwoNG+0S/DCFUGzuGGH').
#### fullAddress
Type: `String`
The concatenated address (e.g. '20 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011').
#### country
Type: `String`
Not currently implemented
#### postcode
Type: `String`
The Postcode component of the address (e.g. '6011').
#### townCity
Type: `String`
The Town/City component of the address (e.g. 'WELLINGTON').
#### suburb
Type: `String`
The Suburb component of the address (e.g. 'WELLINGTON CENTRAL').
#### street
Type: `String`
The Street component of the address (e.g. 'PANAMA STREET').
#### postal
Type: `String`
The Postal address (e.g. 'PO BOX 123').
#### postalNumber
Type: `String`
The Postal Number component of the Postal address (e.g. '123').
#### postalType
Type: `String`
The Postal Type component of the Postal address (e.g. 'PO BOX').
#### streetNumber
Type: `String`
The Street Number component of the address (e.g. '45A').
#### streetName
Type: `String`
The Street Name component of the address (e.g. 'PANAMA').
#### streetType
Type: `String`
The Street Type component of the address (e.g. 'STREET').
#### streetSuffix
Type: `String`
The Street Suffix component of the address (e.g. 'E').
#### buildingName
Type: `String`
The Building Name component of the address (e.g. 'ALBERT PLAZA').
#### subdwelling
Type: `String`
The Subdwelling component of the address (e.g. 'SE 202'). This includes subdwelling, floor, block and lot information.
#### flatUnitNumber
Type: `String`
The Flat Unit Number component of the address (e.g. '7A').
#### flatUnitType
Type: `String`
The Flat Unit Type component of the address (e.g. 'U').
#### floorLevelNumber
Type: `String`
The Floor Level Number component of the address (e.g. '2').
#### floorLevelType
Type: `String`
The Floor Level Type component of the address (e.g. 'FL').
#### lotNumber
Type: `String`
The Lot Number component of the address (e.g. '1').
#### attributes
Type: `Map`
A map of name/value pairs representing additional information from the Address in the Source of Truth (e.g. `{"Longitude": "12.34", "Latitude": "12.34"}`).
For example, sample attributes returned from "NZPAF" are shown below: `{"ParcelId":"3996917","XCoordinate":"2658827", "MeshblockId":"2127500","YCoordinate":"5989553", "Latitude":"-41.287171091075614","Longitude":"174.7770385563209"}`
#### JSON Representation
```json
{
"_type": "AddressNz",
"eid": "DmQYwqF0wjGOgn2XZYMJbvLPHFLYXJEu",
"fullAddress": "25 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011",
"country": null,
"postcode": "6011",
"townCity": "WELLINGTON",
"suburb": "WELLINGTON CENTRAL",
"street": "PANAMA STREET",
"street2": null,
"postal": "",
"postalNumber": "",
"postalType": "",
"streetNumber": "25",
"streetName": "PANAMA",
"streetType": "STREET",
"streetSuffix": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"rdNumber": null,
"attributes": {
"Latitude": "-41.284123",
"Longitude": "174.776194",
"MeshblockId": "2125700",
"ParcelId": "4032109",
"XCoordinate": "2658764",
"XNztm": "1748740.49107",
"YCoordinate": "5989893",
"YNztm": "5428180.430423"
}
}
```
### ValidatedAddressAu <\> [AddressAu](#addressau)
The ValidatedAddressAu object is used when sending and receiving data from the address identify API methods using Australian Sources of Truth (SoTs).
#### \_type
Type: `String`
The Address type object for the returned response (e.g. 'ValidatedAddressAu').
#### eid
Type: `String`
The encrypted ID (e.g. 'fGBUVVdCntAu6wgNVcv0ePuSac7kAbUP').
#### fullAddress
Type: `String`
The concatenated address (e.g. 'SE 202 220 George St, Sydney, NSW 2000').
#### country
Type: `String`
Not currently implemented.
#### state
Type: `String`
The abbreviated State component of the address (e.g. 'NSW').
#### postcode
Type: `String`
The Postcode component of the address (e.g. '2000').
#### locality
Type: `String`
The Locality component of the address (e.g. 'NORTH SYDNEY').
#### street
Type: `String`
The Street component of the address (e.g. 'GEORGE STREET').
#### postal
Type: `String`
The Postal address (e.g. 'PO BOX 123').
#### postalNumber
Type: `String`
The Postal Number component of the Postal address (e.g. '123').
#### postalType
Type: `String`
The Postal Type component of the Postal address (e.g. 'PO BOX').
#### streetNumber
Type: `String`
The Street Number component of the address (e.g. '45A').
#### streetName
Type: `String`
The Street Name component of the address (e.g. 'GEORGE').
#### streetType
Type: `String`
The Street Type component of the address (e.g. 'STREET').
#### streetSuffix
Type: `String`
The Street Suffix component of the address (e.g. 'E').
#### buildingName
Type: `String`
The Building Name component of the address (e.g. 'ANZAC HOUSE').
#### subdwelling
Type: `String`
The Subdwelling component of the address (e.g. 'SE 202'). This includes subdwelling, floor, block and lot information.
#### flatUnitNumber
Type: `String`
The Flat Unit Number component of the address (e.g. '7A').
#### flatUnitType
Type: `String`
The Flat Unit Type component of the address (e.g. 'U').
#### floorLevelNumber
Type: `String`
The Floor Level Number component of the address (e.g. '2').
#### floorLevelType
Type: `String`
The Floor Level Type component of the address (e.g. 'FL').
#### lotNumber
Type: `String`
The Lot Number component of the address (e.g. '1').
#### id
Type: `String`
The DPID or GNAFPID of the address (e.g. '89524889').
#### exception
Type: `String`
The exception thrown from the backend.
#### attributes
Type: `Map`
A map of name/value pairs representing additional information from the Address in the Source of Truth (e.g. `{"Longitude": "12.34", "Latitude": "12.34" }`).
For example, sample attributes returned from "AUPAF" are shown below: `{"Barcode":"1301012101021000002110322210012201313","Bsp":"015","DPID":"71230073"}`
Sample attributes returned from "GNAF" are shown below: `{"GNAFConfidence":"0","ParcelID":"1//DP75111","GNAFPointPID":"GANSW718616256", "MeshblockId":"10743811000","Latitude":"-33.86307089", "GNAFPID":"GANSW718616256","Longitude":"151.20781474", "GNAFReliability":"2","GNAFLocalityPID":"NSW3749", "GNAFGroupPID":"NSW2845405","GeocodeLevel":"7"}`
Sample attributes are shown below, if "GNAF Plus" is active: `{"GNAFConfidence": "0","ParcelID": "CANB/BRAD/7/9/","GNAFPointPID": "GAACT718021569", "MeshblockId": "80003983000","Latitude": "-35.26134209", "GNAFPID": "GAACT718021569","Longitude": "149.13239137", "GNAFReliability": "2","GNAFLocalityPID": "ACT106", "GNAFGroupPID": "ACT346","GeocodeLevel": "7", "GNAFPIDPosition": "DOORSTOP","area_sqkm": "0.0468", "state_name": "AUSTRALIAN CAPITAL TERRITORY","state_code": "8", "lga_name": "UNINCORPORATED ACT","lga_code": "89399", "gcc_sa_name": "AUSTRALIAN CAPITAL TERRITORY","gcc_sa_code": "8ACTE", "ced_name": "FENNER","ced_code": "802", "sed_name": "KURRAJONG","sed_code": "80003", "sa1_code_7d": "8105118","sa1_code_main": "80105105118", "sa2_name": "BRADDON","sa2_code_main": "801051051","sa2_code_5d": "81051", "sa3_name": "NORTH CANBERRA","sa3_code": "80105", "sa4_name": "AUSTRALIAN CAPITAL TERRITORY","sa4_code": "801"}`
#### JSON Representation
```json
{
"_type": "ValidatedAddressAu",
"fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
"country": null,
"postcode": "2000",
"eid": "fGBUVVdCntAu6wgNVcv0ePuSac7kAbUP",
"exception": null,
"state": "NSW",
"locality": "SYDNEY",
"street": "GEORGE ST",
"postal": "",
"postalNumber": "",
"postalType": "",
"streetNumber": "220",
"streetName": "GEORGE",
"streetType": "ST",
"streetSuffix": "",
"buildingName": "",
"subdwelling": "L 2 SE 202",
"flatUnitNumber": "202",
"flatUnitType": "SE",
"floorLevelNumber": "2",
"floorLevelType": "L",
"lotNumber": "",
"attributes": {
"Barcode": "1301012101021000002110322210012201313",
"Bsp": "015",
"DPID": "12345678"
},
"id": "12345678"
}
```
### ValidatedAddressNz <\> [AddressNz](#addressnz)
The ValidatedAddressNz object is used when sending and receiving data from the address identify API methods using New Zealand Sources of Truth (SoTs).
#### \_type
Type: `String`
The Address type object for the returned response (e.g. 'ValidatedAddressNz').
#### eid
Type: `String`
The encrypted ID (e.g. 'O4zqtEf98jsqhJwoNG+0S/DCFUGzuGGH').
#### fullAddress
Type: `String`
The concatenated address (e.g. '20 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011').
#### country
Type: `String`
Not currently implemented
#### postcode
Type: `String`
The Postcode component of the address (e.g. '6011').
#### townCity
Type: `String`
The Town/City component of the address (e.g. 'WELLINGTON').
#### suburb
Type: `String`
The Suburb component of the address (e.g. 'WELLINGTON CENTRAL').
#### street
Type: `String`
The Street component of the address (e.g. 'PANAMA STREET').
#### postal
Type: `String`
The Postal address (e.g. 'PO BOX 123').
#### postalNumber
Type: `String`
The Postal Number component of the Postal address (e.g. '123').
#### postalType
Type: `String`
The Postal Type component of the Postal address (e.g. 'PO BOX').
#### streetNumber
Type: `String`
The Street Number component of the address (e.g. '45A').
#### streetName
Type: `String`
The Street Name component of the address (e.g. 'PANAMA').
#### streetType
Type: `String`
The Street Type component of the address (e.g. 'STREET').
#### streetSuffix
Type: `String`
The Street Suffix component of the address (e.g. 'E').
#### buildingName
Type: `String`
The Building Name component of the address (e.g. 'ALBERT PLAZA').
#### subdwelling
Type: `String`
The Subdwelling component of the address (e.g. 'SE 202'). This includes subdwelling, floor, block and lot information.
#### flatUnitNumber
Type: `String`
The Flat Unit Number component of the address (e.g. '7A').
#### flatUnitType
Type: `String`
The Flat Unit Type component of the address (e.g. 'U').
#### floorLevelNumber
Type: `String`
The Floor Level Number component of the address (e.g. '2').
#### floorLevelType
Type: `String`
The Floor Level Type component of the address (e.g. 'FL').
#### lotNumber
Type: `String`
The Lot Number component of the address (e.g. '1').
#### id
Type: `String`
The DPID or CNAR ID of the address (e.g. '2775942').
#### exception
Type: `String`
The exception thrown from the backend.
#### attributes
Type: `Map`
A map of name/value pairs representing additional information from the Address in the Source of Truth (e.g. `{"Longitude": "12.34", "Latitude": "12.34"}`).
For example, sample attributes returned from "NZPAF" are shown below: `{"ParcelId":"3996917","XCoordinate":"2658827", "MeshblockId":"2127500","YCoordinate":"5989553", "Latitude":"-41.287171091075614","Longitude":"174.7770385563209"}`
#### JSON Representation
```json
{
"_type": "ValidatedAddressNz",
"eid": "DmQYwqF0wjGOgn2XZYMJbvLPHFLYXJEu",
"exception": null,
"id": "123456",
"fullAddress": "25 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011",
"country": null,
"postcode": "6011",
"townCity": "WELLINGTON",
"suburb": "WELLINGTON CENTRAL",
"street": "PANAMA STREET",
"postal": "",
"postalNumber": "",
"postalType": "",
"streetNumber": "25",
"streetName": "PANAMA",
"streetType": "STREET",
"streetSuffix": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"rdNumber": null,
"attributes": {
"Latitude": "-41.284123",
"Longitude": "174.776194",
"MeshblockId": "2125700",
"ParcelId": "4032109",
"XCoordinate": "2658764",
"XNztm": "1748740.49107",
"YCoordinate": "5989893",
"YNztm": "5428180.430423"
}
}
```
### AddressIntl
The AddressIntl object is used when receiving data from [retrieve](/loqate-harmony-api/api-specification/address/address-validation-and-lookup#retrieve) API method for non-Australia and New Zealand addresses. It is also used when sending and receiving data from the previous version of International address lookup `find` and `retrieve` API methods.
#### \_type
Type: `String`
The Address type object for the returned response (e.g. 'AddressIntl').
#### fullAddress
Type: `String`
The full address (e.g. '805 Veterans Blvd Ste 305, REDWOOD CITY CA 94063-1737, UNITED STATES').
#### country
Type: `String`
The country component of the address (e.g. 'United States').
#### Province
Type: `String`
The Province component of the address (e.g. 'CA').
#### postcode
Type: `String`
The Postcode component of the address (e.g. '94063-1737').
#### City
Type: `String`
The City component of the address (e.g. 'REDWOOD CITY').
#### street
Type: `String`
The Street component of the address (e.g. 'Veterans Blvd').
#### street2
Type: `String`
The Street line 2 of the address.
#### postal
Type: `String`
The Postal address (e.g. 'PO BOX 123').
#### postalNumber
Type: `String`
The Postal Number component of the Postal address (e.g. '123').
#### postalType
Type: `String`
The Postal Type component of the Postal address (e.g. 'PO BOX').
#### streetNumber
Type: `String`
The Street Number component of the address (e.g. '45A').
#### buildingName
Type: `String`
The Building Name component of the address (e.g. 'ANZAC HOUSE').
#### subdwelling
Type: `String`
The Subdwelling component of the address (e.g. 'Lowr LEVEL'). This includes subdwelling, floor and block information.
#### District
Type: `String`
The District component of the address (e.g. 'Younus Colony').
#### attributes
Type: `Map`
A map of name/value pairs representing additional information of the Address. (e.g. `{"DomesticId": "Z216947437", "Line1": "805 Veterans Blvd Ste 305"}`).
For example: `{"CountryIso2":"US","CountryIso3":"USA","DomesticId":"Z216947437","DataLevel":"Range","ProvinceName":"California", "Type":"Residential","Language":"ENG","LanguageAlternatives":"ENG","AdminAreaCode":"081", "ProvinceCode":"CA","CountryIsoNumber":"840","Line1":"805 Veterans Blvd Ste 305","AdminAreaName":"San Mateo"}`
#### JSON Representation
```json
{
"_type": "AddressIntl",
"fullAddress": "805 Veterans Blvd Ste 305, REDWOOD CITY CA 94063-1737, UNITED STATES",
"country": "United States",
"postcode": "94063-1737",
"street2": "",
"street": "Veterans Blvd",
"streetNumber": "805",
"postal": "",
"postalType": "",
"postalNumber": null,
"buildingName": "",
"subdwelling": "Ste 305",
"attributes": {
"CountryIso2": "US",
"CountryIso3": "USA",
"DomesticId": "Z216947437",
"DataLevel": "Range",
"ProvinceName": "California",
"Type": "Residential",
"Language": "ENG",
"LanguageAlternatives": "ENG",
"AdminAreaCode": "081",
"ProvinceCode": "CA",
"CountryIsoNumber": "840",
"Line1": "805 Veterans Blvd Ste 305",
"AdminAreaName": "San Mateo"
},
"id": "US|US|B|Z216947437|305",
"district": "",
"city": "Redwood City",
"province": "CA"
}
```
### AddressIntlV2 <\> [AddressIntl](#addressintl)
The AddressIntlV2 object is an [AddressIntl ](#addressintl)with only `non-null` attributes are returned. It is used for receiving data from [find ](/loqate-harmony-api/api-specification/address/address-validation-and-lookup#find)API method, for all countries including Australia and New Zealand.
#### \_type
Type: `String`
The Address type object for the returned response (e.g. 'AddressIntlV2').
#### fullAddress
Type: `String`
The full address (e.g. 'Unit 1-2, Bond Street Industrial Estate Mancunian Way Manchester, M12 6HW').
#### id
Type: `String`
The Address Id or a non-Address Id for further lookup (e.g. for United Kingdom, 'GB|RM|A|14405045' for `Address Type` and 'GB|RM|ENG|MANCHESTER---WAY-MANCUNIAN-ESTATE-BOND\_STREET\_INDUSTRIAL' for `Street Type`), for Australia with GNAF Source of Truth 'AU|GNAF|GANSW717802735' for `Address Type`.
#### attributes
Type: `Map`
A map of name and value pairs representing additional information of the Address, e.g.
* `{"Type": "Address"}` for Address Type
* `{"Type": "Street", "subdwellings": "Manchester, M12 6HW - 2 Addresses"}` for non-Address Type for non-Australia/New Zealand
* `{"Type": "Floor", "subdwellings": "4 Addresses"}` for non-Address Type for Australia/New Zealand
#### JSON Representation
For Australia addresses with GNAF Source of Truth:
```json
{
"_type": "AddressIntlV2",
"fullAddress": "20 Bond Street, Sydney NSW 2000",
"attributes": {
"Type": "BuildingNumber",
"subdwellings": "45 Addresses"
},
"id": "AU|GNAF|GANSW710271307"
},
{
"_type": "AddressIntlV2",
"fullAddress": "20 Bond Street, Oran Park NSW 2570",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GANSW718237492"
}
```
For United Kingdom addresses:
```json
{
"_type": "AddressIntlV2",
"fullAddress": "Bond Street, 17A, High Street Tenterden, TN30 6BN",
"attributes": {
"Type": "Address"
},
"id": "GB|RM|A|24769972"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Bond Street Industrial Estate Mancunian Way",
"attributes": {
"Type": "Street",
"subdwellings": "Manchester, M12 6HW - 2 Addresses"
},
"id": "GB|RM|ENG|MANCHESTER---WAY-MANCUNIAN-ESTATE-BOND_STREET_INDUSTRIAL"
}
```
### AddressList
An array or list of Address ([AddressAu](#addressau) or [AddressNz](#addressnz)) structures.
#### JSON Representation
```json
[
{
"_type": "ValidatedAddressAu",
"eid": "DmQYwqF0wjGOgn2XZYMJbvLPHFLYXJEu",
"exception": null,
"id": "123456",
"fullAddress": "25 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011",
"country": null,
"postcode": "6011",
"townCity": "WELLINGTON",
"suburb": "WELLINGTON CENTRAL",
"street": "PANAMA STREET",
"street2": null,
"postal": "",
"postalNumber": "",
"postalType": "",
"streetNumber": "25",
"streetName": "PANAMA",
"streetType": "STREET",
"streetSuffix": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"rdNumber": null,
"attributes": {
"Latitude": "-41.284123",
"Longitude": "174.776194",
"MeshblockId": "2125700",
"ParcelId": "4032109",
"XCoordinate": "2658764",
"XNztm": "1748740.49107",
"YCoordinate": "5989893",
"YNztm": "5428180.430423"
}
},
{
"_type": "ValidatedAddressAu",
"eid": "fGBUVVdCntAu6wgNVcv0ePuSac7kAbUP",
"exception": null,
"fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
"country": null,
"state": "NSW",
"postcode": "2000",
"locality": "SYDNEY",
"street": "GEORGE ST",
"postal": "",
"postalNumber": "",
"postalType": "",
"streetNumber": "220",
"streetName": "GEORGE",
"streetType": "ST",
"streetSuffix": "",
"buildingName": "",
"subdwelling": "L 2 SE 202",
"flatUnitNumber": "202",
"flatUnitType": "SE",
"floorLevelNumber": "2",
"floorLevelType": "L",
"lotNumber": "",
"attributes": {
"Barcode": "1301012101021000002110322210012201313",
"Bsp": "015",
"DPID": "12345678"
},
"id": "12345678"
}
]
```
### AddressRestRequest
An AddressRestRequest object is used when invoking the address lookup REST service methods.
#### payload
Type: [AddressList](#addresslist)
The list of Address structures being passed to the REST service method.
#### sourceOfTruth
Type: `String`
The Source of Truth (SoT) to use during the REST service method invocation (i.e. 'AUPAF', 'GNAF', 'NZPAF' or 'NZAD').
#### featureOptions
Type: [FeatureOption](#featureoption) An Object containing the values for the feature options available for Address lookups.
#### JSON Representation
```json
{
"payload": [ { "locality": "SYDNEY" } ],
"sourceOfTruth": "GNAF",
"featureOptions": { "positionFilter": "postal" }
}
```
### AddressRestResponse
An AddressRestResponse object is returned from the address lookup REST service method invocations.
#### payload
Type: [AddressList](#addresslist)
The list of Address structures being returned from the REST service method.
#### status
Type: `String`
The status of the request (i.e. 'SUCCESS' or 'ERROR').
#### messages
Type: `String[]`
Any error messages generated during the REST service method invocation (e.g. `[ "Access is denied" ]`)
#### JSON Representation
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressAu",
"fullAddress": "SYDNEY NSW 2000",
"country": null,
"state": "NSW",
"postcode": "2000",
"locality": "SYDNEY",
"street": "",
"postal": "",
"postalNumber": "",
"postalType": "",
"streetNumber": "",
"streetName": "",
"streetType": "",
"streetSuffix": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": ""
},
{
"_type": "AddressAu",
"fullAddress": "SYDNEY OLYMPIC PARK NSW 2127",
"country": null,
"state": "NSW",
"postcode": "2127",
"locality": "SYDNEY OLYMPIC PARK",
"street": "",
"postal": "",
"postalNumber": "",
"postalType": "",
"streetNumber": "",
"streetName": "",
"streetType": "",
"streetSuffix": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": ""
}
]
}
```
### FeatureOption
A FeatureOption object is used to supply option values when invoking the address lookup REST service methods.
#### displayGnafLot
Type: ("0"|"1") Flag which determines if the lot information is displayed in addresses retrieved from GNAF Source of Truth. If the flag is set to "1", the lot information will be returned. Otherwise, the lot information will not be returned. Only applicable for GNAF Source of Truth.
#### suppressLot
Type: ("0"|"1") Flag which suppresses Lot information when a street# is available in the address. If Street# is not in address then Lot information is displayed. This is used in conjunction with displayGnafLot = 1 and suppressLot = 1 to create this behavior.
#### displayTrueLocality
Type: ("0"|"1") Flag which determines whether to use the true locality or the synonym locality in the lookup result. If the flag is set to "1", the true locality will be returned. Otherwise, the synonym locality will be returned.
#### moreSources
Type: Array. The array of strings that expands datasets (source of truth) applied to the lookup result.
moreSources enables additional datasets to be searched and results shown to the end user
Address Find only.
#### positionFilter
Type: Array The array of filters to be applied to the lookup result - for AU locale only.
The *positionFilter* option has two types of filters: **Point filters** (when a specific address is retrieved) and **Locality filters** (where a locality-level address is retrieved).
**Point filters** are used for the following methods:
* [find](/loqate-harmony-api/api-specification/address/address-validation-and-lookup#find)
* [address v1 (deprecated)](/loqate-harmony-api/api-specification/deprecated/address-v1#address-lookup-methods-au-nz)
* [buildingName](#buildingname)
* [subdwelling](#subdwelling)
The option values available for Point filters are:
* POSTAL - filters only postal addresses (only available for [find ](/loqate-harmony-api/api-specification/address/address-validation-and-lookup#find)method and [address v1 (deprecated)](/loqate-harmony-api/api-specification/deprecated/address-v1#address-lookup-methods-au-nz) method)
* ROOFTOP - filters only addresses that contain one or more subdwelling addresses (e.g. unit blocks) - the subdwelling addresses are not included
* DOORSTOP - filters subdwelling addresses within 'ROOFTOP' addresses (e.g. units within a unit block) - the 'ROOFTOP' addresses are not included
* SINGLE - filters addresses that represent a single address with no subdwellings (e.g. houses)
**Locality filters** are used for the following methods:
* [locality](#locality)
* [postcode](#postcode)
The option values available for Locality filters are:
* PHYSICAL - filters localities that do not contain any addresses with a 'postal' type
* POSTAL - filters localities that only contain addresses with a 'postal' type
* BOTH - filters localities that contain at least one 'postal' address and one 'non-postal' address
#### addressTypeFilter
Type: Array The array of filters to be applied to the lookup result - for NZ locale only.
The *addressTypeFilter* option is to filter the result based on the type of delivery point in NZPAF and NZAD. It is used for [find](/loqate-harmony-api/api-specification/address/address-validation-and-lookup#find) and [address v1 (deprecated)](/loqate-harmony-api/api-specification/deprecated/address-v1#address-lookup-methods-au-nz) method for NZPAF and NZAD Source of Truth.
The option values available for Address Type filters are:
* URBAN - filters only Urban Delivery Addresses
* BOX - filters only PO Box Addresses
* BAG - filters only Private Bag Addresses
* RURAL - filters only Rural Delivery Addresses
* COUNTER - filters only Counter Delivery Addresses - PostShops, etc
* CMB URBAN - filters only Community MailBox Urban Addresses
* CMB RURAL - filters only Community MailBox Rural Addresses
There is an option to exclude Address Types by using "-" followed by the Address Type value to be excluded. For example `{"addressTypeFilter": "-urban, -rural"}` to exclude "URBAN" and "RURAL" addresses from the result.
This filter can also be used with AUPOST data set to filter out different data assets like post shops, red street posting box, parcel lockers etc.
The option values available for Address Type filters using AUPOST:
* UPL - filters only Parcel Locker addresses
* LPO - filters only Licensed Post Office addresses
* CPA - filters only Community Postal Agent addresses
* RP - filters only Postshop addresses
* RA- filters only Retail anexxe addresses
* RSPB - filters only Red Street Posting Box addresses.
* CSPB - filters only Combined Street Posting Box addresses.
#### singleLineHitNumber
Type: Integer The maximum number of results returned from the lookup. Note, modifying this value may impact the performance of the lookup.
#### caseType
Type: ("LOW"|"UP"|"TITLE") The case type for the returned addresses (single line and components). If "TITLE" is used, the returned address will be in "title" case except the Australian state abbreviation. For example: "220 George St, Sydney, NSW"
#### exposeAttributes
Type: Integer (0-7) Flag which determines which attributes to expose for the lookups.
* "1" (001) - exposes all the default original attributes.
* "2" (010) - exposes GNAFPlus attributes.
* "4" (100) - exposes extra AUPAF permission and delivery schedule attributes.
* The value can be added up for different combinations of attributes exposure. e.g. if it is "3" (001+010=011(3)), it will expose all the default original attributes + GNAFPlus attributes.
This option can be used for retrieve method, [address v1 (deprecated)](/loqate-harmony-api/api-specification/deprecated/address-v1#address-lookup-methods-au-nz), and [Address cleanse Methods](/loqate-harmony-api/api-specification/deprecated/address-cleanse#cleanse-methods-au-nz).
#### exposePhantom
Type: ("0"|"1") Flag which determines whether to expose phantom addresses for AUPAF address lookup. If the flag is set to "1", it will expose phantom address. Otherwise it will not.
#### baseSource
Type: ("GNAF"|"AUPAF") Flag is used in together with SourceOfTruth as AUSOTS. It determines which data source is used as the base for the search result. Additional information from the other source (if available) is added to the addresses from base result. Some addresses may not be found from the base result given the top number but they may be found from the other source. In this case, these addresses are appended to the result list with additional information from the base source (if available).
#### strictFieldValidation
Type: ("0"|"1") This option is only effective when the request payload has values for field `state`, `locality`, or `postcode` in addition to `fullAddress`. The default value is "1" which means it strictly limits the results in the response to the requested values for field such as state, locality or postcode. When this option is set to "0", it prioritizes the reseults with requested values in the response but it still includes other search results.
#### standardizeSource
Type: (`"AUPAF"`|`"GNAF"`|`"NZPAF"`) The source used to standardize result fields such as Street Type, Flat Unit Type, Floor Level Type, Street Suffix Type and Postal Type.
This option is only supported by the find method. It is not supported by the retrieve method — addresses returned by retrieve are always in the format of the requested Source of Truth, and the `standardizeSource` option is ignored if supplied.
#### splitNzFloorLevel
Type: ("0"|"1") If the flag is set to "1", the floor information will be splitted into "floorLevelType" and "floorLevelNumber". The flag is only available when using with "NZPAF", and will be ignored when using with other sources. The default value is "0".
#### groupAddresses
Type: ("0"|"1") A flag to control whether addresses are grouped together or not for "AUPAF" and "GNAF" Source of Truth. If the flag is set to "1", the service will try to collapse sub-dwelling addresses within the same primary address into a group to reduce clutter. This option is used for [find](/loqate-harmony-api/api-specification/address/address-validation-and-lookup#find) method and [address v1 (deprecated)](/loqate-harmony-api/api-specification/deprecated/address-v1#address-lookup-methods-au-nz) method. The default value is "0".The new Javascript client (since version 1.7.0) supports this feature.
#### radius
Type: Integer Distance in meter from the origin to search. It is used by reverseGeocode API and the default value is 50 meters.The new Javascript client (since version 1.7.0) supports this feature.
#### prioritizedSort
Type: ("0"|"1") Flag which determines whether to sort the locality information based on popularity of addresses for the locality search API. If the flag is set to "1", the locality search result will be sorted by popularity. By default, the value is "1".
#### exposeChanges
Type: ("0"|"1") Flag which determines whether to include PDP change item in CLEANSE API response. If the flag is set to "1", PDP changed items will be exposed. By default, it will not be exposed.
#### JSON Representation
```json
{
"displayGnafLot": 1,
"singleLineHitNumber": 30,
"displayTrueLocality": 1,
"positionFilter": "postal,doorstop,rooftop,single",
"addressTypeFilter": "urban,box,bag,rural,counter,cmb urban,cmb rural",
"caseType": "TITLE",
"exposeAttributes": "1",
"exposePhantom": "0",
"baseSource": "AUPAF",
"standardizeSource": "GNAF",
"splitNzFloorLevel": 1,
"groupAddresses": "1",
"radius": 100,
"prioritizedSort": 1,
"exposeChanges": 1
}
```
# Address Type Objects
Address type information applicable for ANZ only
## Address Type Objects
| [Metadata](#universal) | Wrapper for name/value pairs. |
| ------------------------------------------- | --------------------------------------- |
| [MetadatList](#addressau) | Container for Metadata objects. |
| [MetadataRestRequest](#addressnz) | Request wrapper for type REST methods. |
| [MetadataRestResponse](#validatedaddressau) | Response wrapper for type REST methods. |
### Metadata
The Metadata object is used when receiving data from the Harmony RightAddress metadata API methods.
#### name
Type: `String`
The displayable name of the metadata item (e.g. 'LOWER GROUND').
#### value
Type: `String`
The value of the metadata item (e.g. 'LG')
#### JSON Representation
```json
{
"name": "CUL-DE-SAC",
"value": "CDS"
}
```
### MetadataList
A MetadataList object is an array or list of Metadata structures. It is used to transport multiple instances of Metadata objects (e.g. to return a list of Floor Level or Flat/Unit types).
#### JSON Representation
```json
[
{
"name": "ACCESS",
"value": "ACCS"
},
{
"name": "ACCS",
"value": "ACCS"
},
{
"name": "ALLEY",
"value": "ALLY"
},
...
]
```
### MetadataRestRequest
A MetadataRestRequest object is used when invoking the Harmony RightAddress metadata REST service methods.
#### sourceOfTruth
Type: `String`
The Source of Truth to use during the REST service method invocation (i.e. 'AUPAF', 'GNAF', 'NZPAF' or 'NZAD'").
#### JSON Representation
```json
{
"sourceOfTruth": "AUPAF"
}
```
### MetadataRestResponse
A MetadataRestResponse object is returned from the Harmony RightAddress metadata REST service method invocations.
#### payload
Type: [`MetadatList`](#addressau)
The list of Metadata structures being returned from the REST service method invocation.
#### status
Type: `String`
The status of the request (i.e. 'SUCCESS' or 'ERROR').
#### messages
Type: `String[]`
Any error messages generated during the REST service method invocation (e.g. '\[ "Access is denied" ]').
#### JSON Representation
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [ { "name": "ACCESS", "value": "ACCS" }, ... ]
}
```
# Suburb Objects
# Parse Objects
## Parse Objects
| [ParsedAddressAu](#parsedaddressau) | The result of a parsed Australian Address. |
| ----------------------------------- | ------------------------------------------- |
| [ParsedAddressNz](#parsedaddressnz) | The result of a parsed New Zealand Address. |
### ParsedAddressAu <\> [AddressAu](/loqate-harmony-api/api-specification/objects/address-objects#addressau)
A ParsedAddressAu object extends a standard AddressAu object and is returned in the parse method response for Australian addresses.
See [AddressAu](/loqate-harmony-api/api-specification/objects/address-objects#addressau) for inherited attributes.
#### careOf
Type: StringAn optional 'Care Of' value for the parsed address.
#### exception
Type: StringA message outlining any errors that occuring during the parse process (e.g. "Not enough information").
#### JSON Representation
```
{
"attributes": null,
"exception": null,
"fullAddress": "c/o Bob Flemming, L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
"country": "",
"postcode": "2000",
"street2": "",
"street": "GEORGE ST",
"streetName": "GEORGE",
"streetSuffix": "",
"streetType": "ST",
"streetNumber": "220",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "L 2 SE 202",
"flatUnitNumber": "202",
"flatUnitType": "SE",
"floorLevelNumber": "2",
"floorLevelType": "L",
"lotNumber": null,
"eid": null,
"id": null,
"careOf": "c/o Bob Flemming",
"exception": null,
"locality": "SYDNEY",
"state": "NSW"
}
```
### ParsedAddressNz <\> [AddressNz](/loqate-harmony-api/api-specification/objects/address-objects#addressnz)
A ParsedAddressAu object extends a standard AddressNz object and is returned in the parse method response for New Zealand addresses.
See [AddressNz ](/loqate-harmony-api/api-specification/objects/address-objects#addressnz)for inherited attributes.
#### careOf
Type: StringAn optional 'Care Of' value for the parsed address.
#### exception
Type: StringA message outlining any errors that occuring during the parse process (e.g. "Not enough information").
#### JSON Representation
```
{
"fullAddress": "c/o Bob Flemming, 25 PANAMA STREET, WELLINGTON CENTRAL, WELLINGTON 6011",
"attributes": null,
"country": "",
"postcode": "6011",
"street": "PANAMA STREET",
"streetName": "PANAMA",
"streetSuffix": "",
"streetType": "STREET",
"streetNumber": "25",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": null,
"id": null,
"exception": null,
"careOf": "c/o Bob Flemming",
"exception": null,
"townCity": "WELLINGTON",
"suburb": "WELLINGTON CENTRAL"
}
```
# Email Objects
| [EmailAddress](#emailaddress) | An Email address for validation. |
| ----------------------------------------------- | ----------------------------------------------------------------- |
| [EmailList](#emaillist) | Container for Email addresses. |
| [EmailRestRequest](#emailrestrequest) | Request wrapper for email REST methods. |
| [EmailRestResponse](#emailrestresponse) | Response wrapper for email REST methods. |
| [ValidatedEmailAddress](#validatedemailaddress) | An Email address object containing the results of the validation. |
### EmailAddress
The EmailAddress is used to supply email addresses for validation.
#### address
Type: StringThe email address (e.g. '').
#### JSON Representation
```json
{
"address": "bob@example.org"
}
```
### EmailList
An array or list of EmailAddress structures.
#### JSON Representation
```json
[
{
address: "bob@example.org"
},
{
address: "sarah@example.org"
},
...
]
```
### EmailRestRequest
An EmailRestRequest object is used when invoking the Harmony RightAddress email validation REST service methods.
#### payload
Type: [EmailList](#emaillist)
The list of EmailAddress structures being passed to the REST service method.
**sourceOfTruth**
Type: String
The Source of Truth to use for the validation.
**featureOptions**
Type: [FeatureOption](#featureoption)
An Object containing the values for the feature options available for the validation.
#### JSON Representation
```json
{
"payload": [ { "address": "bob@example.org" } ],
"sourceOfTruth": "VE_ALL",
"featureOptions: { "timeout": "1500" }
}
```
### EmailRestResponse
An EmailRestResponse object is returned from the Harmony RightAddress email validation REST service methods.
#### payload
Type: [EmailList](#emaillist)
The list of EmailAddress structures being returned from the REST service method.
#### status
Type: String
The status of the request (i.e. 'SUCCESS' or 'ERROR').
#### messages
Type: String\[]
Any error messages generated during the REST service method invocation (e.g. '\[ "Access is denied" ]')
#### JSON Representation
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"address": "bob@example.org"
}
]
}
```
### ValidatedEmailAddress <\> [EmailAddress](#emailaddress)
A ValidatedEmailAddress object extends a standard EmailAddress object and is returned in the validate method response.
See [EmailAddress ](#emailaddress)for inherited attributes.
#### formatValidated
Type: Boolean
`email_valid`: true if the email address syntax conforms to RFC 2822 standard, false otherwise.
#### blackListValidated
Type: Boolean
True if the email address does not appear in the internal email block list, false otherwise.
#### domainValidated
Type: Boolean
`domain_exists`: true if the domain of the email address exists and has proper Domain Name Server (DNS) records, false otherwise.
#### mailServerValidated
Type: Boolean
`mailserver_exists`: True if there is a mail server for that domain, false otherwise.
#### mailboxValidated
Type: Boolean
`email_exists`: true if the mailbox for the email address has been found to exist without sending an email, false otherwise.
#### JSON Representation
```json
{
"address": "bob@example.org",
"mailBoxValidated": false,
"mailServerValidated": false,
"domainValidated": false,
"blackListValidated": true,
"formatValidated": true
}
```
### FeatureOption
A FeatureOption object is used to supply option values when invoking the email validation REST service methods.
#### timeout
Type: String
Value of the timeout in milliseconds, if the validation process takes longer than the time specified, timeout error message will be given. Default value is 10000ms (10 seconds).
#### JSON Representation
```json
{
"timeout": "1500"
}
```
# Phone Objects
| [Phone](#phone) | A Phone number for validation. |
| --------------------------------------- | --------------------------------------------------------------- |
| [PhoneList](#phonelist) | Container for Phone numbers. |
| [PhoneRestRequest](#phonerestrequest) | Request wrapper for phone REST methods. |
| [PhoneRestResponse](#phonerestresponse) | Response wrapper for phone REST methods. |
| [ValidatedPhone](#validatedphone) | A Phone number object containing the results of the validation. |
### Phone
The Phone structure is used to supply mobile phone numbers for validation.
#### fullPhone
Type: `String`. The mobile phone number with optional country code (e.g. '+61412345678').
#### country
Type: `String`. The two-character country code to be used for the validation (e.g. 'AU').
#### JSON Representation
```
{
"fullPhone": "+61412345678",
"country": "AU"
}
```
### PhoneList
An array or list of Phone structures.
#### JSON Representation
```
[
{
"fullPhone": "+61412345678",
"country": "AU"
},
{
"fullPhone": "+61487654321",
"country": "AU"
},
...
]
```
### PhoneRestRequest
An PhoneRestRequest object is used when invoking the Harmony RightAddress phone validation REST service methods.
#### payload
Type: [PhoneList](#phonelist) The list of Phone structures being passed to the REST service method.
#### JSON Representation
```
{
"payload":
[
{
"fullPhone": "+61412345678",
"country": "AU"
},
{
"fullPhone": "+61487654321",
"country": "AU"
},
...
]
}
```
### PhoneRestResponse
An PhoneRestResponse object is returned from the Harmony RightAddress phone validation REST service methods.
#### payload
Type: [PhoneList](#phonelist) The list of Phone structures being returned from the REST service method.
#### status
Type: `String`. The status of the request (i.e. 'SUCCESS' or 'ERROR').
#### messages
Type: `String[]`. Any error messages generated during the REST service method invocation (e.g. '\[ "Access is denied" ]')
#### JSON Representation
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullPhone": "+61412345678",
"country": "AU"
}
]
}
```
### ValidatedPhone <\> [Phone](#phone)
A ValidatedPhone object extends a standard Phone object and is returned in the validate method response.
See[ Phone](#phone) for inherited attributes.
#### countryCode
Type: `String`. Any country code associated with the supplied phone number (e.g. '+61').
#### areaCode
Type: `String`. Any area code associated with the supplied (non-mobile) phone number (e.g. '02').
#### localNumber
Type: `String`. The local part of the supplied number (e.g. '12345678')
#### operatorName
Type: `String`. The mobile operator associated with the supplied number (e.g. 'Vodafone Australia')
#### phoneStatus
Type: `String`. The current status of the mobile phone with the supplied number (e.g. 'connected|Network confirmed connection', 'disconnected|Network confirmed disconnection', 'indeterminate').
#### exception
Type: `String`. An exception message outlining the errors that occurred during validation for the phone numbers with 'indeterminate' phone status. (e.g. 'Number prefix missing', 'Network is forbidden', 'Invalid destination address.').
#### JSON Representation
```
{
"fullPhone": "+61412345678",
"country": "AU",
"countryCode": "61",
"areaCode": "",
"localNumber": "412345678",
"operatorName": "Vodafone Australia",
"phoneStatus": "connected|Network confirmed connection",
"exception": ""
},
{
"fullPhone": "61488888888",
"country": "AU",
"countryCode": "61",
"areaCode": "",
"localNumber": "488888888",
"operatorName": "Unknown",
"phoneStatus": "disconnected|Network confirmed disconnection",
"exception": ""
},
{
"fullPhone": "04123456789",
"country": "AU",
"countryCode": null,
"areaCode": null,
"localNumber": null,
"operatorName": "",
"phoneStatus": "indeterminate",
"exception": "Number prefix missing"
},
{
"fullPhone": "+64412345678",
"country": "NZ",
"countryCode": "64",
"areaCode": "",
"localNumber": "412345678",
"operatorName": "",
"phoneStatus": "indeterminate",
"exception": "Invalid destination address."
},
{
"fullPhone": "02 12345678",
"country": "AU",
"countryCode": "",
"areaCode": "02",
"localNumber": "12345678",
"operatorName": "",
"phoneStatus": "indeterminate",
"exception": "Network is forbidden"
}
```
# Property Title Objects
| [PropertyTitleInfo](#propertytitleinfo) | A PropertyTitle info for validation. |
| --------------------------------------------------------- | --------------------------------------------------------------- |
| [PropertyTitleRestRequest](#propertytitlerestrequest) | Request wrapper for PropertyTitle info validation REST methods. |
| [PropertyTitleRestResponse](#propertytitlerestresponse) | Response wrapper for PropertyTitle info REST methods. |
| [ValidatedPropertyTitleInfo](#validatedpropertytitleinfo) | A object containing the results of the validation. |
### PropertyTitleInfo
The PropertyTitleInfo structure is used to supply the information for validation.
#### firstName
Type: StringThe First name of the person (e.g. 'Smith').
#### lastName
Type: StringThe last name of the person (e.g. 'John').
#### latitude
Type: StringThe Latitude of the address (e.g. '-33.25933673').
#### longitude
Type: StringThe Longitude of the address (e.g. '151.54871059').
#### postcode
Type: StringThe Postcode component of the address (e.g. '2000').
#### townCity
Type: StringThe Town/City component of the address (e.g. 'WELLINGTON').
#### suburb
Type: StringThe Suburb component of the address (e.g. 'WELLINGTON CENTRAL').
#### street
Type: StringThe Street component of the address (e.g. 'GEORGE STREET').
#### streetNumber
Type: StringThe Street Number component of the address (e.g. '45A').
#### postal
Type: StringThe Postal address (e.g. 'PO BOX 123').
#### subdwelling
Type: StringThe Subdwelling component of the address (e.g. 'SE 202'). This includes subdwelling, floor, block and lot information.
#### JSON Representation
```
{
"firstName":"John",
"lastName":"Doe",
"streetNumber":"000",
"street":"xxxx st",
"suburb":"wellington central",
"townCity":"wellington"
}
```
### PropertyTitleRestRequest
An PropertyTitleRestRequest object is used when invoking the Harmony RightAddress nz property title ownership validation REST service methods.
#### payload
Type: [PropertyTitleInfo](#propertytitleinfo) The PropertyTitleInfo structure being passed to the REST service method.
#### showDetails
Type: BooleanShow details of the property title in the response or not (i.e. 'true' or 'false'). Default is false.
#### JSON Representation
```
{
"payload":{
"firstName":"John",
"lastName":"Doe",
"streetNumber":"000",
"street":"xxxx st",
"suburb":"wellington central",
"townCity":"wellington"
},
"showDetails":"true"}
}
```
### PropertyTitleRestResponse
An PropertyTitleRestResponse object is returned from the Harmony RightAddress nz property title ownership validation REST service methods.
#### payload
Type: [ValidatedPropertyTitleInfo ](#validatedpropertytitleinfo)The ValidatedPropertyTitleInfo structure being returned from the REST service method.
#### status
Type: StringThe status of the request (i.e. 'SUCCESS' or 'ERROR').
#### messages
Type: String\[]Any error messages generated during the REST service method invocation (e.g. '\[ "Access is denied" ]')
#### JSON Representation
```
{
{
"status":"SUCCESS",
"messages":[],
"payload":{
"response":"fail",
"attributes":[
{"type":"NZ_PROPERTY_TITLE",
"attributes":{
"guaranteeStatus":"Guarantee",
"status":"LIVE",
"descrption":"Fee Simple, 1/1, Lot x Deposited Plan xxx, 401 m2",
"spatialExtensShared":"T",
"ownsNumber":"1",
"issueDate":"1986/09/10 00:00:00",
"titleNo":"xxxx",
"type":"Freehold",
"owners":"xxxx",
"titleId":"xxxx",
"landDistrict":"Wellington"
}
}
]
}
}
}
```
### ValidatedPropertyTitleInfo
A ValidatedPropertyTitleInfo object with validation response and list of attributes if showDetails set as true in the request.
#### response
Type: StringThe response of the validation (i.e. 'pass' or 'fail').
#### attributes
A list of attributes for the property title
#### JSON Representation
```
{
"response":"fail",
"attributes":[
{"type":"NZ_PROPERTY_TITLE",
"attributes":{
"guaranteeStatus":"Guarantee",
"status":"LIVE",
"descrption":"Fee Simple, 1/1, Lot x Deposited Plan xxx, 401 m2",
"spatialExtensShared":"T",
"ownsNumber":"1",
"issueDate":"1986/09/10 00:00:00",
"titleNo":"xxxx",
"type":"Freehold",
"owners":"xxxx",
"titleId":"xxxx",
"landDistrict":"Wellington"
}
}
]
}
```
# Match Objects
| [CustomerData](#customerdata) | CustomerData information. |
| ----------------------------------------------- | ----------------------------------------------- |
| [CustomerDataList](#customerdatalist) | CustomerData container. |
| [MatchRequest](#matchrequest) | MatchRequest object. |
| [MatchRestRequest](#matchrestrequest) | Request wrapper for match lookup REST methods. |
| [MatchEntityResult](#matchresult) | MatchEntityResult information. |
| [MatchEntityResultList](#matchentityresultlist) | MatchEntityResult container. |
| [MatchResult](#matchresult-1) | MatchResult information. |
| [MatchResultList](#matchresultlist) | MatchResult container. |
| [MatchResultRestResponse](#companyrestresponse) | Response wrapper for match lookup REST methods. |
### CustomerData
The CustomerData object is used when sending data for the match lookup API methods.
#### id
Type: StringThe identifier for each data set.
#### addresses
Type: [AddressList ](/loqate-harmony-api/api-specification/objects/address-objects#addresslist)The address list in a data set. Only one address is allowed for one data set.
#### emailAddresses
Type: [EmailList ](/loqate-harmony-api/api-specification/objects/email-objects#emaillist)The email address list in a data set. Only one email address is allowed for one data set.
#### phones
Type: [PhoneList](/loqate-harmony-api/api-specification/objects/phone-objects#phonelist) The phone list in a data set. Only one phone is allowed for one data set.
#### JSON Representation
```
{
"id": "c1",
"addresses": [ { "fullAddress": "level 2, 220 george street, sydney nsw 2000" } ],
"emailAddresses": [ { "address": "test@mydomain.com" } ],
"phones": [ { "fullPhone": "12345678" } ]
}
```
With address components:
```
{
"id": "r2",
"addresses": [ {
"floorLevelNumber": "2",
"floorLevelType": "level",
"streetName": "george",
"streetNumber": "220",
"streetType": "street",
"locality":"sydney",
"state":"nsw"
} ],
"phones": [ { "fullPhone": "12345678" } ]
}
```
### CustomerDataList
An array or list of [CustomerData ](#customerdata)structures.
#### JSON Representation
```
{
"id": "c1",
"addresses": [ { "fullAddress": "level 2, 220 george street, sydney nsw 2000" } ],
"emailAddresses": [ { "address": "test@mydomain.com" } ],
"phones": [ { "fullPhone": "12345678" } ]
}
```
With address components:
```
{
"id": "r2",
"addresses": [ {
"floorLevelNumber": "2",
"floorLevelType": "level",
"streetName": "george",
"streetNumber": "220",
"streetType": "street",
"locality":"sydney",
"state":"nsw"
} ],
"phones": [ { "fullPhone": "12345678" } ]
}
```
### MatchRequest
A MatchRequest object is used when sending data from the customer match API methods.
#### from
Type: [CustomerDataList ](#customerdatalist)The list of CustomerData structures representing the Customer Record (CR) data set. Only one data set is allowed for CR.
#### to
Type: [CustomerDataList ](#customerdatalist)The list of CustomerData structures representing the Reference Record (RR) data set. Multiple data sets are allowed for RR.
#### JSON Representation
```
{
"from": [
{
"addresses": [ { "fullAddress": "220 george street, sydney nsw 2000" } ],
"id": "c1"
}
],
"to": [
{
"addresses": [ { "fullAddress": "220 george street, sydney nsw 2000" } ],
"id": "r1"
},
{
"addresses": [ { "fullAddress": "level 2, 220 george street, sydney nsw 2000" } ],
"id": "r2"
}
]
}
```
### MatchRestRequest
A MatchRestRequest object is used when invoking the match lookup REST service methods.
#### payload
Type: [MatchRequest ](#matchrequest)The MatchRequest object being passed to the REST service method.
#### featureOptions
Type: [FeatureOption ](/loqate-harmony-api/api-specification/objects/address-objects#featureoption)An Object containing the values for the feature options available for Match Lookup. Currently is not implemented.
#### JSON Representation
```
{
"payload": {
"from": [
{
"addresses": [ { "fullAddress": "220 george street, sydney nsw 2000" } ],
"id": "c1"
}
],
"to": [
{
"addresses": [ { "fullAddress": "220 george street, sydney nsw 2000" } ],
"id": "r1"
},
{
"addresses": [ { "fullAddress": "level 2, 220 george street, sydney nsw 2000" } ],
"id": "r2"
}
]
}
}
```
### MatchEntityResult
The MatchEntityResult object is used when receiving data for the match lookup API methods.
#### addressPairIdx
Type: List of IntegerThe indexes of the matched addresses.
#### emailAddressPairIdx
Type: List of IntegerThe indexes of the matched email addresses.
#### phonePairIdx
Type: List of IntegerThe indexes of the matched phones.
#### assignedMatchClass
Type: StringThe assigned match class.
#### confidenceLevel
Type: StringThe match confidence level.
#### description
Type: StringThe description of the match class.
#### matchCategory
Type: StringThe match category.
#### JSON Representation
```
{
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [ 0, 0 ],
"assignedMatchClass": "H1",
"confidenceLevel": "10",
"description": "Household Match Class H1",
"matchCategory": "MATCH_CLASS"
}
```
### MatchEntityResultList
An array or list of [MatchEntityResult ](#matchresult)structures. Currently will only return one [MatchEntityResult ](#matchresult)in the list.
#### JSON Representation
```
"entityResults": [
{
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [ 0, 0 ],
"assignedMatchClass": "H1",
"confidenceLevel": "10",
"description": "Household Match Class H1",
"matchCategory": "MATCH_CLASS"
},
{
. . . .
}
]
```
### MatchResult
The MatchResult object is used when receiving data for the match lookup API methods.
#### fromId
Type: StringThe identifier for Customer Record (CR) data set.
#### toId
Type: StringThe identifier for Reference Record (RR) data set.
#### entityResults
Type: [MatchEntityResultList](#matchentityresultlist) The MatchEntityResult list for the corresponding fromId and toId.
#### JSON Representation
```
{
"fromId": "c1",
"toId": "r1",
"entityResults": [ {
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [ 0, 0 ],
"assignedMatchClass": "H1",
"confidenceLevel": "10",
"description": "Household Match Class H1",
"matchCategory": "MATCH_CLASS"
} ]
}
```
### MatchResultList
An array or list of [MatchResult ](#matchresult-1)structures.
#### JSON Representation
```
{
"fromId": "c1",
"toId": "r1",
"entityResults": [ {
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [ 0, 0 ],
"assignedMatchClass": "H1",
"confidenceLevel": "10",
"description": "Household Match Class H1",
"matchCategory": "MATCH_CLASS"
} ]
},
{
"fromId": "c1",
"toId": "r2",
"entityResults": [ {
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [],
"assignedMatchClass": "G2",
"confidenceLevel": "8",
"description": "Address Match Class G2",
"matchCategory": "MATCH_CLASS"
} ]
}
```
### MatchResultRestResponse
A [MatchResultRestResponse ](#companyrestresponse)object is returned from the match lookup REST service methods.
#### payload
Type: [MatchResultList ](#matchresultlist)The list of MatchResult structures being returned from the REST service method.
#### status
Type: StringThe status of the request (i.e. 'SUCCESS' or 'ERROR').
#### messages
Type: String\[]Any error messages generated during the REST service method invocation (e.g. '\[ "Access is denied" ]')
#### JSON Representation
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fromId": "c1",
"toId": "r1",
"entityResults": [ {
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [ 0, 0 ],
"assignedMatchClass": "H1",
"confidenceLevel": "10",
"description": "Household Match Class H1",
"matchCategory": "MATCH_CLASS"
} ]
},
{
"fromId": "c1",
"toId": "r2",
"entityResults": [ {
"addressPairIdx": [ 0, 0 ],
"emailAddressPairIdx": [],
"phonePairIdx": [],
"assignedMatchClass": "G2",
"confidenceLevel": "8",
"description": "Address Match Class G2",
"matchCategory": "MATCH_CLASS"
} ]
}
]
}
```
# Business Objects
| [BusinessRequest](#businessrequest) | Request wrapper for REST methods. |
| --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| [HostedBusinessRestResponse](#hostedbusinessrestresponse) | Response wrapper for REST methods |
| [BusinessSummary](#businesssummary) | Business summary information from [find ](/loqate-harmony-api/api-specification/business-validation#find)API |
| [BusinessDetail](#businessdetail) | Detail information of Business from [retrieve ](/loqate-harmony-api/api-specification/business-validation#retrieve)API. |
| [BusinessEntity](#businessentity) | Object which is included in the [BusinessDetail ](#businessdetail)for other names of the entity |
### BusinessRequest
BusinessRequest object is used when invoking the Harmony RightAddress business [Find](/loqate-harmony-api/api-specification/business-validation#find)/[Retrieve ](/loqate-harmony-api/api-specification/business-validation#retrieve)REST service methods. (\* means mandatory field)
**name\***
Type: String. Mandatory field for both Find/Retrieve API.
For [Find](/loqate-harmony-api/api-specification/business-validation#find) API ,it can be a business number, company or any entity names.
For [Retrieve](/loqate-harmony-api/api-specification/business-validation#retrieve) API, it can be Id value from Find API or clear text business/company number.
**country\***
Type: String. Country ISO2 code. (e.g. AU)
**hits**
Type: Integer. Optional, the maximum number of results returned from the lookup. If empty default will be 20.
**taxStatus**
Type: String. TAX/GST status want to search, default will be empty which will search ALL. ACT -> Active, CAN -> Cancelled, NON -> None
**bnStatus**
Type: String. Business number status want to search, default will be empty which will search ALL. ACT -> Active, CAN -> Cancelled
**nameTypes**
Type: String Array. Depending on country the available filters differ. Entity types want to search from, default will search ALL. \["TRD", "BN", "OTN"] -> search against trading names and business names
Australia:
* MN → main entity name;
* LGL → legal entity name (individuals/sole traders). Use with MN;
* TRD → trading name in Other Entity;
* BN → business name in Other Entity;
* OTN → other name in Other Entity;
* PRV → Australian Private Company
* DGR → deductible gift recipient
Note: Here is the link to the complete list of entity types →
New Zealand:
* MN → main entity name;
* TRD → trading name in Other Entity;
* OTN → other name in Other Entity;
**state**
Type: String Array. The state of the entity for searching, default will search ALL. It accept multiple states. e.g. \["NSW", "QLD"] -> search against NSW and QLD entities
**caseType**
Type: String. Case type for entity name, default is whatever the case in the reference data. *Available values* : UP, LOW, TITLE.
#### JSON Representation
```json
{
"name": "name, abn or acn",
"hits": 20,
"country": "au",
"taxStatus": "ACT",
"bnStatus": "ACT",
"nameTypes": [
"MN",
"BN"
],
"state": [
"VIC",
"NSW"
],
"caseType": "UP"
}
```
### HostedBusinessRestResponse
An HostedBusinessRestResponse object is returned from the Harmony RightAddress Business find/retrieve REST service method invocation
#### payload
Type: The list of [BusinessSummary ](#hostedbusinesssummary)for find API or list of [BusinessDetail ](#businessdetail)for retrieve API
#### status
Type: String. The status of the request (i.e. 'SUCCESS' or 'ERROR').
#### messages
Type: String Array. Any error messages generated during the REST service method invocation (e.g. '\[ "Access is denied" ]')
#### JSON Representation
For Find API
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "INSURANCE ADVICE & ADVOCACY STONES CORNER",
"bn": "xxxxx1825",
"postcode": "4120",
"id": "XEE0eyRpm1UY80rNOdIDvQ=="
},
{
"name": "Insurance Glass",
"bn": "xxxxx8910",
"postcode": "6172",
"id": "dETz7USYQoDM1OuyzrjmLQ=="
}]
}
```
### BusinessSummary
BusinessSummary is the result from the [find ](/loqate-harmony-api/api-specification/business-validation#find)API. It contains summary information of the business. id can be used for retrieve API for full information of the business entity.
**name**
Type: String. The Main or Legal name of the business entity.
**bn**
Type: String. Partial business number of the business entity, in order to get the all information will require to call the retrieve API.
**postcode**
Type: String. Postcode of the business entity.
**id**
Type: String. Id to use for the retrieve API call in order to get [full detail of the business entity](#businessdetail) information.
#### JSON Representation
```json
{
"name": "INSURANCE ADVICE & ADVOCACY STONES CORNER",
"bn": "xxxxx1825",
"postcode": "4120",
"id": "XEE0eyRpm1UY80rNOdIDvQ=="
}
```
### BusinessDetail
BusinessDetail is the object return from the [retrieve ](/loqate-harmony-api/api-specification/business-validation#retrieve)API. It includes a list of [BusinessEntity ](#businessentity)object for other names of the business entity.
**name**
Type: String. Main/Legal name of the business entity.
**country**
Type: String. Country ISO2 code. (e.g. AU)
**bn**
Type: String. Business number of the entity.
**cn**
Type: String. Company number of the entity.
**postcode**
Type: String. Postcode of the business entity.
**state**
Type: String. State of the business entity.
**name\_entity\_type**
Type: String. Type of the name of the entity. MN → Main Entity Name; LGL → legal Entity Name.
**other\_entities**
Type: List of [BusinessEntity ](#businessentity)object for other entity names.
**last\_updated\_date**
Type: String. The last updated date.
**bn\_status**
Type: String. Status of the business number. ACT -> Active, CAN -> Cancelled.
**bn\_status\_from\_date**
Type: String. Date of the business number from
**entity\_type\_ind**
Type: String. Indicator of the entity type with description the the entity\_type\_text field.
**entity\_type\_text**
Type: String. Description for the entity\_type\_ind value.
**tax\_status**
Type: String. The status of the GST. ACT -> Active, CAN -> Cancelled, NON -> None.
**tax\_status\_from\_date**
Type: String. The date for the tax\_status value*.* If tax\_status is NON, date value is 19000101 .
**attributes**
Type: List of name value pairs for extra attributes.
#### JSON Representation
```json
{
"name": "SIMON PETER KENDALL",
"bn": "51321301825",
"state": "QLD",
"postcode": "4120",
"country": "au",
"name_entity_type": "LGL",
"other_entities": [
{
"entity_name": "INSURANCE ADVICE & ADVOCACY STONES CORNER",
"entity_type": "BN"
}
],
"last_updated_date": "20190510",
"bn_status": "CAN",
"bn_status_from_date": "20190510",
"entity_type_ind": "IND",
"entity_type_text": "Individual/Sole Trader",
"tax_status": "NON",
"tax_status_from_date": "19000101"
}
```
### BusinessEntity
BusinessEntity object is used for other business entities names like other trading name etc. One [Business ](#businessdetail)can have a list of BusinessEntity objects if applicable.
**entity\_name**
Type: String. Name of the business entity.
**entity\_type**
Type: String. Type of the name. TRD → trading name; BN → business name ; OTN → other name; DGR → DGR name.
#### JSON Representation
```json
{
"entity_name": "INSURANCE ADVICE & ADVOCACY STONES CORNER",
"entity_type": "BN"
}
```
# Deprecated API services
Depreciated or planned end of life for existing services.
### Address Lookup & Validation v1 (HRA v1.0)
### Legacy RightAddress (LRA)
### Legacy Datasan - Address
### Address Cleanse v1.0
### Email Validation v1.0 & v1.1
### Address International
### Address Combined
# Email Validation v1.1
Performs a full mailbox validation on the supplied email address.
Version 1.1
Takes one or more email addresses as an input and performs validation, returning a list of the results. The maximum number of input email addresses is 100 per call.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/validate/email
```
#### Request
The request body is an [EmailRestRequest ](/loqate-harmony-api/api-specification/objects/email-objects#emailrestrequest)object:
```json
{
"payload": [
{ "address": "jim@hotmail.com" },
{ "address": "thiswilltimeout@email.com" }
],
"sourceOfTruth": "VE_ALL",
"featureOptions: { "timeout": "1500" }
}
```
#### Response
The response body is an [EmailRestResponse](/loqate-harmony-api/api-specification/objects/email-objects#emailrestresponse) object. Sample responses below:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"address": "jim@hotmail.com",
"attributes": {
"domain_exists": "VALID",
"mailserver_exists": "VALID",
"email_valid": "VALID",
"message": "Email address does not exist on mail server.",
"email_exists": "INVALID",
"do_not_mail": "FALSE",
"disposable": "FALSE",
"rolebased": "FALSE",
"catchall": "FALSE",
"spamtrap": "FALSE",
"abuse": "FALSE",
"free_email": "TRUE",
"accountname": "jim",
"domain": "hotmail.com",
"domain_age_days": "1052",
"suggested_email": "",
"deliverable": "VALID",
"hashsha256": "4c93fb55adc0297ee4086a8d047ff7ca694784c690703eab0f215685db180f37",
"hashmd5": "3e9385d795906ee1a3e04aa93bfa3a41",
"hashsha1": "7a90bf8dcac4717728d4f36e291ff17255dadeb2"
},
"domainValidated": true,
"mailServerValidated": true,
"mailBoxValidated": false,
"blackListValidated": true,
"formatValidated": true
},
{
"address": "thiswilltimeout@email.com",
"attributes": {
"hashsha1": "b89406e03dd7cf89e55c1353f9fd3f5e940abbf4",
"hashmd5": "04097aeaaafe1b91144a006ea0dc2921",
"hashsha256": "ffc36bbab1970bfa0aeef8fdb989f396dea4d0ad2f7df3d6dd2349430c71a944",
"domain_exists": "UNKNOWN",
"mailserver_exists": "UNKNOWN",
"email_valid": "UNKNOWN",
"message": "Timeout Exceeded",
"email_exists": "UNKNOWN"
},
"formatValidated": true,
"blackListValidated": true,
"domainValidated": false,
"mailServerValidated": false,
"mailBoxValidated": false
}
]
}
```
**Response Elements**
The response attributes are listed below. These are listed in the order expected when validating email addresses.
Element Name
Description
Example
address
the email address that is being validated.
jim@hotmail.com
mailBoxValidated
if the mailbox is valid and deliverable if true
true/false
mailServerValidated
Determines if the mailserver is valid or not.
true/false
domainValidated
Determines if the domain is valid or not.
true/false
blackListValidated
Determines if the user has blocked this email address.
### Response timings
We make live calls to domains located all around the world that have variable protocols and capacities. The vast majority of calls, in particular to major ISP's operate within the desire response times. A small amount a domains will result in network, server latency and security protocols variables like mail transfer agents that can impact the overall latency of the service.
This is an industry wide issue when sending requests to domains around the world. Our expected ranges of performance results are:
* 96%-98% of all domains sit between 1 to 5 seconds.
* All the major ISP's are 1 to 3 secs.
* 2%-4% will take longer than 5 seconds.
This can causing impacts in your customer experience. If this is an issue for your implementation we recommend implementing a timeout function when calling our Email Validation API and handling as an 'unknown' response to the end user.
# Address v1
{% hint style="danger" %}
These methods have been deprecated.
We recommend you upgrade your service to the latest [Address Validation method](/loqate-harmony-api/api-specification/address/address-validation-and-lookup). Upgrade at no cost and improved performance.
{% endhint %}
## Address lookup methods (AU/NZ)
Address lookup methods take complete or partial address information as an input and perform a search against an address Source of Truth, returning address information that matches the search parameters.
| [address](#address) | Lookup addresses using a single-line input address. |
| ----------------------------------------- | ----------------------------------------------------------------------------------------------- |
| [buildingName](#buildingname) | Lookup building names. |
| [locality (AU only)](#locality) | Lookup Australian localities. |
| [postal](#postal) | Lookup postal addresses (such as PO Boxes). |
| [postcode](#postcode) | Lookup postcodes. |
| [street](#street) | Lookup streets. |
| [streetNumber](#streetnumber) | Lookup street numbers. |
| [subdwelling](#subdwelling) | Lookup subdwellings. |
| [subdwellingAddress](#subdwellingaddress) | List all subdwellings under a given address. |
| [suburb (NZ only)](#suburb) | Lookup suburbs. |
| [townCity (NZ only)](#towncity) | Lookup towns/cities in New Zealand. |
| [auNzReverseGeocode](#aunzreversegeocode) | Lookup addresses within a certain distance using geocode input - for Australia and New Zealand. |
| [transaction](#transaction) | Indicate that an address lookup transaction has been completed. |
### address
Lookup addresses using a single-line input address. If want to further filter the result by the locality level information, you can also specify the locality, postcode or state value
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/address
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/address
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `fullAddress` attribute is required
```
{
"payload": [ { "fullAddress": "202 220 GEORGE ST" } ],
"sourceOfTruth": "AUPAF"
}
If want to return addresses in NSW.
{
"payload": [ { "fullAddress": "202 220 GEORGE ST", "state": "nsw" } ],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `fullAddress` attribute is required
* The `sourceOfTruth` attribute is required
* The `locality` attribute is optional
* The `postcode` attribute is optional
* The `state` attribute is optional
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
"country": null,
"exception": null,
"postcode": "2000",
"street2": null,
"street": "GEORGE ST",
"streetName": "GEORGE",
"streetSuffix": "",
"streetType": "ST",
"streetNumber": "220",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "L 2 SE 202",
"flatUnitNumber": "202",
"flatUnitType": "SE",
"floorLevelNumber": "2",
"floorLevelType": "L",
"lotNumber": "",
"eid": "DWhlfKqXLLSTYjra7PXq+VYtLDV4rJM6",
"state": "NSW",
"locality": "SYDNEY"
}
]
}
```
### buildingName
Performs a search for building names using the supplied `buildingName`.
Additional information supplied in the request will further filter the results.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/buildingName
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/buildingName
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `buildingName` attribute is required
* The `postcode` attribute is optional
* The `locality` attribute is optional
* The `townCity` attribute is optional (New Zealand)
* The `suburb` attribute is optional (New Zealand)
* The `street` attribute is optional
* The `streetNumber` attribute is optional
* The `featureOptions` attribute is optional
```
{
"payload": [ { "buildingName": "anz" } ],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `buildingName` attribute is required
* The `sourceOfTruth` attribute is required
* The `postcode` attribute is optional
* The `locality` attribute is optional
* The `transactionID` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "",
"exception": null,
"country": null,
"postcode": "0870",
"street2": null,
"street": "SCHWARZ CRES",
"streetName": "SCHWARZ",
"streetSuffix": "",
"streetType": "CRES",
"streetNumber": "26",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "ANZAC HILL HIGH SCHOOL",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": "",
"state": "NT",
"locality": "ALICE SPRINGS"
},
...
]
}
```
### locality
Performs an Australian locality search using the supplied information.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/locality
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/locality
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `locality` attribute is required for non-semi locality search
* The `postcode` attribute is optional
* The `fullAddress` attribute is required for semi locality search
```
{
"payload": [ { "locality": "SYD" } ],
"sourceOfTruth": "AUPAF"
}
For Semi structure locality search:
{
"payload": [ { "fullAddress":"SYDNEY 2000"} ],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `locality` attribute is required for non-semi locality search
* The `postcode` attribute is optional
* The `fullAddress` attribute is required for semi locality search
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "SYDNEY NSW 2000",
"attributes": {},
"exception": null,
"country": null,
"postcode": "2000",
"street2": null,
"street": "",
"streetName": "",
"streetSuffix": "",
"streetType": "",
"streetNumber": "",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": "",
"state": "NSW",
"locality": "SYDNEY"
},
...
]
}
```
### postal
Performs a search for a postal address using the supplied information.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postal
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postal
```
#### Request (POST)
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object:
* The `postal` is required
* Either the `postcode` or `locality` attribute is required
```
{
"payload": [ { "postcode": "2000", "postal": "Locked Bag 1" } ],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `postal` is required
* Either the `postcode` or `locality` attribute is required
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "LOCKED BAG 1, MILLERS POINT NSW 2000",
"country": null,
"exception": null,
"postcode": "2000",
"street2": null,
"street": "",
"streetName": "",
"streetSuffix": "",
"streetType": "",
"streetNumber": "",
"postal": "LOCKED BAG 1",
"postalNumber": "1",
"postalType": "LOCKED BAG",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": "6So/3cBB43g9gZ5h97tjVlAP6KSxW63k",
"state": "NSW",
"locality": "MILLERS POINT"
},
...
]
}
```
### postcode
Performs a postcode search using the supplied information.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postcode
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postcode
```
#### Request (POST)
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object:
* The `postcode` attribute is required
```
{
"payload": [ { "postcode": "3000" } ],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `postcode` attribute is required
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "BARANGAROO NSW 2000",
"country": null,
"exception": null,
"postcode": "2000",
"street2": null,
"street": "",
"streetName": "",
"streetSuffix": "",
"streetType": "",
"streetNumber": "",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": "",
"state": "NSW",
"locality": "BARANGAROO"
},
...
]
}
```
### street
Performs a street search using the supplied information.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/street
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/street
```
#### Request (POST)
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object:
* The `street` attribute is required
* The `postcode` attribute is optional
* The `locality` attribute is optional
* The `townCity` attribute is optional (New Zealand)
* The `suburb` attribute is optional (New Zealand)
```
{
"payload": [ { "street": "GEORGE" } ],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `street` attribute is required
* The `postcode` attribute is optional
* The `locality` attribute is optional
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "GEORGE ST, HAYMARKET NSW 2000",
"attributes": {},
"country": null,
"exception": null,
"postcode": "2000",
"street2": null,
"street": "GEORGE ST",
"streetName": "GEORGE",
"streetSuffix": "",
"streetType": "ST",
"streetNumber": "",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": "",
"state": "NSW",
"locality": "HAYMARKET"
},
...
]
}
```
### streetNumber
Performs a street number search using the supplied information.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/streetNumber
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/streetNumber
```
#### Request (POST)
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object:
* The `streetNumber` attribute is required
* The `postcode` attribute is required
* The `locality` attribute is required
* The `townCity` attribute is optional (New Zealand)
* The `suburb` attribute is optional (New Zealand)
* The `street` attribute is required
```
{
"payload": [
{
"postcode": "2000",
"locality": "SYDNEY",
"street": "GEORGE",
"streetNumber": "220"
}
],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `streetNumber` attribute is required
* The `postcode` attribute is required
* The `locality` attribute is required
* The `street` attribute is required
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "",
"attributes": {
"Barcode": "1301011211020102222010332230110202013",
"Bsp": "015",
"DPID": "12345678"
},
"country": null,
"exception": null,
"postcode": "2000",
"street2": null,
"street": "GEORGE ST",
"streetName": "GEORGE",
"streetSuffix": "",
"streetType": "ST",
"streetNumber": "220",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": "6So/3cBB43g9gZ5h97tjVlAP6KSxW63k",
"id": "12345678",
"state": "NSW",
"locality": "SYDNEY"
}
]
}
```
### subdwelling
Performs a subdwelling search using the supplied information.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwelling
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwelling
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `subdwelling` attribute is required
* The `postcode` attribute is optional
* The `locality` attribute is optional
* The `townCity` attribute is optional (New Zealand)
* The `suburb` attribute is optional (New Zealand)
* The `street` attribute is optional
* The `streetNumber` attribute is optional
```
{
"payload": [
{
"postcode": "2000",
"locality": "SYDNEY",
"street": "GEORGE",
"streetNumber": "220",
"subdwelling": "202"
}
],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `subdwelling` attribute is required
* The `postcode` attribute is required
* The `locality` attribute is required
* The `street` attribute is required
* The `streetNumber` attribute is required
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload":[
{
"fullAddress": "L 2 SE 202 220 GEORGE ST, SYDNEY NSW 2000",
"attributes": {
"Barcode": "1301011211020102222010332230110202013",
"Bsp": "015",
"DPID": "12345678"
},
"country": null,
"exception": null,
"postcode": "2000",
"street2": null,
"street": "GEORGE ST",
"streetName": "GEORGE",
"streetSuffix": "",
"streetType": "ST",
"streetNumber": "220",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "L 2 SE 202",
"flatUnitNumber": "202",
"flatUnitType": "SE",
"floorLevelNumber": "2",
"floorLevelType": "L",
"lotNumber": "",
"eid": "tx99SZgKkuFvHO55bcst3we72s6/5vK4",
"id": "12345678",
"state": "NSW",
"locality": "SYDNEY"
}
]
}
```
### subdwellingAddress
List all subdwellings under a given address.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwellingAddress
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwellingAddress
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `id` attribute is required
```
{
"payload": [
{
"id":"59676232"
}
],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `id` attribute is required
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "L 1 20 BOND ST, SYDNEY NSW 2000",
"country": null,
"postcode": "2000",
"street2": null,
"street": "BOND ST",
"streetNumber": "20",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "L 1",
"eid": "09A409957EAD7B0EF1A8C52D39795736AF93F9D0AE5B2014",
"lotNumber": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "1",
"floorLevelType": "L",
"streetSuffix": "",
"streetType": "ST",
"streetName": "BOND",
"attributes": null,
"id": null,
"state": "NSW",
"locality": "SYDNEY"
},
{
"fullAddress": "L 2 20 BOND ST, SYDNEY NSW 2000",
"omitted": "The rest of the reponse is omitted for readable "
}
]
}
```
### suburb
Performs a New Zealand Suburb search using the supplied information.
*The suburb method is only valid when the 'NZPAF' or 'NZAD' sourceOfTruth parameter is supplied.*
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/suburb
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/suburb
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `suburb` attribute is required
* The `postcode` attribute is optional
* The `townCity` attribute is optional
```
{
"payload": [ { "suburb": "WELL" } ],
"sourceOfTruth": "NZPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `suburb` attribute is required
* The `postcode` attribute is optional
* The `townCity` attribute is optional
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"attributes": null,
"fullAddress": "WELLINGTON CENTRAL, WELLINGTON 6011",
"country": null,
"exception": null,
"id": null,
"rdNumber": null,
"postcode": "6011",
"street": "",
"streetName": "",
"streetSuffix": "",
"streetType": "",
"streetNumber": "",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": "",
"townCity": "WELLINGTON",
"suburb": "WELLINGTON CENTRAL"
}
]
}
```
### townCity
Performs a lookup for Towns and Cities in New Zealand using the supplied information.
*The townCity method is only valid when the 'NZPAF' or 'NZAD' sourceOfTruth parameter is supplied.*
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/townCity
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/townCity
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `townCity` attribute is required
* The `postcode` attribute is optional
```
{
"payload": [ { "townCity": "WELL" } ],
"sourceOfTruth": "NZPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
* The `townCity` attribute is required
* The `postcode` attribute is optional
* The `transactionID` attribute is optional
* The `featureOptions` attribute is optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"attributes": null,
"fullAddress": "WELLSFORD 0900",
"country": null,
"exception": null,
"id": null,
"rdNumber": null,
"postcode": "0900",
"street2": null,
"street": "",
"streetName": "",
"streetSuffix": "",
"streetType": "",
"streetNumber": "",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"lotNumber": "",
"eid": "",
"suburb": "",
"townCity": "WELLSFORD"
},
...
]
}
```
### AUNZreverseGeocode
Lookup addresses through the specified Source of Truth within a certain distance using the geocode input.
For multiple geocode inputs, only the **first** record will be processed. The supported Source of Truths are 'GNAF', 'NZPAF', 'NZAD' and 'CNAR' (default is GNAF for Australia and NZPAF for New Zealand).
#### Resource URL
```
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/reverseGeocode
```
#### Request
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `attributes` with `latitude` and `longitude` is required
* The `sourceOfTruth` is optional. The supported Source of Truths are GNAF, NZPAF, NZAD, CNAR (default is GNAF for Australia and NZPAF for New Zealand).
* The `featureOptions` is optional. The supported feature options are displayGnafLot, singleLineHitNumber (default 20), caseType, exposeAttributes, radius (default 50 for 50 meters radius).
```
{
"payload": [{"attributes": {"latitude":"-33.xxxxx", "longitude":"150.xxxxx"}}],
"sourceOfTruth": "GNAF",
"featureOptions": {"radius":"100"}
}
```
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "LOT 1 13 MEROO STREET, BLACKTOWN NSW 2148",
"country": null,
"postcode": "2148",
"street2": null,
"street": "MEROO STREET",
"streetNumber": "13",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "LOT 1",
"eid": "209593C380BE0D2AD545B41361CFB7B00DE4251D77BA4C78C8A0918B2624A10E",
"lotNumber": "1",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "STREET",
"streetName": "MEROO",
"attributes": null,
"id": null,
"state": "NSW",
"locality": "BLACKTOWN"
},
...
]
}
```
### transaction
Indicates that an address lookup transaction has been completed.
*The transaction method must be called when address has been found using the lookup process*. It is used for audit and billing purposes.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/transaction
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/transaction
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
```
{
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `sourceOfTruth` attribute is required
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": null
}
```
# Address Cleanse v1
Cleanse methods validate the single line input address based on the required source of truth.
## Cleanse methods (AU/NZ)
Cleanse methods validate the single line input address based on the required source of truth.
Cleanse the supplied single-line address into its component parts based on the supplied SOT.
### address
The cleanse method takes a concatenated address String in the fullAddress field of an AddressAu or AddressNz parameter. It then attempts to validate it based on the supplied sourceOfTruth into component parts which are then returned in a populated AddressAu or AddressNz object with additional attributes. We support AUPAF, GNAF and NZPAF in this version, and we are continuing the development to support more validations.
POST method it can allow to send a list of Addresses (maximum 100 per request) and then return a list of validated addresses.
Details of the processes for each available sourceOfTruth:
* sourceOfTruth : GNAF (GNAFAddressStandardization + GNAFValidation)
* sourceOfTruth : AUPAF (AMASAddressStandardization + AMASHAVE)
* sourceOfTruth : NZPAF (NZAddressStandardiztion + NZPostcodeAllocation + NZHAVEGeoPAF)
#### Resource URL
```
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/cleanse/address?sourceOfTruth=GNAF&fullAddress=220 GEORGE ST, SYDNEY
```
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/cleanse/address
```
#### Request
The request body is an [AddressRestRequest](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest) object:
{% hint style="info" %}
{% endhint %}
```
{
"payload": [
{ "fullAddress": "SE 202, 220 George Street, Syndey 2000" },
{ "fullAddress": "3 Orara Street, waitara nsw" },
....
],
"sourceOfTruth": "AUPAF"
}
```
#### Response
{% hint style="success" %}
See [Address Field Mapping Gui](/loqate-harmony-api/guides/best-practices/address-field-mappings)[de](/loqate-harmony-api/guides/best-practices/address-field-mappings) for integration best practices.
{% endhint %}
The response body is an [AddressRestResponse ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse)object:
```
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "220 GEORGE STREET,SYDNEY NSW 2000",
"country": "",
"postcode": "2000",
"street2": "",
"street": "George Street",
"streetNumber": "220",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "SE 202",
"eid": null,
"lotNumber": null,
"flatUnitNumber": "202",
"flatUnitType": "SE",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "Street",
"streetName": "George",
"careOf": "",
"exception": null,
"locality": "SYDNEY",
"state": "NSW",
"attributes": {
"GNAFPIDPosition": "ROOFTOP",
"GNAFConfidence": "0",
"ParcelID": "1//DP75111",
"MeshblockId": "10743811000",
"Latitude": "-33.86307089",
"Longitude": "151.20781474",
"GNAFReliability": "2",
"GNAFPID": "GANSW710276621",
"GNAFPointPID": "GANSW710276621",
"GNAFGroupPID": "NSW2845405",
"GNAFLocalityPID": "NSW3749",
"GeocodeLevel": "7"
}
},
{
"fullAddress": "3-11 ORARA STREET,WAITARA NSW 2077",
"country": "",
"postcode": "2077",
"street2": "",
"street": "Orara Street",
"streetNumber": "3-11",
"postal": "",
"postalNumber": "",
"postalType": "",
"buildingName": "",
"subdwelling": "",
"eid": null,
"lotNumber": null,
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "Street",
"streetName": "Orara",
"careOf": "",
"exception": null,
"locality": "waitara",
"state": "nsw",
"attributes": {
"GNAFPIDPosition": "ROOFTOP",
"GNAFConfidence": "1",
"ParcelID": "110//SP75046",
"GNAFPointPID": "GANSW716818114",
"MeshblockId": "11205293800",
"Latitude": "-33.70872612",
"GNAFPID": "GANSW716818114",
"Longitude": "151.10400679",
"GNAFReliability": "2",
"GNAFLocalityPID": "NSW4122",
"GNAFGroupPID": "NSW2895995",
"GeocodeLevel": "7"
}
},
.......
]
}
```
# Address International
{% hint style="danger" %}
These methods have been deprecated.
We recommend you upgrade your service to the latest [Address Validation method](/loqate-harmony-api/api-specification/address/address-validation-and-lookup). Upgrade at no cost and improved performance.
{% endhint %}
## International address lookup methods
International address lookup methods take complete or partial address information as an input and perform a search against a given country **other than Australia or New Zealand,** returning address information that matches the search parameters.
| [find](#address) | Lookup international addresses using a single-line input address. |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| [retrieve](#buildingname) | Retrieve international address details using the result from international address lookup. |
### find
Lookup international addresses from a given country other than Australia/New Zealand using a single-line input address.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/intl/address/find
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/intl/address/find
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `fullAddress` attribute is required
* The `country` attribute is required, its value should be an [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
```json
{
"payload": [ { "fullAddress": "10 Downing Street", "country": "GB" } ]
}
```
#### Request Parameters (GET)
* The `fullAddress` parameter is required
* The `country`parameter is required, its value should be an [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "10 Downing Street SomeCity, B63 3TA",
"country": null,
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": null,
"id": "GB|RM|A|123456",
"district": null,
"city": null,
"province": null
}
]
}
```
### retrieve
Retrieve international address details using the address `id` returned from the international address lookup.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/intl/address/retrieve
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/intl/address/retrieve
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `id`attribute is required
```json
{
"payload": [ { "id": "GB|RM|A|123456" } ]
}
```
#### Request Parameters (GET)
* The `id`parameter is required
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "Prime Minister & First Lord of the Treasury, 10 Downing Street, LONDON, SW1A 2AA, UNITED KINGDOM",
"country": "United Kingdom",
"postcode": "SW1A 2AA",
"street2": "",
"street": "Downing Street",
"streetNumber": "10",
"postal": "",
"postalType": "",
"postalNumber": null,
"buildingName": "",
"subdwelling": "",
"attributes": {
...
},
"id": "GB|RM|A|12345678",
"district": "",
"city": "London",
"province": ""
}
]
}
```
# Address Combined
{% hint style="danger" %}
These methods have been deprecated.
We recommend you upgrade your service to the latest [Address Validation method](/loqate-harmony-api/api-specification/address/address-validation-and-lookup). Upgrade at no cost and improved performance.
{% endhint %}
## Combined International address lookup methods
Combined International address lookup methods take complete or partial address information as an input and perform a search against a given country **including Australia and New Zealand**, returning address information that matches the search parameters.
| [lookup](#address) | Lookup international addresses using a single-line input address. |
| ------------------------- | ------------------------------------------------------------------------------------------ |
| [retrieve](#buildingname) | Retrieve international address details using the result from international address lookup. |
### lookup
Lookup international addresses from a given country including Australia/New Zealand using a single-line input address
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/address/lookup
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/address/lookup
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `fullAddress` attribute is required
* The `country` attribute is required, its value should be an [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
* The `sourceOfTruth` attribute is Optional
```json
{
"payload": [ { "fullAddress": "10 Downing Street", "country": "GB" } ]
}
```
For ANZ
```json
{
"payload": [ { "fullAddress": "20 bond Street", "country": "AU" } ],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `fullAddress`parameter is required
* The `country`parameter is required, its value should be an [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
* The `sourceOfTruth` parameter is Optional
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "10 Downing Street SomeCity, B63 3TA",
"country": null,
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": null,
"id": "GB|RM|A|123456",
"district": null,
"city": null,
"province": null
}
]
}
```
For ANZ
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "220 GEORGE ST, SomeCity NSW 2150",
"country": null,
"postcode": "2150",
"street2": null,
"street": "GEORGE ST",
"streetNumber": "220",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "",
"eid": "982407C8CC957CD0BE3984B913436F51508889391D6493DE",
"lotNumber": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "ST",
"streetName": "GEORGE",
"attributes": null,
"id": "40591980",
"exception": null,
"state": "NSW",
"locality": "SomeCity"
}
]
}
```
### retrieve
Retrieve international address details using the address `id` returned from the international address lookup.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/address/retrieve
```
#### Or if using GET
```
GET https://hosted.mastersoftgroup.com/harmony/rest/address/retrieve
```
#### Request (POST)
The request body is an [AddressRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects#addressrestrequest)object:
* The `id`attribute is required
* The `country`attribute is required, its value should be an [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
* The `sourceOfTruth` attribute is Optional
```json
{
"payload": [ { "id": "GB|RM|A|123456", "country": "GB" } ]
}
```
For ANZ
```json
{
"payload": [ { "id": "40591980", "country": "AU" } ],
"sourceOfTruth": "AUPAF"
}
```
#### Request Parameters (GET)
* The `id`parameter is required
* The `sourceOfTruth` parameter is Optional
* The `country`parameter is required, its value should be an [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2).
#### Response
The response body is an [AddressRestResponse](/loqate-harmony-api/api-specification/objects/address-objects#addressrestresponse) object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "Prime Minister & First Lord of the Treasury, 10 Downing Street, LONDON, SW1A 2AA, UNITED KINGDOM",
"country": "United Kingdom",
"postcode": "SW1A 2AA",
"street2": "",
"street": "Downing Street",
"streetNumber": "10",
"postal": "",
"postalType": "",
"postalNumber": null,
"buildingName": "",
"subdwelling": "",
"attributes": {
...
},
"id": "GB|RM|A|12345678",
"district": "",
"city": "London",
"province": ""
}
]
}
```
For ANZ
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"fullAddress": "220 GEORGE ST, PARRAMATTA NSW 2150",
"country": null,
"postcode": "2150",
"street2": null,
"street": "GEORGE ST",
"streetNumber": "220",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "",
"eid": null,
"lotNumber": "",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "ST",
"streetName": "GEORGE",
"attributes": {
"Barcode": "1301011100123001302200331112310103013",
"DPID": "40591980",
"PAFPosition": "ROOFTOP"
},
"id": "40591980",
"exception": null,
"state": "NSW",
"locality": "PARRAMATTA"
}
]
}
```
# Address Types
{% hint style="danger" %}
These methods have been deprecated.
We recommend you upgrade your service to the latest [Address Validation method](/loqate-harmony-api/api-specification/address/address-validation-and-lookup). Upgrade at no cost and improved performance.
{% endhint %}
## Address type methods (AU/NZ)
Address type methods provide address type information from a specific Source of Truth.
| [floorLevel](#address) | Retrieves the floor level types. |
| ----------------------- | ---------------------------------- |
| [postal](#buildingname) | Retrieves the postal types. |
| [street](#locality) | Retrieves the street types. |
| [streetSuffix](#postal) | Retrieves the street suffix types. |
| [unitFlat](#postcode) | Retrieves the unit/flat types. |
### floorLevel
Retrieves the list of Floor Level types available in the Source of Truth. No additional input is required.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/type/floorLevel
```
#### Request (POST)
The request body is a [MetadataRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects-1#addressnz)object:
* The sourceOfTruth attribute is required
```json
{
"sourceOfTruth": "AUPAF"
}
```
#### Response
The response body is an [MetadataRestResponse ](/loqate-harmony-api/api-specification/objects/address-objects-1#validatedaddressau)object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "B",
"value": "B"
},
{
"name": "BASEMENT",
"value": "B"
},
{
"name": "FL",
"value": "FL"
},
...
]
}
```
### postal
Retrieves the list of Postal types available in the Source of Truth. No additional input is required.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/type/postal
```
#### Request (POST)
The request body is a [MetadataRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects-1#addressnz)object:
* The sourceOfTruth attribute is required
```json
{
"sourceOfTruth": "AUPAF"
}
```
#### Response
The response body is a [MetadataRestResponse](/loqate-harmony-api/api-specification/objects/address-objects-1#validatedaddressau) object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "C POST OFFICE",
"value": "CARE PO"
},
{
"name": "C/ P O BOX",
"value": "PO BOX"
},
{
"name": "C/ PO BOX",
"value": "PO BOX"
},
...
]
}
```
### street
Retrieves the list of Street types available in the Source of Truth. No additional input is required.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/type/street
```
#### Request (POST)
The request body is a [MetadataRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects-1#addressnz)object:
* The sourceOfTruth attribute is required
```json
{
"sourceOfTruth": "AUPAF"
}
```
#### Response
The response body is a [MetadataRestResponse](/loqate-harmony-api/api-specification/objects/address-objects-1#validatedaddressau) object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "ACCESS",
"value": "ACCS"
},
{
"name": "ACCS",
"value": "ACCS"
},
{
"name": "ALLEY",
"value": "ALLY"
},
...
]
}
```
### streetSuffix
Retrieves the list of Street Suffix types available in the Source of Truth. No additional input is required.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/type/streetSuffix
```
#### Request (POST)
The request body is a [MetadataRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects-1#addressnz)object:
* The sourceOfTruth attribute is required
```json
{
"sourceOfTruth": "AUPAF"
}
```
#### Response
The response body is a [MetadataRestResponse](/loqate-harmony-api/api-specification/objects/address-objects-1#validatedaddressau) object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "CENTRAL",
"value": "CN"
},
{
"name": "CN",
"value": "CN"
},
{
"name": "E",
"value": "E"
},
...
]
}
```
### unitFlat
Retrieves the list of Unit/Flat types available in the Source of Truth. No additional input is required.
#### Resource URL
```
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/type/unitFlat
```
#### Request (POST)
The request body is a [MetadataRestRequest ](/loqate-harmony-api/api-specification/objects/address-objects-1#addressnz)object:
* The sourceOfTruth attribute is required
```json
{
"sourceOfTruth": "AUPAF"
}
```
#### Response
The response body is a [MetadataRestResponse](/loqate-harmony-api/api-specification/objects/address-objects-1#validatedaddressau) object:
```json
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"name": "AMENT",
"value": "APT"
},
{
"name": "AMT",
"value": "APT"
},
{
"name": "AP",
"value": "APT"
},
...
]
}
```
# Guides
Some topics require more guidance and understanding. Here we explain the detail on tuning your implementation for your use cases.
{% content-ref url="/pages/2w1YDD2OcrpmKrvO4dmy" %}
[Best Practices](/loqate-harmony-api/guides/best-practices)
{% endcontent-ref %}
{% content-ref url="/pages/3BFzdw2QwxFOAtLO9RBf" %}
[Address Field Mappings](/loqate-harmony-api/guides/best-practices/address-field-mappings)
{% endcontent-ref %}
{% content-ref url="/pages/D3hs6AdUUCKu8Z3DyBx3" %}
[Finding an Address](/loqate-harmony-api/guides/best-practices/finding-an-address)
{% endcontent-ref %}
{% content-ref url="/pages/sEPcQv5o48ddoAi3r9Gx" %}
[User Derived Address](/loqate-harmony-api/guides/user-derived-address)
{% endcontent-ref %}
{% content-ref url="/pages/omjXAPUs3ydGqPaBSWDA" %}
[Migrating to Address V2](/loqate-harmony-api/guides/migrating-to-address-v2)
{% endcontent-ref %}
# Best Practices
# Address Field Mappings
Our recommended commonly used field mappings.
### Universal Response Objects / Persistent Data Hierarchy
We have three different types of objects suited to primary business regions being Australia, New Zealand and International (rest of world).
We've created universal response components to enable consistent information no matter which address object best suits your business need.
When integrating to a platform we recommend using the universal response objects for mapping for consistency and scale across regions.
### Recommended field mappings
This fields remain constant across AU, NZ and INTL address response packages. We recommend using this mapping to reduce integration effort.
We have very detailed response allowing you to full customise how you want to compile any address component.
Generic Field
Recommended mapping
Description
Building names
buildingName
Building Name component of the address (e.g. 'ANZAC HOUSE').
Subdwelling (long)
subdwelling
Compiled subdwelling components of the address 'UNIT 2'. This includes subdwelling, floor, block and lot information.
Street number
streetNumber
Street Number component of the address '45A'
Street name
street
Compiled Street Name and Street Type. 'HIGH STREET'
City/Locality/Suburb
attributes.City
A smaller region contained in a Province. Australia known as Locality, in NZ is Suburb, around the world it can be City.
Zip/Postcode
postcode
Postcode or ZIP code of address
Region/State/Province (Short)
attributes.ProvinceCode
This is the highest region contained within a country. 'VIC'
Region/State/Province (Long)
attributes.ProvinceName
This is the highest region contained within a country. 'Victoria'
Country2 (Short)
attributes.CountryIso2
Country in ISO2 format. 'AU'
Country3 (Short)
attributes.CountryIso3
Country in ISO3 format. 'AUS'
Country (Long)
country
Country in full text. 'Australia'
Latitude
attributes.Latitude
Geocode of latitude "-34.77910653"
Longitude
attributes.Longitude
Geocode of longitude "139.55428910"
### Components for labels or integration
Every supplier has a preferred configuration. We give you the tools to compile as you need to fit your use case.
#### **Example 1: Australia Post Standard Address**
AUPAF barcode: {attributes.Barcode}
Address Line 1: {buildingName} {subdwelling} {userInferred}
Address Line 2: {streetNumber} {street} {streetSuffix} {postal}
Address Line 3: {attributes.City} {attributes.ProvinceCode} {postcode} {attributes.CountryIso3}
#### **Example 2: New Zealand Standard Address**
NZPAF barcode: {attributes.DPID}
Address Line 1: {buildingName} {subdwelling} {userInferred}
Address Line 2: {streetNumber} {street} {streetSuffix} {postal} ,{suburb}
Address Line 3: {attributes.City} {attributes.ProvinceCode} {postcode} {attributes.CountryIso3}
#### **Example 3: American Standard (INTL)**
Address Line 1: {streetNumber} {street} {streetSuffix} {district} {postal}
Address Line 2: {buildingName} {subdwelling} {userInferred}
Address Line 3: {attributes.City} {attributes.ProvinceCode} {postcode} {attributes.CountryIso2}
#### Example 4: Two lines with regions American
Address Line 1: {streetNumber} {street} {streetSuffix} {postal} ,{suburb/district}
Address Line 2: {buildingName} {subdwelling} {userInferred}
City: {attributes.City}
Zip: {postcode}
Province code: {attributes.ProvinceCode}
Country code: {attributes.CountryIso2}
# Finding an Address
This guide details the best methods for finding an Address using GBG Loqate Australia & New Zealand services
## Address Find
**Related Service**
{% content-ref url="/pages/5ylNPVUFqxzdVXGnD8kk" %}
[Address Validation & Lookup](/loqate-harmony-api/api-specification/address/address-validation-and-lookup)
{% endcontent-ref %}
### Quick Tips
All tips are generalisations on how to get the best performance overtime. Every country has a different way to input an address, which means end users enter addresses in many different ways and structures.
These tips are designed to be consistently fast and accurate, they may not be the outright fastest but they consistently work.
**Always helps:**
* Key fields: StreetNumber, StreetName, Postcode - '20 HIGH 2334’
* **Any Order with numbers first**, starting with postcode '2334 20 HIGH' yields similar results as '20 example 2121’. **Why?** Typing numbers is faster. For phone operators easier to understand and limits incorrect spelling.
* Find 'premise' first then extend to a sub-dwelling.
* Wildcards '*': unsure about something use a wildcard. - ' 20 HI* 2334 ' or ' UNIT 21 44 BRI\* 2000'
**What can impede:**
* Unit & unit numbers. Units will appear as options if you search Street method. Specifing Unit does narrow the search, however, being too narrow can be disadvantage if the Unit is not within the data for example commercial sublets may not have Unit sub-dwelling.
* Trying to spell Suburbs you don't know 'sombre' when 'sunbury'. Misspellings are common offers limited optimisation. Use postcode instead.
**Adds time with little benefit:**
* Typing the Street types e.g. 'Street, Road, Close'.
* Typing Suburbs - Simply a postcode is more useful. It is highly unusual to 2 identical addresses expect suburb within a postcode.
### Understanding an Address
Addresses comprise many components and interpretations around the world. Below diagram helps give a visual representation of an address.
### Use Wildcards '\*'
A wildcard replaces 'known' input with 'unknown' input. Entering a wildcard is the star (in blue) '\*'
* Wildcards can be used on any component of an address.
* You can use multiple wildcards in a search - one per component.
* Wildcards can be used in the start, end or middle of a component. '\*AL' or 'MAL\*' or 'M\*LEE'
### Method: Numbers First
**Target Address:** ‘4 MALLEE COURT, SUNBURY VIC 3429’
**Method:** {postcode} {streetNumber} {streetName}.
Numbers are easier to hear and faster to type.
Input examples:
* '3429 4 MALLEE’
* '3429 4 MAL\* SUN\*' Unsure of multiple spellings – use wildcard
* '34\* 4 MALLEE' - missed a number? - use wildcard
* '3429 4 M\*LEE' - unsure of street spelling – use wildcard
### Method: Letters Premise then sub-dwellings
**Target Address:** ‘UNIT 5 25 NEPEAN HIGHWAY, ASPENDALE VIC 3195’
**Method:** {streetNumber} {streetName} {postcode} {subdwelling}.
We don't recommend adding subdwelling component until after premise component. Its more efficient to find the premise then extend to the subdwelling.
NB: Not all sub-dwellings are in our trusted data sources. This is industry wide problem.
Input examples:
* '25 NEPEAN 3195’ - gives all matching 25 Nepean. Sometimes Units will not be in the data and only premise match is possible.
* '25 NEPEAN 3195 5' - Extend with UnitNumber. All subdwelling types (unit, flat) with 5.
* '25 NEPEAN 3195 Unit' - Extend with Unit all matching units within 25 Nepean
* '\* NEPEAN 3195 Unit 5' - all matching 'unit 5' on Nepean StreetName
* '25 NEP\* 3195 Unit' - unsure of street spelling – use wildcard
# User Derived Address
Using user input to infer subdwelling address component exists to assist the user journey with validation address information.
## What is a user derived addresss?
User derived address is a featureOption called 'userInferred' of Address Find functionality that is very powerful in using user input to infer an address sub-premise. We link any inference to a valid address and provide this information to you to decide how best to use it (see [How do I know userInferred has been used?](#how-do-i-know-userinferred-has-been-used)).
Any inference is a known subdwelling component in that our technology and lexical knowledge base recognises the sub-dwelling component and handles it appropriately.
### How user derived address changes behaviour
User derived address alters the address options the end user selects because of the end users input to recognise sub-premise. This is very usefull
**Without User derived**
The unit information is not used because within the data no unit exists at this address. However, the end user is requesting a unit.
**With User derived**
The unit information is now available for the end user to select as they have searched for it. Importantly, the premise level is what the validated address is linked with.
### How to Implement **User derived address**
Add in call featureOptions "userInferred": "1". This is the only change you need to make. Address Retrieve works normally based upon the "id" supplied in Address Find.
```json
{
"payload": [ { "country": "au", "fullAddress": "suite 4 20 bond st, nsw" } ],
"sourceOfTruth": "AUPAF",
"featureOptions": { "userInferred": "1", "singleLineHitNumber": "5" }
}
```
## How do I know user derived address has been used?
When a User Inferred sub-premise has been selected in Address Find by the customer this confirms the inference eg That the end customer wants to use this address.
The Address id contains the UserInferred detail eg "AU|AUPAF|68930608|UNIT 2".
When calling Retrieve include this full ID containing the User inferred information.
Within the response data ***payload.attributes.UserInferred*** has the value of the userInferred input.
Population of this field
## Which sub-premise types does it work for?
For AU & NZ all of them.
For information of a sub-premise be inferred this information must match Loqates Lexical knowledge base. This contains wide range of lexicals such as units, shop, level, floor, suite and various shorthand abbreviations for subdwellings.
If you find one that doesn't work let us know and we will update our knowledge base.
[^1]:
# Expanded sub-premise reach
Expand your reach be enabling sub-premise reach feature to increases successful address finds to sub-premises not within our authoritative data.
## What is Expanded sub-premise reach?
Increases your successful address searches for ungazetted sub-premises. These are commonly newly created developments, commercial addresses, retirement homes, land lease, shopping centers. These addresses are present in our authoritative data at a building or premise level, however, often the customer will request an address at their known sub-premise. This feature solves that issue by solving the last metres for successful delivery.
Our technology recognises the sub-premise has been requested for valid address and handles it appropriately.
### How user derived address changes responses
Loqate AU NZ expanded sub-premise alters the address options the end user selects because of the end users input to recognise sub-premise.
**Without expanded sub-premise**
The unit information is not used because within the data no unit exists at this address. However, the end user is requesting a unit. If the customer selects the premise the end deliver can fail as the delivery driver does not know which sub-premise the deliver is for.
**With expanded sub-premise**
The unit information is now available for the end user to select as they have searched for it. Importantly, the premise level is what the validated address is linked with. The delivery driver has clear instruction to make the delivery.
### How to Implement **Expanded sub-premise**
Add in call featureOptions "userInferred": "1". This is the only change you need to make. Address Retrieve works normally based upon the "id" supplied in Address Find.
```json
{
"payload": [ { "country": "au", "fullAddress": "suite 4 20 bond st, nsw" } ],
"sourceOfTruth": "AUPAF",
"featureOptions": { "userInferred": "1", "singleLineHitNumber": "5" }
}
```
## How do I know **expanded sub-premise** has been used?
When a expanded sub-premise has been selected in Address Find by the customer this confirms the inference eg That the end customer wants to use this address.
The Address id contains the UserInferred detail eg "AU|AUPAF|68930608|UNIT 2".
When calling Retrieve include this full ID containing the User inferred information.
Within the response data ***payload.attributes.UserInferred*** has the value of the userInferred input.
Population of this field
## Which sub-premise types does it work for?
For AU & NZ all of them.
Our technology recognises the sub-premise patterns for valid address and handles it appropriately seamlessly in our api response.
[^1]:
# Parcel Locker Plus
Deliver your products to over 4,700 collections point including Australia Posts Parcel Locker, Post Office and retail partner network.
In the 2020/2021 period, over 46 million parcels were sent to collection points, offering parcel collect options that provide the delivery choices your customers expect.
### Successful delivery is paramount:
**49%** of customers surveyed by AustPost emphasized the importance of access to additional collection points.^[^1].
**73%** of consumers prefer knowing their parcel collection options before making a purchase.\*[^2]
**68%** of businesses highlight failed or late deliveries as a significant operational cost\*\*[^3]​
### Parcel Locker Plus - Collection Points
Parcel Locker Plus is updated monthly, encompassing the expanding collection point network. Collection points include:
* Parcel Lockers
* Licensed Post office
* Post Offices
* Post Office Agency
* Community Postal Agent
* Retail Annexa
* PostShop
* Delivery Annex
* Business Center
### Parcel Locker Plus - Sending Points
Parcel Locker Plus comprises locations where mail or packages can be sent, including roadside options such as red roadside mailboxes and Express Post mailboxes.
Sending points include:
* Red roadside mailboxes
* Express Post mailboxes
### How to access Parcel Locker Plus
Parcel locker plus is available in [Address Lookup & Validation](/loqate-harmony-api/api-specification/address/address-validation-and-lookup) by setting either "sourceOfTruth" or "moreSources" to "AUPOST". Results are prioritised by the dataset listed in "sourceOfTruth".
If you only want to search with Parcel Locker Plus then only set "sourceOfTruth":"AUPOST" without anything within "moreSources"
### Filtering Parcel Locker Plus using addressTypeFilter
You are able to filter Parcel Locker Plus by using "addressTypeFilter" employing either inclusion or exclusion methods.
Inclusion method is whereby you state what you want searched in the array "addressTypeFilter":"UPL" will only search within Parcel Lockers.
Inclusion method involves specifying what you want searched in the array (eg. "addressTypeFilter":"UPL" will search only within Parcel Lockers)
Exclusion method, indicated by adding a "-", entails specifying what you want excluded (eg. "addressTypeFilter":"-UPL" will search everything except Parcel Lockers).
#### Common Use Cases:
**Collection Only:** You need to set the "addressTypeFilter": "-rspb, -cspb". This searches everything except the sending use cases.
**Sending Only:** You need to set the "addressTypeFilter": "rspb, cspb". This searches only the sending use cases.
| Asset Type​ Code | Description |
| ---------------- | ---------------------------- |
| UPL​ | PARCEL LOCKER​ |
| LPO​ | LICENSED POST OFFICE​ |
| PO​ | POST OFFICE​ |
| CPA​ | COMMUNITY POSTAL AGENT​ |
| RA​ | RETAIL ANNEXE​ |
| RP​ | POSTSHOP​ |
| POA​ | POST OFFICE AGENCY​ |
| PO​ | POST OFFICE​ |
| PDEP​ | DELIVERY ANNEX​ |
| BC​ | BUSINESS CENTRE​ |
| RSPB​ | RED STREET POSTING BOX​ |
| CSPB​ | COMBINED STREET POSTING BOX​ |
### Parcel Locker Plus request examples
Lookup Request: Address Lookup with Collection points only
```json
{
"payload": [ { "country": "AU", "fullAddress": "parcel 3000 " } ],
"sourceOfTruth": "AUSOTS",
"featureOptions": { "moreSources": "AUPOST","addressTypeFilter": "-rspb, -cspb"}
}
```
Lookup Request: Collection Only
This will show all options within "3000" search criteria eg mostly Melbourne postcode.
```json
{
"payload": [ { "country": "AU", "fullAddress": "3000" } ],
"sourceOfTruth": "AUPOST",
"featureOptions": { "addressTypeFilter": "-rspb, -cspb"}
}
```
Lookup Request: Sending Only
This use case you would be telling customers where they can send something from.
```json
{
"payload": [ { "country": "AU", "fullAddress": "3000" } ],
"sourceOfTruth": "AUPOST",
"featureOptions": { "addressTypeFilter": "rspb, cspb"}
}
```
[^1]: ^2021 APO Deliver experience report
[^2]: \*APO 2022 Inside Australian Online Shopping eCommerce Industry Report
[^3]: \*\* Loqate fixing failed deliveries research
# Migrating to Address V2
Step by step guide to migrating to Address V2.
## Introduction
This guide is written to assist upgrading to receive the benefits of using Address V2.
We have depreciated all api connections except Address V2. This is to enable us to better improve our services to you.
Address V2 separates concepts of:
Address Lookup (typeahead service ) and Address Validation (the validated data) into two defined endpoints.
1. Address Lookup - the typeahead service
1. API endpoint: [.../v2/address/find](https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/address/address-validation-and-lookup#find)
2. Address Validation - the validated data package of the address
1. API endpoint: [.../v2/address/retrieve](https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/address/address-validation-and-lookup#retrieve)
### Benefits of using Address V2
We have implemented many improvements into Address V2 that can assist in problems encountered and knowledge gained from previous versions of our address lookup product(s).
* No contractual changes. You've purchased address validation we continue to supply address validations through an improved service. We proto-rata transactions from V1 to V2 when putting migration in production.
* The service is faster reducing loads and tuning compute by separating find and retrieve api endpoints.
* Many issues with V1 have resolution features in V2 that is enables by changing your api requests. Within the migration we can address these to ensure you have the best solution for your changing business needs.
* V2/address/find enables us to better monitor performance of find and bring new features to find functionality to improve our goal of finding target addresses the fastest with the least keystrokes.
* V2/address/retrieve has the same response data package reducing effort to migrate.
* V2 Reduces billable transaction ambiguity. Using V2 understand what is a Find and what is a Retrieve (Transaction) is independently monitored.
* V1 is depreciated. We are reducing our effort in supporting this endpoint and investing that effort in improving V2. The less customers on V1 the faster we can bring improvements.
* Improves our information security protocols to keep you and us safer.
## Migration Timeline
We have depreciated all API connections prior to Address V2. We in the process of scheduling turn-off dates from 2025 depending on the service.
Implementing V2 usually fully completed within 2 weeks.
The response package is the same as V1 meaning much of the complex work is re-usable from your V1 implementation.
## Migration Checklist:
* [ ] 1\) Notify Loqate AU & NZ that you intent to migrate to V2. You will get access and support to migrate.
* [ ] 2\) Read & share with developers [Address V2 API documentation](https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/address/address-validation-and-lookup) within this documentation Loqate Harmony API > API Specification > Address > Address Validation and Lookup. In particular, the difference between Find and Retrieve api endpoints.
* [ ] 3\) Read & share with developers [client and/or server side libraries ](https://docs.mastersoftgroup.com/loqate-harmony-api/integrations/client-libraries)to assist in implementing V2. If you need a library please ask as we have more than we publicly publish.
* [ ] 4\) Book a pre-development meeting with our team and your team (if required) to answer any questions. Check the FAQ here we are updating it.
* [ ] 5\) Develop and Test Address V2 within your development team.
* [ ] 6\) Notify Loqate AU & NZ of intended switch date.
* [ ] 7\) Implement to production
## FAQ
Do I need to sign new contract?
No. Unless you have a very old contract or through migrating you need access to additional data.
What happens to my transaction limits?
Any transaction limit are pro-rata. We consider V2 another service to conduct address validations.
For example: You have purchased 240,000 transactions, you utilise 90,000 transactions with V1 you will have 150,000 left for V2.
Does it cost more?
No, usually once implemented it reduces your costs.
Has the Data changed?
Its the same and the response data is the same schema its migrating from Address V1 being .
Having the same schema greatly reduces the effort of migration as your existing processes should remain unchanged.
What are the best fields to use in integrations?
You want to use Universal Response objects when integrating. This is likely new since your last integation.
See Best Practice guide on [Address Field Mappings.](https://docs.mastersoftgroup.com/loqate-harmony-api/guides/best-practices/address-field-mappings)
# Sign up/ Login
How to sign up to Loqate Harmony API service.
Before you begin you will need a Loqate Harmony Account.
### Free Trial
You can register a free trial to get started. Moving onto a paid plan is the only way to use our products.
{% embed url="" %}
Once your account is created your can access your API keys through the Harmony Console.
See this guide to Get your API Keys and get started
{% content-ref url="/pages/VvdkGCL1SrmqLDqhO5il" %}
[Getting your API keys](/loqate-harmony-api/guides/console/getting-your-api-keys)
{% endcontent-ref %}
### Paid plans
From small plans to enterprise solutions, we have packages to suit businesses of all sizes.
These plans comprise a Transaction limit of which you use over time (usually 12 months). If you exceed your limit your usage will revert to our standard rate and your service will continue.
Before you exceed limits we will notify you, its best to contact to us to arrange a new plan before reverting to standard rates.
{% embed url="" %}
### Login
You can login or reset password from login
{% embed url="" %}
If you have forgotten your password you can reset it from the login page
# Support
### Support Desk
All our customer receive support via our support desk.
{% embed url="" %}
### Premium Support
Premium support is available at additional cost.
Our team of experts can assist in all matters of design, implementation and configuration of our services.
If you don't already have Premium Support lodge a support ticket requesting Premium Support.
{% embed url="" %}
### Custom development
Custom development is available at additional cost.
Our team of experts solution design and develop solutions for your needs as it relates to the products and services we offer.
Lodge a support ticket requesting custom development.
{% embed url="" %}
# Console
{% content-ref url="/pages/VvdkGCL1SrmqLDqhO5il" %}
[Getting your API keys](/loqate-harmony-api/guides/console/getting-your-api-keys)
{% endcontent-ref %}
{% content-ref url="/pages/6nblUVGuqyqgTkhlq5cH" %}
[Getting Started](/loqate-harmony-api/guides/console/getting-started)
{% endcontent-ref %}
{% content-ref url="/pages/YKL5DNtR9w3feVLoMWTO" %}
[Add a Service](/loqate-harmony-api/guides/console/add-a-service)
{% endcontent-ref %}
{% content-ref url="/pages/Z4Qia4tS0WLR5hkTrcVM" %}
[Dashboard](/loqate-harmony-api/guides/console/dashboard)
{% endcontent-ref %}
{% content-ref url="/pages/3gMrxwsXtxNpvxY3OWGo" %}
[Subscriptions](/loqate-harmony-api/guides/console/subscriptions)
{% endcontent-ref %}
{% content-ref url="/pages/SJolUF3ivGjDmjy8fgvm" %}
[Reports](/loqate-harmony-api/guides/console/reports)
{% endcontent-ref %}
{% content-ref url="/pages/DVXUWK0Xuf3s0VQ6rGrk" %}
[Invoices](/loqate-harmony-api/guides/console/invoices)
{% endcontent-ref %}
# Getting your API keys
To get your API Keys within Console. Its assumed you have signed up already.
1\. Navigating 'Subscriptions' and click on 'Name'
3\. Click on Users
4\. Create a new User to issue a new API key for a specific purpose or Click 'Detail' of a User to see API keys for that user.
5\. API keys are User Name and Credential
# Getting Started
The links are provided to either [Add a Service](/loqate-harmony-api/guides/console/add-a-service) or get further information.
Its likely you will need to contact us to enable additional services on your account.
Contact [support ](https://www.loqate.com/anz/support/)to have these services enabled.
# Add a Service
Its likely you will need to contact us to enable additional services on your account.
Contact [support ](https://www.loqate.com/anz/support/)to have these services enabled.
# Dashboard
Dashboard that enables the customer to get a graphical representation of their API call usage analytics both on a daily and monthly basis. We also show pie charts that depict customers active plans.
**Daily Request Count**
The customer can get the usage analytics for last 7,14,21,30 days or filter the usage by date range.
Data metrics can be retrieved for **All request types** or **specific requests** that customer is interested in for e.g. "lookupAddress","validateEmail" etc.
**Monthly Request Count**
The customer can get the usage analytics for last 3,6,9 or 12 months.
**Active Plans**
Pie charts to depict customers active plans, planned quota ,exceeded calls and estimated additional cost.
# Subscriptions
{% content-ref url="/pages/jibos4MTyAYHzzOwPJdN" %}
[Features](/loqate-harmony-api/guides/console/subscriptions/features)
{% endcontent-ref %}
{% content-ref url="/pages/O7rL6AhX1CBs4YoLSAgE" %}
[Users](/loqate-harmony-api/guides/console/subscriptions/users)
{% endcontent-ref %}
{% content-ref url="/pages/75yaJ2x7zW5ZcMv1ndBm" %}
[Subscribed Plans](/loqate-harmony-api/guides/console/subscriptions/subscribed-plans)
{% endcontent-ref %}
{% content-ref url="/pages/amdXgmcixzgwOZA1xoNM" %}
[Allowlisting domains](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains)
{% endcontent-ref %}
{% content-ref url="" %}
{% endcontent-ref %}
{% content-ref url="/pages/vfqZNJwXsjbilEGS7bVu" %}
[Blocklist - Email Validation](/loqate-harmony-api/guides/console/subscriptions/blocklist-email-validation)
{% endcontent-ref %}
# Features
Features are the particular functions available within the subscription.
**Check Usage** button will allow the user to check the usage at feature level.
# Users
Users are allowed to make calls to our RESTful web services. A user is identified by the `API Username` and the `domain`. The domain is required to match the host where the javascript code is used. If the web service call is made directly from backend program such as Java, PHP, .NET, the domain is not required to be specified.
Each user will require features to be assigned so that the user can have the access to those functions.
### **Create New User**
### **Features**
User is allowed to add or remove features of the API user by clicking Features link.
Assign Features button can be used to add or remove features.
**Add features**: Tick the checkbox and hit Assign button to add features.
**Remove features**: Untick the checkbox and hit Assign button to remove features.
### Detail
User is allowed to modify the API User credential by clicking Detail link.
Click Edit User button to modify the Credential.
Click on Get New Credential button and hit SUBMIT to modify API Credential.
User can also disable API user by ticking the Disable User check box.
# Subscribed Plans
Subscribed plans from customers Live Subscription depicts all the active plans.
These plans will auto renew annually or monthly based on the billing cycle of the plan.
Contact [support](https://www.loqate.com/anz/support/) to get these plans upgraded.
# Allowlisting domains
Users are allowed to allowlist the domains while creating API [Users](/loqate-harmony-api/guides/console/subscriptions/users).
User can allowlist different domains with the same API user and password.
Users are allowed to allowlist wildcard domains to support all subdomains of the parent domain. This can be done by specifying (\*) as the leftmost label of a parent domain name **e.g.** \*.example.com.
# Blocklist - Email Validation
User is allowed to add any emails that they want to blocklist.
The email validation service will mark such email addresses as block listed.
### Add Email
Add email address to the blocklist and hit SUBMIT.
### Disable Email
Disable the email added in blocklist using Disable link.
User can also delete the email from email blocklist using Delete link.
# Reports
**Usage Detail Report**
Customer can use this report to query the data that is limited up to 1 day. This report produces the instant usage information, usage can be checked as soon the user triggers calls.
**Usage Summary Report**
Customer can use this Summary report to query larger data range i.e. data range that's over a period of 24hrs.
This report shows a summary of the total number of requests run per feature.
# Invoices
User can view all the invoices that are paid and the ones that are due to be paid.
Payment Status AUTHORISED means its due to be paid.
##
# Paying Invoices
## Pay by Credit Card
Users can pay the invoice using Make Payment link.
Make Payment link will open up the Invoice pdf document which allows the user to process the payment using Click here to pay online link.
## Pay by Bank Account
User needs to use the details below from the invoice for payment by EFT.
# API Latency
Our service API Latency
Latency is very important to us and we constantly monitor performance of our API to ensure our world class products have high performance.
We consistency implement changes to maintain and improve latency performance of our services.
We measure our latency by our GBG On-Server Performance. See [Latency by Service](#latency-by-service).
When calling our API service, several factors can affect end user latency, which is the delay between making a request and receiving a response. Its important to understand these factors
## Latency Factors
1. **Network Latency:**
* Physical distance: The geographical distance between the client and the API server can significantly affect latency.
* Network congestion: High traffic and congestion on the network can introduce delays in data transmission.
* Network latency is outside of our control.
2. **GBG On-Server Performance:**
* Server load: The server's current load or the number of requests it's processing can affect response times.
* We manage this by great api design, auto scaling our servers during peak demand periods..
3. **Client-Side Factors:**
* Client hardware and software: The performance of the client device, as well as the efficiency of the client application, can influence latency.
* Client Server load: The server's current load or the number of requests it's processing can affect response times.
* Client security protocols.
* Client-side factors are outside of our control.
4. **Authentication and Security:**
* Encryption: We use TLS of encryption, can add processing time to both the client and server, affecting latency.
* This is essential for information security.
5. **Auto Scaling delay:**
* We auto scale services to demand levels to manage traffic and latency.
* In peak demand, it takes approximately 30 -120 seconds for the servers to scale up to meet maintain our target On-Server latency. During this short auto scaling period we see peak latency.
6. **Caching:**
* We have short term request caching on Server-side to reduce overall latency.
7. **Third-Party Dependencies:**
* Some API services relies on third-party services or external data sources, the latency of those services can impact the overall API response time.
8. **Datasets accessed:**
* Latency varies between the datasets by accessed.
* With AU & NZ datasets this is tiny 20ms. Larger impact is when accessing Non AU & NZ addresses.
## Latency by Service
### Address Lookup & Validation
We measure the Address Lookup service (Address Find) because this is user typeahead services. 2024 AU & NZ - Average On-Server Latency is 37ms. This significantly outperforms our benchmarking.
2024 INTL - Average On-Server Latency is 323ms. We continue to work on reducing latency of this service. It is not that noticeable within UX. By the time you stop typing get your mouse and look at screen the results are showing.
### Address Cleanse
2024 AU & NZ - Average On-Server Latency is 22ms. This significantly outperforms our benchmarking.
2024 INTL - Average On-Server Latency is 86ms. This outperforms our benchmarking.
### Address Parse
2024 - Average On-Server Latency is 3ms. This significantly outperforms our benchmarking.
### Reverse Geocoding (Address by Geocode)
2024 AU & NZ - Average On-Server Latency is 33ms. This significantly outperforms our benchmarking.
2024 INTL - Average On-Server Latency is 487ms. We continue to work on reducing latency of this service.
### Suburb Lookup
2024 AU & NZ - Average On-Server Latency is 23ms. This significantly outperforms our benchmarking.
### Business Lookup & Validation
2024 Average On-Server Latency is 56ms. This significantly outperforms our benchmarking.
### Email Validation
2024 Average On-Server Latency for is 516ms. This on the benchmark for this service.
We have implement a timeout feature on email validation. This service is heavy reliant (industry issue) on 3rd party services such network latency, email server latency and responses.
### Phone Validation
2024 Average On-Server Latency for is 692ms. This on the benchmark for this service.
This service is heavy reliant (industry issue) on 3rd party services such network latency and live phone connectivity tests.
### Matching
2024 Average On-Server Latency for is 133ms. This outperforms our benchmarking.
# Demos
### Prerequisites
Before you begin you will need a Loqate Harmony Account. You can register a free trial to get started.
{% embed url="" %}
### How to use our **demo's**
Each of demo you will need to include you Authentication to use.
We use Codepen so you can see how we have implemented our API's and supporting libraries.
To get the best experience - open the demo in Codepen by clicking 'Edit on Codepen' in the top right. Once in Codepen select the boxes and Full Page View
#### Settings
First enter you credentials and press start. This is the same for all demo's
**Option**
Each demo you can set of Options relating to service. These Options optimise the look, feel and performance of our API's. We set the default to what works for most of the time.
Changing Options enables you to tune the API performance for your use case.
#### Demo section
Each demo varies to display the performance of our API's. However, commonly we have input fields usually appearing first with instructions then the full response from our API service based on your filters.
**Input fields**
These provide you with the customer experience of using Loqate in a field. Commonly things that would take you several fields are solved in just a few keystrokes.
**Response**
The full response from our API. Often from the few keystrokes put into the input field our full response is full of data structured and ready for use.
**Mock User Interface**
Some demo's underneath the API response package have an example of how End Users (your customers) might see and use our products.
# How to use our demos
### Prerequisites
Before you begin you will need a Loqate Harmony Account. You can register a free trial to get started.
{% embed url="" %}
### Understanding the **demo** templates
Each of demo you will need to include you Authentication to use. We use Codepen so you can see how we have implemented our API's and supporting libraries.
#### Settings
First enter you credentials and press start. This is the same for all demo's
**Filters**
Each demo you can set common Options to optimise the look, feel and performance of our API's. We set the default to what works for most of the time. Changing the filters is about tuning the use case for your business.
#### Demo section
Each demo varies to display the performance of our API's. However, commonly we have input fields usually appearing first with instructions then the full response from our API service based on your filters.
**Input fields**
These provide you with the customer experience of using Loqate in a field. Commonly things that would take you several fields are solved in just a few keystrokes.
**Response**
The full response from our API. Often from the few keystrokes put into the input field our full response is full of data structured and ready for use.
### Go to Demo
{% content-ref url="/pages/HvyuR7TTNjla3K5XMkWb" %}
[Address Validation Demo](/loqate-harmony-api/demos/address-validation-demo)
{% endcontent-ref %}
{% content-ref url="/pages/Vg6qJfLLcMfajoujSxTS" %}
[Address by Geocode (Reverse Geocode) Demo](/loqate-harmony-api/demos/address-by-geocode-reverse-geocode-demo)
{% endcontent-ref %}
{% content-ref url="/pages/HVNXWJZwijWqdCG09GQZ" %}
[Address Cleanse Demo](/loqate-harmony-api/demos/address-cleanse-demo)
{% endcontent-ref %}
{% content-ref url="/pages/8DMdwogg6aOdZATAp5Sy" %}
[Address Parse Demo](/loqate-harmony-api/demos/address-parse-demo)
{% endcontent-ref %}
{% content-ref url="/pages/k8dR5NJsjr5vhxLTmtR2" %}
[Business Validation Demo](/loqate-harmony-api/demos/business-validation-demo)
{% endcontent-ref %}
{% content-ref url="/pages/cRdWEvExEInbaObtWXNc" %}
[Email Validation Demo](/loqate-harmony-api/demos/email-validation-demo)
{% endcontent-ref %}
{% content-ref url="/pages/IgCT1mGwXcOejmCETOTG" %}
[Phone Validation demo](/loqate-harmony-api/demos/phone-validation-demo)
{% endcontent-ref %}
# Address Validation Demo
### Prerequisites
Before you begin you will need a Loqate Harmony Account.
If you do not have Harmony API account you register a free trial.
{% embed url="" %}
### Address Lookup & Validation Demo
You can demo the service from within the Harmony API Console by signing up for a trial or navigating to API Demo.
Alternatively, using your API keys within domain access to cdpn.io. See our guide on [how to use our demo's](/loqate-harmony-api/demos#how-to-use-our-demos). Further guides are below the Codepen
### Demo Guide
Once you enter your credentials and click start. The demo will appear below.
Simply start typing an address into the input field. After 3 characters you will see suggestions, click on a suggestion and the full response package becomes available.
#### **Common Options to change**
In Setting the Options button gives you all the API options that you set for different uses for this API.
#### **Common Options**
In Setting the Options button gives you all the API options that you set for different uses for this API.
***Country:*** Set to the target country.
***Source of Truth:*** AU & NZ offer selections of datasets to access.
***Address grouping:*** valid for certain countries / data sources
***Hits:** Alters the amount of results our API returns on a Find request*
***State:** Filters results to a specific state or region in AU & NZ*
#### Any Order Feature
Any Order feature allows addresses to be entered in Any order and they will be found.
* Street Number, Street Name, Suburb
* Suburb, Street Number, Street Name
* Postcode, State, Street Name, Street Number
* Try Any Order you like - it still works.
**Accurate Data**
Try '99999 George Street Sydney'. This does not exist in real life. We return no result because its not real.
### Related API Specification
{% content-ref url="/pages/5ylNPVUFqxzdVXGnD8kk" %}
[Address Validation & Lookup](/loqate-harmony-api/api-specification/address/address-validation-and-lookup)
{% endcontent-ref %}
# Address by Geocode (Reverse Geocode) Demo
### Prerequisites
Before you begin you will need a Loqate Harmony Account.
If you do not have Harmony API account you register a free trial.
{% embed url="" %}
### Address by Geocode Demo
We recommend opening in Codepen (click top right 'Edit on Codepen') for the best experience.
See our guide on [how to use our demo's](/loqate-harmony-api/demos#how-to-use-our-demos). Further guides are below the Codepen.
### Demo Guide
Once you enter your credentials and click start. The demo will appear below.
Add Geopoints (lat,lon) and you will see suggestions by order of distance from input geopoint, click on a suggestion and the full response package.
#### **Common Options to change**
In Setting the Options button gives you all the API options that you set for different uses for this API.
**Common settings**
***Radius:*** Sets the radius to find addresses from a geopoint.
***Source of Truth:*** AU & NZ offer selections of datasets to access.
***Hits:** Alters the amount of results our API returns on a Find request*
***State:** Filters results to a specific state or region in AU & NZ*
### Related API Specification
{% content-ref url="/pages/NjSnzxkY97PKcUdk71DB" %}
[Address by Geocode](/loqate-harmony-api/api-specification/address/address-by-geocode)
{% endcontent-ref %}
# Address Cleanse Demo
### Prerequisites
Before you begin you will need a Loqate Harmony Account.
If you do not have Harmony API account you register a free trial.
{% embed url="" %}
### Address Cleanse Demo
We recommend opening in Codepen (click top right 'Edit on Codepen') for the best experience.
See our guide on [how to use our demo's](/loqate-harmony-api/demos#how-to-use-our-demos). Further guides are below the Codepen.
### Demo Guide
Once you enter your credentials and click start. The demo will appear below.
Enter full address string and click 'Cleanse'. The full response package of the match is within the response.
#### **Common Options to change**
In Setting the Options button gives you all the API options that you set for different uses for this API.
***Country:*** Set to the target country.
***Source of Truth:*** AU & NZ offer selections of datasets to access.
***Hits:** Alters the amount of results our API returns on a Find request*
***State:** Filters results to a specific state or region in AU & NZ*
### Related API Specification
{% content-ref url="/pages/SMyFPz9o7daempZRizy7" %}
[Address Cleanse v1](/loqate-harmony-api/api-specification/deprecated/address-cleanse)
{% endcontent-ref %}
# Address Parse Demo
### Prerequisites
Before you begin you will need a Loqate Harmony Account.
If you do not have Harmony API account you register a free trial.
{% embed url="" %}
### Address Parse Demo
We recommend opening in Codepen (click top right 'Edit on Codepen') for the best experience.
See our guide on [how to use our demo's](/loqate-harmony-api/demos#how-to-use-our-demos). Further guides are below the Codepen.
### Demo Guide
Once you enter your credentials and click start. The demo will appear below.
Enter full address string and click 'Parse'. The full response package of the match is within the response.
#### **Common Options to change**
In Setting the Options button gives you all the API options that you set for different uses for this API.
***Country:*** Set to the target country.
***Source of Truth:*** AU & NZ offer selections of datasets to access.
***Hits:** Alters the amount of results our API returns on a Find request*
***State:** Filters results to a specific state or region in AU & NZ*
### Related API Specification
{% content-ref url="/pages/UXWaaXwtlSoE2mgsMj2M" %}
[Address Parse](/loqate-harmony-api/api-specification/address/address-parse)
{% endcontent-ref %}
# Business Validation Demo
### Prerequisites
Before you begin you will need a Loqate Harmony Account.
If you do not have Harmony API account you register a free trial.
{% embed url="" %}
### Business Validation Demo
We recommend opening in Codepen (click top right 'Edit on Codepen') for the best experience.
See our guide on [how to use our demo's](/loqate-harmony-api/demos#how-to-use-our-demos). Further guides are below the Codepen.
### Demo Guide
Once you enter your credentials and click start. The demo will appear below.
Enter full address string and click 'Validate'. The full response package of the match is within the response.
#### **Common Options to change**
In Setting the Options button gives you all the API options that you set for different uses for this API.
***Country:*** Set to the target country.
***Business Status:*** ACT means ACTIVE, CAN means CANCELLED. In most cases you will want 'ACT" unless looking for Cancelled entities.
***Tax Status:*** ACT means ACTIVE, CAN means CANCELLED.
***Hits:** Alters the amount of results our API returns on a Find request*
***State:** Filters results to a specific state or region in AU & NZ*
### Related API Specification
{% content-ref url="/pages/VXBpoC6mGSdnonIKt82D" %}
[Business Validation and Lookup](/loqate-harmony-api/api-specification/business-validation)
{% endcontent-ref %}
# Email Validation Demo
### Prerequisites
Before you begin you will need a Loqate Harmony Account.
If you do not have Harmony API account you register a free trial.
{% embed url="" %}
### Email Validation Demo
We recommend opening in Codepen (click top right 'Edit on Codepen') for the best experience.
See our guide on [how to use our demo's](/loqate-harmony-api/demos#how-to-use-our-demos). Further guides are below the Codepen.
### Demo Guide
Once you enter your credentials and click start. The demo will appear below.
Enter full email address string and click 'Validate'. The full response package of the match is within the response.
**Options**
**Source of Truth:** Default ''.
**Use Feature Options:** Default is unchecked. Check this box to use timeout feature option.
**Timeout (Optional):** Is used to declare timeout in milliseconds. Sample value "1500".
### Related API Specification
{% content-ref url="/pages/q1KjGwb1g07McwT1DGjN" %}
[Broken mention](broken://pages/q1KjGwb1g07McwT1DGjN)
{% endcontent-ref %}
# Phone Validation demo
### Prerequisites
Before you begin you will need a Loqate Harmony Account.
If you do not have Harmony API account you register a free trial.
{% embed url="" %}
### Phone Validation Demo
We recommend opening in Codepen (click top right 'Edit on Codepen') for the best experience.
See our guide on [how to use our demo's](/loqate-harmony-api/demos#how-to-use-our-demos). Further guides are below the Codepen.
### Demo Guide
Once you enter your credentials and click start. The demo will appear below.
Enter full phone address string and click 'Validate'. The full response package of the match is within the response.
### Related API Specification
{% content-ref url="/pages/HhGDGUFD3213kXUmce24" %}
[Phone Validation](/loqate-harmony-api/api-specification/phone-validation)
{% endcontent-ref %}
# Integrations
# Client Libraries
Fast integrations using our pre-built client side libraries
# Javascript Library v2.7.0
{% hint style="warning" %}
**Important Note**: As of June 2026, we have upgraded the JavaScript library used in Loqate Harmony solutions to the client side to address certain security fixes.
We urge all customers to upgrade their JavaScript client to the latest version (2.7.0) before **Thursday 29 October 2026**. Any JavaScript integration using a version older than 2.7.0 will stop working after this date. Customers must upgrade to 2.7.0 or later to avoid disruption.
{% endhint %}
## Getting Started
### Prerequisites
1. Harmony API Account.
2. We strongly recommend [Allowlisting your domain](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains) when implementing this method.
### Quick Start
Looking to quickly add Harmony to your project? Harmony JS library can be deployed on a web page, allowing users to connect directly to the Harmony API services without any server-side processing requirements. It's recommended to [Allowlist your domain](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains).
Use our content delivery by copying and pasting into your html
```
```
Using a package manager or need to download the source files? Download the files located in content delivery.
#### Initializing the client
Before making service requests, the client must be initialised. This is done by invoking the `init` method on the global `Harmony` object:
```
Harmony.init({String} username, {String} password, {String} locale);
```
This method must be called before any other methods are invoked on the `Harmony` object.
```javascript
```
#### Setting the environment and protocol
During initialization, the client environment is set to Production and the protocol is set to CORS. To use the Production environment or the JSONP protocol, the `useEnv` and `useProtocol` methods can be used.
```javascript
```
## Invoking Address services
Once the client has been initialized, any methods available to the supplied user can be invoked. These methods are invoked using the global `Harmony` object.
### Address Find (Autocomplete)
The following example invokes the `find` method with the single-line address '1 abc street' in Canada. The callback method then output the addresses in a textarea with the id 'output':
```javascript
Harmony.v2.find({ fullAddress: "1 abc street", country: "CA"}, null,
function(response) {
if (response.status == Harmony.SUCCESS) {
// Do something with the response payload.
for (var i = 0; i < response.payload.length; i++) {
var address = response.payload[i];
...
}
} else {
// Show any error messages.
for (var i = 0; i < response.messages.length; i++) {
alert(response.messages[i]);
...
}
}
}
);
```
#### Find FeatureOptions
Only use FeatureOptions when you want to change the system defaults.
The following example configures feature options for address lookup service methods.
```
Harmony.useFeatureOptions({singleLineHitNumber:'10', displayGnafLot: 1,
exposeAttributes:'1', exposePhantom:'0'});
```
## Extending Library for Autocomplete
The client library acts as an extension of JavaScript Library for Address Find (Autocomplete).
Please refer to the Code snippet section to copy and paste to your web page.
### Methods
| Name | Description | Since |
| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| [HarmonyJS.addField](#jsaddfield) | Adds a new field specifying the field name (e.g. `Harmony.POSTCODE`, `Harmony.LOCALITY`, etc) or the attribute name (e.g. `"attributes.Line1"`, `"attributes.Latitude"`, etc), and the input element. | 2.0.0 |
| [HarmonyJS.addressLookup](#jsaddresslookup) | Single-line address lookup on the supplied `input` element. | 2.0.0 |
### HarmonyJS.addField(field, element, index)
Adds a new field specifying the field name (e.g. `Harmony.POSTCODE`, `Harmony.LOCALITY`, etc) or the attribute name (e.g. `"attributes.Line1"`, `"attributes.Latitude"`, etc), and the input element.
#### field
`Type: String`
The name of the field (e.g. `Harmony.POSTCODE`) or attribute (e.g. `"attributes.Line1"`) to be added.
#### element
`Type: Object`
The `input` element to be assigned to the field (e.g. `document.getElementById("postcodeField"))`.
#### index
`Type: Integer`
The optional index if there are multiple sets of lookups on the same page (e.g. one for residential addresses and the other one for postal addresses). Currently only available for `addressLookup`.
The following example assigns the `Harmony.LOCALITY` field to the input element with `localityField` ID and the `"attributes.Latitude"` attribute to the input element with `latitudeField` ID:
```javascript
// Perform the assignment using standard JavaScript on single address lookup.
HarmonyJS.addField(Harmony.LOCALITY, document.getElementById("localityField"));
HarmonyJS.addField("attributes.Latitude", document.getElementById("latitudeField"));
// Perform the assignment using standard JavaScript on the second set address lookup.
HarmonyJS.addField(Harmony.LOCALITY, document.getElementById("localityField"), 1);
HarmonyJS.addField("attributes.Latitude", document.getElementById("latitudeField"), 1);
```
### HarmonyJS.addressLookup(element, countryElement, sourceOfTruth, opts, index)
Creates single-line address lookup with [the current Address lookup APIs ](/loqate-harmony-api/api-specification/address/address-validation-and-lookup)on the supplied `input` and `country` elements. It returns the response from [find](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraFind) service and the callback is available via `onSelect` option.
For [retrieve ](/loqate-harmony-api/api-specification/address/address-validation-and-lookup#retrieve)service, the response is available via `ui.onRetrieveItem` and the callback is available via `onRetrieve` option. For internationalGeocode service, if `getIntlGeocode` options is enabled, the response is available via `ui.onIntlGeocodeItem` and the callback is available via `onIntlGeocode` option.
#### element
`Type: Object`
The `input` address element to create the lookup for (e.g. `document.getElementById("address")`).
#### countryElement
`Type: String or Object`
The Country used for the lookup. It can be String (e.g. `Harmony.AUSTRALIA` for Australia) or Object in `input` or `select` Country element (e.g. `document.getElementById("country")`).
#### sourceOfTruth
`Type: String or Object`
The Source of Truth to override the default Australia and New Zealand SOTs. It is optional. It can be String (e.g. `Harmony.AUPAF` for Australia) or Object in `input` or `select` Source of Truth element (e.g. `document.getElementById("sourceOfTruth")`).
#### opts
`Type: Object`
Optional parameter to be passed into the auto-complete component (e.g. `getIntlGeocode` true/false to enable international geocode call for the selected address, default is false. And callback functions e.g. `onRetrieve` and `onIntlGeocode` in below sample).
#### index
`Type: Integer`
Optional index to indicate which set of fields to populate if there are multiple lookups on the same page.
#### Example
The following example creates a single-line address lookup (use AUPAF for Australian addresses) on the input element with ID `singleLineAddress` and `country` and customized `opts`:
```javascript
let opts = {
// min 3 chars to trigger the lookup
minLength: 3,
//autocomplete function will only be called once within the specified time frame (ms)
delay: 500,
// enable Harmony.International.getGeocode for non-AU/NZ countries when address selected.
getIntlGeocode: true,
//Override onSelect function if applicable. It is Optional
onSelect: function (ui) {
console.log('address selected: ' + JSON.stringify(ui));
},
//Override onIntlGeocode function if applicable. It is Optional
//e.g. get ui.onIntlGeocodeItem object for address payload after onIntlGeocode call.
onIntlGeocode: function (ui) {
console.log('geocode address selected: ' + JSON.stringify(ui.onIntlGeocodeItem));
},
//Override onRetrieve function if applicable. It is Optional
//e.g. get ui.onRetrieveItem object for address payload after onRetrieve call.
onRetrieve: function (ui) {
console.log('onRetrieve address selected: ' + JSON.stringify(ui.onRetrieveItem));
}
};
let input = document.getElementById("addressField");
let country = document.getElementById("countryField");
Harmony.useFeatureOptions({ "exposeAttributes": 0, "groupAddresses": 1 });
HarmonyJS.addressLookup(input, country, null, opts);
```
### Code snippet
Loqate Harmony API provides a self-service console where a customer can quickly generate a ready to use code snippet. You can find more information [here about sign up or login](/loqate-harmony-api/guides/sign-up-login).
The following is an example of how the generated code looks. Please note, the actual user and credential will be different for different customers.
```html
```
# Adobe Commerce (Magento 2) Plugin
Speed up your Adobe Commerce (Magento) checkout with real-time address verification.
​Our Magento extension ticks all the boxes, standardizing AU and NZ addresses in real-time even if your customer makes a typo​.
### Prerequisites
1. Have Adobe Commerce / Magento platform installed.
2. Have a active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/).
3. Downloaded Loqate Harmony - Adobe Commerce / Magento Plugin.
{% content-ref url="/pages/82AiCmxhHqnDDhjuRAXs" %}
[Magento2 User Guide](/loqate-harmony-api/integrations/adobe-commerce-magento-2-plugin/magento2-user-guide)
{% endcontent-ref %}
### Get the Plugin
After registering from account ([free trial here](https://www.loqate.com/anz/register/)) you can download the Plugin from [Harmony Console.](https://hosted.mastersoftgroup.com/console/#/gettingStarted)
# Magento2 User Guide
Loqate AU & NZ Address Autocomplete extension module for Magento2
Version: 1.1.1
### Prerequisites
1. Have Adobe Commerce / Magento platform installed.
2. Have a active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/).
3. Downloaded Loqate Harmony - Adobe Commerce / Magento Plugin.
### Features
* Autocomplete billing and shipping address in Checkout page
* Support all different Magento payment methods
* Support Braintree Payments extension for credit card
* Autocomplete address in My Account page for Customer's billing address and shipping address
* Only enabled when country is selected as Australia or New Zealand
* Configuration for address lookup options, such as Source of Truth
* Control user authorisation via Access Control List (ACL) rules
* Enable/Disable the module in Magento2 Admin
### Releases
* v1.0.x is compatible for Magento 2.2 (tested with Magento 2.2.4)
* v1.1.x is compatible for Magento 2.3 (tested with Magento 2.3.4 and 2.2.4)
### Installation
Go to your Magento2 Home (usually is in `/var/www/html` directory).
It is recommended to backup the existing composer.json in your Magento2 Home directory:
```
/var/www/html# cp composer.json composer.json.old
```
#### Composer Installation
It is available in both GitHub and Packagist.
1. Make sure git is installed: `apt-get install git`.
2. (Optional) To install from GitHub: add this GitHub Repository link to Magento2 composer.json:
```
composer config repositories.mastersoft vcs https://github.com/MastersoftGroup/mastersoft-address-magento
```
This will append 'mastersoft' Repository reference with GitHub Repository URL in composer.json:
```
{
....
"repositories": {
"mastersoft": {
"type": "vcs",
"url": "https://github.com/MastersoftGroup/mastersoft-address-magento"
}
}
}
```
While to install from Packagist, there is no need to do this step.
3. To install the latest release: `composer require mastersoft/address-widget`.
If you encounter this error:
> InvalidArgumentException: Could not find package mastersoft/address-widget at any version for your minimum-stability (stable). Check the package spelling or your minimum-stability.
This is because there is no release yet, alternative option is to install from `dev-master` branch:
```
composer require mastersoft/address-widget:dev-master
```
You can specify a specific version to be installed: `composer require :`.
If successful, you should find the module source in `/var/www/html/vendor/mastersoft/address-widget/` directory.
#### Updating Existing Composer Installation
1. Update `./composer.json` with the version to be downloaded: `composer require mastersoft/address-widget: --no-update`. For example to get the latest `mastersoft/address-widget` from `dev-master` branch:
```
composer require mastersoft/address-widget:dev-master --no-update
```
1. Downloading and installing the specified `mastersoft/address-widget` version: `composer update`.
2. Clear the compiled code and cache in general: `php bin/magento setup:upgrade`.
3. **(For Production mode only)** Recompile your Magento project: `php bin/magento setup:di:compile`.
4. **(For Production mode only)** Deploy static files to `pub/static/` directory:
```
php bin/magento setup:static-content:deploy en_AU en_US
```
If you know the files and content that have been updated in this new version, you should be able to verify in the module source: `/var/www/html/vendor/mastersoft/address-widget/` directory.
If after this installation, the page is blank or encounter permission error or other errors, please follow some commands in Post Installation.
#### Manual Installation
1. Download the zip file in `ZIP` directory.
2. Unzip it in your Magento2 Home directory, it will merge with existing directories and files.
You should find the module source in `/var/www/html/app/code/Mastersoft/AddressWidget/` directory.
Alternatively, you can also use the zip file downloaded from GitHub:
1. In GitHub -> click `Clone or download` button on top right corner -> click `Download ZIP` link in GitHub
2. In Magento2 Home, create sub-directories `app/code/Mastersoft/AddressWidget/`.
3. Unzip the content of the zip file to `app/code/Mastersoft/AddressWidget/` directory. You should see `composer.json` and `registration.php` files directly in this directory.
#### Post Installation
These steps must be followed after Composer Installation or Manual Installation steps above.
1. Verify `Mastersoft_AddressWidget` module is installed properly: `php bin/magento module:status`. It is now should be listed in the Disabled Modules.
2. Enable the module: `php bin/magento module:enable Mastersoft_AddressWidget`.
3. Register the extension and update the database: `php bin/magento setup:upgrade`.
4. **(For Production mode only)** Recompile your Magento project: `php bin/magento setup:di:compile`.
5. **(For Production mode only)** Deploy static files to `pub/static/` directory:
```
php bin/magento setup:static-content:deploy en_AU en_US
```
This is very important for Production mode, otherwise your store and store admin will not load correctly because of some js and css files are not found, and users will not be able to load Checkout and edit Customer Address.
6. Verify `Mastersoft_AddressWidget` module is enabled: `php bin/magento module:status`. It is now should be listed in the Enabled Modules.
7. (Optional) Other commands maybe needed if the page is blank or encounter permission error or other errors:
```
php bin/magento cache:clean
php bin/magento cache:flush
chown -R :www-data var/cache
chmod -R 777 app/ var/ pub/ generated/
rm -rf var/cache/* var/page_cache/*
```
8. Update Mastersoft Address Configuration.
### Disabling/Enabling Module
There are 2 ways to disable/enable this module:
1. Magento Admin\
Go to Mastersoft Address Configuration: in `Enable Module` field, select `No` to disable module or `Yes` to enable module, and click `Save Config` button.
By disabling the module via Mastersoft Address Configuration, the module status is still enabled but it will not load the module javascript.
OR
2. Magento Command\
To disable module:
```
php bin/magento module:disable Mastersoft_AddressWidget --clear-static-content
php bin/magento setup:upgrade
php bin/magento module:status
```
You can enable the module easily by following the Post Installation steps.
### Uninstallation
Following these steps will fully uninstall this module: clean the module code, database, and any module references. You will need to follow the installation steps to be able to use this module again.
#### Composer Uninstallation
**This will work only if the module was installed using Composer.**
1. Disable `Mastersoft_AddressWidget` module by following Disabling/Enabling Module using **Magento Command** steps.
2. Uninstall module:
```
php bin/magento module:uninstall Mastersoft_AddressWidget -r -c
```
* `-r` or `--remove-data`: very important to remove the relevant configuration data stored in the database
* `-c` or `--clear-static-content`: remove the static content
* `--backup-db`: backup the Magento2 database
* `--backup-code`: backup Magento file system (excluding `var` and `pub/static` directories)
* `--backup-media`: backup `pub/media` directory
These backup files will be stored in `var/backup/` directory.
If the module was not installed using Composer, running this command will give an error. Continue the uninstallation by following the Manual Uninstallation steps.
3. Update database: `php bin/magento setup:upgrade`.
4. IMPORTANT: If the module source under `vendor/mastersoft/address-widget/` directory is still not deleted, run:
```
composer remove mastersoft/address-widget
```
This will delete `mastersoft` directory under `vendor` directory and properly clean all module references in composer configuration files.
#### Manual Uninstallation
1. Disable `Mastersoft_AddressWidget` module by following Disabling/Enabling Module using **Magento Command** steps.
2. Delete module source directory:
* Composer installation: `rm -rf vendor/mastersoft` or
* Manual installation: `rm -rf app/code/Mastersoft`
3. Clean database by logging in to magento2 database and execute these queries:
```
// Delete module registration
DELETE FROM setup_module WHERE module='Mastersoft_AddressWidget';
// Delete module configuration
DELETE FROM core_config_data WHERE path like 'Mastersoft_AddressWidget/%';
```
4. Remove module reference `Mastersoft_AddressWidget` in `app/etc/config.php`.
5. Compile the code and clear the cache
```
php bin/magento setup:upgrade
php bin/magento cache:flush
```
### Configuration
In Magento Admin Dashboard of your Store: `Stores` -> `Configuration` -> `Services` -> `Mastersoft Address`.
* **Licence Key** (Mandatory)\
Default value: blank/empty. Must be in this format: **username-without-domain:password**.\
**Get your FREE licence key** [**here**](https://www.loqate.com/anz/register/)**.**
* **URL** (Mandatory)\
Default value: `https://hosted.mastersoftgroup.com`
* **Default Widget Options**\
Generic Widget Options for both AUSTRALIA and NEW ZEALAND.\
Default value: `{ singleLineHitNumber: 5, caseType: 'TITLE' }`
* **Widget Options for AUSTRALIA**\
Default value: `{ sot: 'GNAF' }`
* **Widget Options for NEW ZEALAND**\
Default value: `{ sot: 'NZPAF' }`
* **Enable Module**\
Default value: `Yes`
All Widget Options must be in valid JSON format and must use single-quote for String value, **DO NOT use double-quote anywhere**.
For Widget Options for certain country, if the same option key is defined in the Default Widget Options, the value in the Widget Options for certain country will take precedence over the value in the Default Widget Options.
To configure the Widget Options, here is the full list of FeatureOption available.
### Setting ACL Rules
In Magento Admin Dashboard of your Store: `System` -> `User Roles` -> `Add/Edit Role` -> `Role Resources`.
Select `Custom` from `Resource Access` dropdown menu, you will see `Mastersoft Address Configuration` rule, which now you can assign to admin roles in the system, and those admin roles can be assigned to users.
When this `Mastersoft Address Configuration` rule is not checked for that particular role, whoever is assigned to this role will not be able to see and access the Mastersoft Address Configuration link and page.
# Woocommerce Plugin
Optimise your WooCommerce checkout process with real-time verification, single line lookup of address & businesses, validate email & phone numbers in checkout. Download for free.
Turns your checkout into a performance checkout by saving the customer time in checkout, reduces failed deliveries, reduces failed contacts and builds trust. Powered by the most curated address and location data in the world.
Loqate is the most advanced software for capturing, verifying and enriching address data globally - delivering the unrivalled precision businesses need.
**Tested versions:**
We believe the plugin will work with most versions of Woocommerce. We have tested these versions for current and backwards compatibility.
`WooCommerce 8.2.1`
`WooCommerce 7.8.0`
`WooCommerce 3.4.5`
### Address Lookup & Validation
* Remove 6 address fields into one seamless address lookup serive using authoritative global address data. Reduces keystrokes by 78%, reducing overall time to write an address from 24 seconds to 6 seconds error free.
* Prebuilt integration with Loqate AU & NZ
### Email Validation
* Ensure you collect the right contact information before its too late, increase email delivery rates, improve your sender reputation and advance customer communications.
* Prebuilt integration with Loqate AU & NZ
### Phone Validation
* Confirm a mobile phone number is accurate and connected at the point of entry.
* Prebuilt integration with Loqate AU & NZ
### Business Lookup & Validation
* Know your business. Fast reliable Business/Company Lookup for Australia and New Zealand using name, business or company numbers.
* Know that business is active and registered for Tax.
* Prebuilt integration with Loqate AU & NZ
### Prerequisites
1. Have Woocommerce platform installed.
2. Have a active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/).
3. Download Plugin from [Harmony Console.](https://hosted.mastersoftgroup.com/console/#/gettingStarted)
1. [See Woocommerce installation guide](/loqate-harmony-api/integrations/woocommerce-plugin/woocommerce-user-guide).
2. We've pre-configured to be optimised out of the box. You can configure the API to your use case. [See Woocommerce settings guide](/loqate-harmony-api/integrations/woocommerce-plugin/woocommerce-settings-guide-v2.0.0).
{% content-ref url="/pages/wGchle4vkQexGC97AGd1" %}
[Woocommerce Install Guide v2.0.0](/loqate-harmony-api/integrations/woocommerce-plugin/woocommerce-user-guide)
{% endcontent-ref %}
### Get the Plugin
After registering from account ([free trial here](https://www.loqate.com/anz/register/)) you can download the Plugin from [Harmony Console.](https://hosted.mastersoftgroup.com/console/#/gettingStarted)
# Woocommerce Install Guide v2.0.0
How to install Loqate AU NZ Woocommerce Plugin
Version: 2.0.0
All versions available in
### Prerequisites
1. Have Wordpress platform and Woocommerce plugin installed or available oncloud.
2. Have a active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/).
3. Download Loqate AU NZ Woocommerce plugin from [github ](https://github.com/MastersoftGroup/woocommerce-mastersoft-address)or [packgist](https://packagist.org/packages/mastersoft/woocommerce-mastersoft-address)
### Features
Performance checkout with Address lookup and validation for WooCommerce Checkout and Account Billing and Shipping Addresses, as well as checkout with Address lookup and validation, business lookup and validation, email and phone validation​
Turns your checkout into a performance checkout by saving the customer time in checkout, reduces failed deliveries, reduces failed contacts and builds trust. Powered by the most curated address and location data in the world.
Loqate is the most advanced software for capturing, verifying and enriching address data globally - delivering the unrivalled precision businesses need.
Features:
* Autocomplete billing and shipping address, business lookup, email and phone validation in Checkout page
* Autocomplete address in My Account page for Customer's billing address and shipping address
* Support for over 245 countries addresses, including AU, NZ, US, UK, CA etc
* Flexible configurations for the lookup and validation depending on the business needs.
Get started with a [free trial here](https://www.loqate.com/anz/register/).
### Installation
This plugin requires WooCommerce. Please make sure WooCommerce is installed.
#### Automatic installation
Automatic installation is not currently available.
#### Manual installation
1. Download the zip file of the latest release from [GitHub](https://github.com/MastersoftGroup/woocommerce-mastersoft-address).
2. Upload the zip file to your WordPress plugins directory by either:
* Upload the zip file using your WordPress Admin:
Log in to WordPress Admin > go to `Plugins` > `Add New` > `Upload Plugin` button > upload the zip file
**OR**
* Upload and unzip the zip file into your WordPress plugins directory: `WP_ROOT/wp-content/plugins/`. The `WP_ROOT` is usually `/var/www/html/`.
After installation, the WordPress plugins directory should include the `woocommerce-mastersoft-address` directory with the same file structure as the GitHub.
#### Composer installation
The plugin is also available for installation from [Packagist](https://packagist.org/packages/mastersoft/woocommerce-mastersoft-address).
1. Download and install composer:
```
$ curl -sS https://getcomposer.org/installer | php
$ mv composer.phar /usr/local/bin/composer
```
2. Install with composer by either:
* Create `composer.json` file in the `WP_ROOT` and add the `mastersoft/woocommerce-mastersoft-address` package. For example, to add `woocommerce-mastersoft address` v2.0.0.
```
{
"require": {
"mastersoft/woocommerce-mastersoft-address": "2.0.0"
}
}
```
Install the package:
`$ composer install`
**OR**
* Use extended composer command and install:
`$ composer require mastersoft/woocommerce-mastersoft-address:`
The `` is optional.
After installation, the WordPress plugins directory should include the `woocommerce-mastersoft-address` directory with the same file structure as the GitHub.
**Updating an existing Composer installation**
1. Update `composer.json` in your WordPress plugins directory with the version to be downloaded:
`$ composer require mastersoft/woocommerce-mastersoft-address: --no-update`
Alternatively, you can also update the version of `mastersoft/woocommerce-mastersoft-address` package in the `composer.json` file by directly editing it.
2. Download and install the updated version of `mastersoft/woocommerce-mastersoft-address`:
`$ composer update`
#### Post installation
1. Activate plugin: log in your WordPress Admin > got to `Plugins` > `Installed Plugins` > scroll to `Loqate AU NZ Address` plugin and click `Activate`
2. Configure plugin by following the Configuration guide.
#### Disable/enable plugin
To disable: log in to your WordPress Admin > go to `Plugins` > `Installed Plugins` > scroll to `Loqate AU NZ Address` plugin and click `Deactivate` to disable plugin.
This will disable the functionality but will still keep all your configuration settings, so you do not need to configure when you enable the plugin again.
To enable: log in to your WordPress Admin > go to `Plugins` > `Installed Plugins` > scroll to `Loqate AU NZ Address` plugin and click `Activate` to enable plugin.
#### Uninstallation
Log in to your WordPress Admin > go to `Plugins` > `Installed Plugins` > scroll to `Loqate AU NZ Address` and click `Deactivate` and `Delete`.
This will uninstall and delete all the configuration settings in your database.
If there is an error message during the deleting process `Could not fully remove the plugin ....`, please make sure the file ownership is set to `www-data`. To correct the ownership, change to your WordPress plugins directory:
`$ chown -R www-data:www-data woocommerce-mastersoft-address`
### Configuration
Log in to your WordPress Admin > go to `WooCommerce` > `Settings` > `Loqate AU NZ Address`.
* **Licence Key:** (mandatory). Get your [free trial here](https://www.loqate.com/anz/register/). Must be in **username-without-domain:password** format. Default Value: blank/empty.
* **Address Layout Options:** Address layout options. Must be in valid format. Options {"layout":"OPTIMISED"} or {"layout":"DEFAULT"}. The preconfigured value:
`{ "layout": "`OPTIMISED`" }`
* **Address Feature Options:** Must be in valid format. Full list of [Feature Options](/loqate-harmony-api/api-specification/objects/address-objects#featureoption). The preconfigured value:
`{ "singleLineHitNumber": 5, "caseType": "TITLE", "displayGnafLot":1,"suppressLot":1 }`
* **Address Data AUSTRALIA:** Must be in valid format. The preconfigured value is {"sot":"GNAF"}. Options {"sot":"AUPAF"} , {"sot":"AUSOTS"} .
`{ sot: "GNAF" }`
* **Address Data NEW ZEALAND:** Must be in valid format. Options {"sot":"NZAD", "exposeAttributes":"1"} , {"sot":"CNAR"}. The preconfigured value:
`{ "sot": "NZPAF" }`
* **Enhanced State/Country/Region:** checkbox. To enable this setting to make use of our comprehensive collection of state/county/region or the equivalent.
* **Business Lookup:** checkbox. To enable business lookup.
* **Widget Options for Business Lookup:** Must be in valid format.Note: state only applicable for au business lookup, it will be ignored for other countries. Further documentation of the [options ](/loqate-harmony-api/api-specification/objects/business-objects#businessrequest). The preconfigured value:
`​{ "caseType": "TITLE", "hits": 5, "taxStatus": "", "bnStatus": "", "state": ["NSW","VIC","QLD","ACT","SA","WA","NT"], "nameTypes": ["MN","BN","TRD","OTN","LGL","DGR"] }`
* **Display Main/Legal Entity Name:** checkbox. To enable this setting if you wish to populate main/legal entity name which might be different from the entity's alias name entered by user.
* **Email Validation:** checkbox. To enable email validation.
* **Widget Options for Email Validation:** Must be in valid format. Further documentation of the [configuration](/loqate-harmony-api/api-specification/email-validation#request). The preconfigured value:
`​`{ "sot": "VE\_ALL", "options": \[ "FORMAT", "BLOCKLIST", "DOMAIN", "MAILSERVER", "MAILBOX" ] }
* **Phone Validation:** checkbox. To enable phone validation.
### Frequently Asked Questions
#### How do I get a licence key?
You can get a [free trial here](https://www.loqate.com/anz/register/) and start using it right away.
#### What are all available Widget Options to configure in the settings?
Widget Options are basically `sot` for `Source of Truth` value and key value of `FeatureOptions`.
Currently these Source of Truth are available for AUSTRALIA: `AUPAF`, `GNAF` and for NEW ZEALAND: `NZPAF`, `NZAD`.
Here is the full list of [Feature Options.](/loqate-harmony-api/api-specification/objects/address-objects#featureoption)
# Woocommerce Settings guide v2.0.0
How to configure the settings Loqate AU NZ Woocommerce Plugin. You have full control over what is enabled with full access to API settings.
Version: 2.0.0
Navigate to Plugins and click on settings... /wp-admin/plugins.php and find 'Loqate AU & NZ Address' plugin
### Step 1: Get your API Keys
Get your Loqate AU NZ API Keys from
We wrote a guide for getting your API keys.
{% content-ref url="/pages/VvdkGCL1SrmqLDqhO5il" %}
[Getting your API keys](/loqate-harmony-api/guides/console/getting-your-api-keys)
{% endcontent-ref %}
If you don't have a Loqate AU NZ account sign up here to free trial:
### Step 2: Add your API Keys to Woocommerce V2 Plugin
Navigate to Plugins and click on settings... /wp-admin/plugins.php and find 'Loqate AU & NZ Address' plugin
Your API key is concatenated {user name}:{password}.
For example if
User Name = 'myuser' and password ='mypassword' then you enter myuser:mypassword. Don't forget the semi colin :
**Alright you should be all set to start using using our default performance checkout settings.**
## Optional Settings
### Address Layout Options
Address Layout modifies your checkout experience for your users. We have two options available Optimised or Default.
**Optimised** being single line address. This hides 5 address fields and shortens your overall checkout form. Its the recommended setting.
Insert the below code block for Optimised
```json
{ "layout": "DEFAULT" }
```
**Default** is Woocommerces standard checkout.
Insert the below code block for Default
```json
{ "layout": "DEFAULT" }
```
#### Checkout experience
### Address FeatureOptions
Address FeatureOptions is the API settings for our Address Lookup service. Our Address Lookup has a broad range of feature that you can optimise for your application.
All of these settings we can configure for you in the backend meaning you don't have to update these settings yourself.
Read about the featureOptions available here:
#### Default setting
This shows 5 results, in Title Case and suppresses Lot information when street numbers are available.
```json
{ "singleLineHitNumber": 5, "caseType": "TITLE", "displayGnafLot":1,"suppressLot":1 }
```
#### Add User Derived Address:
Learn about [User Derived Address](/loqate-harmony-api/guides/user-derived-address)
```json
{ "userInferred": 1, "singleLineHitNumber": 5, "caseType": "TITLE", "displayGnafLot":1,"suppressLot":1 }
```
#### For International (not AU & NZ) regions (recommended)
Grouping addresses particularly in countries with large populations in multi dwelling premises. Recommended setting.
We don't apply grouping to AU & NZ country searches.
```json
{ "groupAddresses": "1", "singleLineHitNumber": 5, "caseType": "TITLE", "displayGnafLot":1,"suppressLot":1 }
```
#### Add AustPost Parcel Locker data
This will include Australia Post parcel lockers, post offices and post shops to delivery selection options.
```json
{ "moreSources": "AUPOST", "singleLineHitNumber": 5, "caseType": "TITLE", "displayGnafLot":1,"suppressLot":1 }
```
#### Add them all
We've only list some of the available featureOptions.
Read about all the featureOptions available here:
```json
{ "userInferred": 1, "groupAddresses": "1", "moreSources": "AUPOST", "singleLineHitNumber": 5, "caseType": "TITLE", "displayGnafLot":1,"suppressLot":1 }
```
### Address Data - Australia
Within Australia we have 3 datasets the you can use. Choosing the right dataset is critical. Contact us for advice.
AUPAF: Australia Post Postal Address File (Postal Certified)
GNAF: Geocoded National Address File (Physical addresses)
AUSOTS: Combined AUPAF & GNAF for highest coverage.
```json
// for GNAF
{ "sot": "GNAF" }
// for Australia Post
{ "sot": "AUPAF" }
// for Australia Post & GNAF combined
{ "sot": "AUSOTS" }
```
### Address Data - New Zealand
Within New Zealand we have 3 datasets the you can use. Choosing the right dataset is critical. Contact us for advice.
NZPAF: New Zealand Posts - Postal Address File (Postal Certified deliverable)
NZAD: New Zealand Posts - Address File (Physical addresses)
CNAR: Critchlow / National Map is Physical address file with improved Geocoding results.
```json
// for New Zealand Posts - Postal Address File (Postal Certified deliverable)
{ "sot": "NZPAF" }
// for New Zealand Posts - Address File (Physical addresses)
{ "sot": "NZAD" }
// for Critchlow / National Map
{ "sot": "CNAR" }
```
### Enhanced State/County/Region
Loqate is a global address experts.
Ticking this box overrides Woocommerce representations of regional information and uses Loqates comprehensive collection of state/county/region or the equivalent.
For some regions syncing of Loqate data with Woocommerce lists of regions is not always possible. Enabling will overwrite with Loqate data.
### Business Lookup
Enable or disable the Business Lookup service. Business Lookup enables users to search for the business names, business or company numbers within the company field in checkout.
In checkout, reduce time in checkout, accurately capture business customers, know your business identifiers.
#### Checkout experience
#### Filter for Active Businesses
```json
{
"caseType": "TITLE",
"hits": 5,
"taxStatus": "ACT",
"bnStatus": "",
"state": [],
"nameTypes": []
}
```
#### Filter for Active Businesses & Active tax registration
#### Filter by State
If only conducting business in a particular state you can filter your results.
```json
{
"caseType": "TITLE",
"hits": 5,
"taxStatus": "",
"bnStatus": "",
"state": ["VIC", "NSW"],
"nameTypes": []
}
```
#### Display Main/Legal Entity Name
Main/legal entity name which might be different from the entity's alias name entered by user.
For example: You might know McDonalds the brand or a 'trading name'. Legal entity name is different and this option changes the information being displayed to legal entity names.
### Email Validation
Enable or disable the Email Validation within the checkout experience.
#### Checkout experience
This displays the result of the validation to the end user. Results that are valid or indeterminate can proceed to the next step. Invalid email addresses are alerted within checkout enabling users to correct any issues they have.
#### Default Email Options
We recommend you keep the default configuration.
```json
{ "sot": "VE_ALL", "options": [ "FORMAT", "BLOCKLIST", "DOMAIN", "MAILSERVER", "MAILBOX" ] }
```
### Phone Validation
Enable or disable the phone validation.
Like email validation phone displays the result of the validation to the end user. Results that are valid or indeterminate can proceed to the next step. Invalid phone numbers are alerted within checkout enabling users to correct any issues they have.
# Shopify Plus App
Checkout UI for Shopify Plus checkout with real-time address verification.
*Our Shopify Plus standardises AU, NZ and international addresses in real-time using Shopify Plus Checkout extensions.*
***
### Prerequisites
1. Have Shopify Plus platform installed.
2. Have an active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/).
3. Contact Support or Account Manager to get the Custom App.
### Custom App - Install
1. Get the app link from Loqate Support then paste into your browser that is logged into your store. One app link per organisation can have many Stores.
2. Review App permissions and press install
### Set-up API Key for Shopify Plus
1. You will need a your Harmony API keys (see [getting your api keys](/loqate-harmony-api/guides/console/getting-your-api-keys).) Then base64 encode these keys.
2. Your user will need domain extensions.shopifycdn.com added to key. See ([allowlisting domain](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains))
3. To base64 encode username and password in format '{user}:{password} or Contact support who can supply you with this.
4. Enter your base 64 encoded keys into the Loqate API Key section
### Configure each store
Each store requires manual configuration to ensure other solutions do not interfere with performance of Loqate Harmony solution.
1. ***Select Checkout on left navigation and scroll down***
2. ***Uncheck the 'Validate shipping address' option.***
3. ***Navigate to top and this time go into Store Customize***
4. ***Scroll down the left have options until you reach 'Address autocompletion' and disable it.***
5. ***Ensure you have added the loqate-checkout app block.***
### Testing your Installation
You are now ready to test connectivity within your store.
If you need to configure requests this can be done by contacting support.
### Configuration of requests
You can still use all our API settings (featureOptions). For Shopify Plus these are set in our API by our service team.
For example using:
* Dataset / SOT per country - Basic or Pro
* [AU Parcel Lockers](/loqate-harmony-api/guides/parcel-locker-plus)
* [Derived sub-premise feature](/loqate-harmony-api/guides/user-derived-address)
See all [Address featureOptions ](https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/address/address-validation-and-lookup#/request)here for particular services.
# Gravity Forms
Gravity Forms is a powerful form-building plugin for WordPress that allows you to create complex forms with ease. Utilise Gravity Forms to enhance your workflows with real-time address verification.
*Our plugin standardises and verifies AU, NZ and international addresses, email and phone in real-time using the below code.*
***
### Prerequisites
1. Have Wordpress platform and Gravity Forms plugin installed or available oncloud.
2. Have an active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/).
### Enabling Address, Phone and Email verification in Gravity Forms
Here is the actual working demo and actual code used. You can use this as a reference. You just need to supply the user and credential in the code.
{% embed url="" %}
Just copy the below code to your HTML Block component.
```
```
### Set-up API Key and the above sample code in Gravity Forms
1. You will need your Harmony API keys (see [getting your api keys](/loqate-harmony-api/guides/console/getting-your-api-keys).)
2. Your user will need domain (e.g. \*.wpcomstaging.com) added to key. See ([allowlisting domain](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains))
### Testing your Installation
You are now ready to test connectivity within your form.
### Configuration of requests
You can still use all our API settings (featureOptions).
For example using:
* Dataset / SOT per country - Basic or Pro
* [AU Parcel Lockers](/loqate-harmony-api/guides/parcel-locker-plus)
* [Derived sub-premise feature](/loqate-harmony-api/guides/user-derived-address)
See all [Address featureOptions ](https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/address/address-validation-and-lookup#/request)here for particular services.
# Voxco Survey Software
Voxco is a great survey software to run any type of survey, including employee engagement, customer satisfaction, or transition feedback.
*Our plugin standardises and verifies AU, NZ and international addresses, email and phone in real-time using the below code.*
***
### Prerequisites
1. Have a ready Voxco instance.
2. Have an active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/).
### Enabling Address, Phone and Email verification in Voxco
Just copy the below code in code view (click the \), to the main question text in Voxco online.
```
```
### Set-up API Key and the above sample code in Voxco
1. You will need your Harmony API keys (see [getting your api keys](/loqate-harmony-api/guides/console/getting-your-api-keys).)
2. Your user will need domain (e.g. \*.yourdomain.com) added to key. See ([allowlisting domain](/loqate-harmony-api/guides/console/subscriptions/allowlisting-domains))
### Testing your Installation
You are now ready to test connectivity within your form.
### Configuration of requests
You can still use all our API settings (featureOptions).
For example using:
* Dataset / SOT per country - Basic or Pro
* [AU Parcel Lockers](/loqate-harmony-api/guides/parcel-locker-plus)
* [Derived sub-premise feature](/loqate-harmony-api/guides/user-derived-address)
See all [Address featureOptions ](https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/address/address-validation-and-lookup#/request)here for particular services.
# Salesforce CRM
Loqate helps eliminate friction and ensures only complete and accurate address data comes from your Salesforce forms.
A great CRM starts with great data. Loqate helps ensure accurate and complete address entry as you type in real-time on Salesforce CRM.
Our plugin standardizes all global addresses & AU Businesses upon entry in the CRM, even if you make a typo.
### Prerequisites
1. Have Salesforce CRM platform installed.
2. Have a active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/). You will need to contact Sales to enable Salesforce CRM feature.
3. Get from Salesforce [AppExchange](https://appexchange.salesforce.com/appxListingDetail?listingId=a0N30000003HlOZEA0)
4. Download Salesforce Installation Guide
{% file src="/files/gBZuK0ECNX8zXrfhoOFb" %}
### Features
Harmony API verifies addresses using simple yet powerful real-time validation. Verification is based on Australia Post (AMAS) data and Australian Business Register.
HRA rapidly validates addresses directly in salesforce.com, including visualforce pages, in the familiar Salesforce look and feel.
Key features:
* For Australia and New Zealand Salesforce Users
* Predictive search-as-you-type
* Australia Post (AMAS) certified
* Works with Visualforce pages
* Email & Phone verification
* ABN and Australian company name lookup
* Fast Data Entry
* Batch Matching and Validation functionality
* Standardise naming of Australian company names (No more CBA, Comm Bank etc)
* DPID, ASGS and SEIFA attributes provided
* Bank graded security for data transmission
* Fully cloud-based & scalable
* Can be used from mobile devices
* Super simple setup
* Lightning Ready
GBG Loqate Harmony API is one of Australia’s leaders in data validation and address matching. Harmony API has the ability to validate your current database and auto-complete addresses. A direct integration with Salesforce makes Harmony API a must-have application for businesses who deal with large databases.
# Dynamics 365 CRM
A faster, easier way to enter and verify addresses in Microsoft Dynamics 365.
A great CRM starts with great data. Loqate helps ensure accurate and complete address entry as you type in real-time on Microsoft Dynamics 365. Our plugin standardizes all global addresses upon entry in the CRM, even if you make a typo.
### Prerequisites
1. Have Dynamics 365 CRM platform installed.
2. Have an active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/).
3. Download the installation guide for reference
{% file src="/files/Q5iAvZvcRtlIEnufm3Wz" %}
### Installation File
Download the plugin installation file below for installation
{% file src="/files/tgOcbJKMnLf3F7iUsY26" %}
# Batch App - Lightweight
A faster, easier way to enter and verify addresses in small batches.
### Prerequisites
1. Have a active Loqate Harmony API Account. You can sign-up for [free trial here](https://www.loqate.com/anz/register/). You will need to enable Address Cleanse, Phone or Email API services on your account. Contact sales.
2. Get from our Batch App - Lightweight from Harmony Support team
### Key Features
Batch App lite processes 20,000 records directly from your desktop using our API services.
We have 3 different versions for Address, Phone and Email.
# Deprecated Integrations
# Harmony RightAddress c# example
This is an example of how to call Harmony RightAddress REST API using c#.
The following example invokes REST request for the address method with the single line address '220 George St' and the 'AUPAF' reference data set (Source of Truth):
```
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Net;
using System.Text;
using System.Threading.Tasks;
namespace HarmonyHostedClient
{
class Program
{
// the end point for which environment to access
private const string END_POINT
= "https://hosted.mastersoftgroup.com/harmony/rest/au/address";
// Go to https://hosted.mastersoftgroup.com/console to get user/credential
private const string USER = "user";
private const string CREDENTIAL = "credential";
// the reference data set (SOT): AUPAF, GNAF, and etc
private const string SOT = "AUPAF";
static void Main(string[] args)
{
string result = lookupAddress("220 George St");
Console.WriteLine(result);
System.Diagnostics.Debug.WriteLine(result);
}
static string lookupAddress(string escapedInput)
{
var httpWebRequest = (HttpWebRequest)WebRequest.Create(END_POINT);
httpWebRequest.ContentType = "application/json";
httpWebRequest.Method = "POST";
// authentication
string encoded = Convert.ToBase64String(
Encoding.GetEncoding("ISO-8859-1").GetBytes(USER + ":" + CREDENTIAL));
httpWebRequest.Headers.Add("Authorization", "Basic " + encoded);
using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{
// make sure input is escaped
string json = "{ \"payload\": [{ \"fullAddress\": \"" +escapedInput+ "\"}], " +
" \"sourceOfTruth\": \""+SOT+"\"}";
streamWriter.Write(json);
}
// may need to handle exceptions
var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
{
var responseText = streamReader.ReadToEnd();
return responseText;
}
}
}
}
```
See the [Harmony RightAddress API](/loqate-harmony-api/api-specification) documentation for details on invoking the other Harmony RightAddress service methods.
# Harmony RightAddress cURL example
This is an example of how to do cURL request in Harmony RightAddress. The following example invokes cURL request for the address method with the single line address.
```
curl https://hosted.mastersoftgroup.com/harmony/rest/au/address \
-H "Content-Type:application/json" \
-H "Accept:application/json" \
-X POST \
-u webUser:password \
-d "{\"payload\":[{\"fullAddress\":\"1 abc street\"}],\"sourceOfTruth\":\"AUPAF\"}"
```
See the [Harmony RightAddress JavaScript client API](/loqate-harmony-api/integrations/client-libraries/javascript-library-v2.7.0) documentation for details on invoking the other Harmony RightAddress service methods.
# Deprecated JS Library v2.0.1
{% hint style="warning" %}
This method has been deprecated. Please use current version for new implementations.
{% endhint %}
## JavaScript client
JavaScript client is a JavaScript library that can be included on a web page, allowing website users to connect directly to the Harmony API services without any server-side processing requirements. For versions earlier than 1.8.0 please refer to [the previous version of Harmony RightAddress JavaScript Client ](https://developer.mastersoftgroup.com/harmony/client/js/v1/index.html)for code snippet.
For the best experience, we recommend you to use the latest versions of your favourite browsers.
* As of version 1.3.0, the Harmony RightAddress JavaScript client can be configured to use either Cross Origin Resource Sharing (CORS) or JSON with Padding (JSONP). CORS is preferable for modern browsers.
* Please note that IE 11 will no longer be supported by Microsoft after August 17th, 2021.
### Code snippet
UsernamePasswordAddress Id
Copy and paste the following code snippet into your web page.
```
```
### Pre-requisites
Before you can use the Harmony RightAddress client, you must make sure you have:
* An active Harmony RightAddress account
* A Harmony RightAddress username and password for your domain
* A proficiency in JavaScript
### Getting the client
The versions of the JavaScript client can be downloaded using the following link:
* [harmony-2.0.1.min.js](http://common.mastersoftgroup.com/scripts/harmony-2.0.1.min.js)
* For any earlier versions of client please contact us.
### Initialising the client
Before making service requests, the client must be initialised. This is done by invoking the `init` method on the global `Harmony` object:
```
Harmony.init({String} username, {String} password, {String} locale);
```
This method must be called before any other methods are invoked on the `Harmony` object.
```
```
### Setting the environment and protocol
During initialisation, the client environment is set to Production and the protocol is set to CORS. To use the Production environment or the JSONP protocol, the `useEnv` and `useProtocol` methods can be used.
```
```
### Invoking service requests
Once the Harmony RightAddress client has been initialised, any methods available to the supplied user can be invoked. These methods are invoked using the global `Harmony` object.
The following example invokes the `find` method with the single-line address '1 abc street' in Canada. The callback method then output the addresses in a textarea with the id 'output':
```
```
See the[ JavaScript client API v2.0.1 ](#harmony-rightaddress-javascript-client-api)documentation for details on invoking the other Harmony API service methods.
## JavaScript client API v2.0.1
The client library acts as a JavaScript wrapper for the Harmony RightAddress Services. The objects used by the library are JavaScript representations of those found in the [Harmony RightAddress service API](https://developer.mastersoftgroup.com/harmony/api/).
**It is recommended to use the current Javascript Client Address lookup methods.** However [the previous version of JavaScript Client Address lookup methods](https://developer.mastersoftgroup.com/harmony/client/js/v1/api.html) is still available.
### Constants
| Name | Type | Description |
| -------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Harmony.ENV\_PREVIEW | Environment | The PREVIEW environment |
| Harmony.ADDRESS | Field | The single-line Address field |
| Harmony.ATTRIBUTES | Field | The Attributes field |
| Harmony.BUILDING\_NAME | Field | The Building Name field |
| Harmony.CITY | Field | The City field |
| Harmony.DISTRICT | Field | The District field |
| Harmony.EID | Field | The Encrypted ID field |
| Harmony.FULL\_ADDRESS | Field | The Full Address field |
| Harmony.ID | Field | The ID field |
| Harmony.LOCALITY | Field | The Locality field |
| Harmony.POSTAL | Field | The Postal field |
| Harmony.POSTCODE | Field | The Postcode field |
| Harmony.POSTCODE\_LOCALITY | Field | The Postcode and Locality combined field |
| Harmony.PROVINCE | Field | The Province field |
| Harmony.SOURCE\_OF\_TRUTH | Field | The Source of Truth field |
| Harmony.STATE | Field | The State field |
| Harmony.STATE\_TOWN\_CITY | Field | The State and Town/City combined field |
| Harmony.STREET | Field | The Street field |
| Harmony.STREET\_ADDRESS | Field | The Street Address field |
| Harmony.STREET\_NUMBER | Field | The Street Number field |
| Harmony.SUBDWELLING | Field | The Subdwelling field |
| Harmony.SUBURB | Field | The Suburb field |
| Harmony.TOWN\_CITY | Field | The Town/City field |
| Harmony.AUSTRALIA | Locale | The Australian locale |
| Harmony.NEW\_ZEALAND | Locale | The New Zealand locale |
| Harmony.INTERNATIONAL | Locale | The international locale except Australian and New Zealand |
| Harmony.CORS | Protocol | Cross-Origin Resource Sharing (CORS) protocol |
| Harmony.JSONP | Protocol | JSON with Padding (JSONP) protocol |
| Harmony.AUPAF | Source of Truth | The Australian Postal Address Source of Truth |
| Harmony.AUSOTS | Source of Truth | The combined Australian Source of Truth |
| Harmony.GNAF | Source of Truth | The Australian Geo-coded Address Source of Truth |
| Harmony.NZPAF | Source of Truth | The New Zealand Postal Address Source of Truth |
| Harmony.NZAD | Source of Truth | It is a snapshot of addresses (at the time of the extract) that contains all addresses in New Zealand Post's National Postal Address Database (NPAD) |
| Harmony.ERROR | Status | The error status |
| Harmony.SUCCESS | Status | The success status |
### Methods[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
| Name | Description | Since |
| ------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
| [Harmony.v2.find](https://developer.mastersoftgroup.com/harmony/client/js/api.html#v2Find) | Finds a list of international addresses based on the input address and country information | 1.8.0 |
| [Harmony.v2.retrieve](https://developer.mastersoftgroup.com/harmony/client/js/api.html#v2Retrieve) | Retrieves and provides additional data for an international address. | 1.8.0 |
| [Harmony.reverseGeocode](https://developer.mastersoftgroup.com/harmony/client/js/api.html#reverseGeocode) | Reverse geocode lookup for international addresses based on the input latitude and longitude. It has more options for Australia and New Zealand addresses. | 1.8.0 |
| [Harmony.init](https://developer.mastersoftgroup.com/harmony/client/js/api.html#init) | Initialises the client. | 1.0.0 |
| [Harmony.useEnv](https://developer.mastersoftgroup.com/harmony/client/js/api.html#useEnv) | Specify the environment to use. | 1.2.0 |
| [Harmony.useProtocol](https://developer.mastersoftgroup.com/harmony/client/js/api.html#useProtocol) | Specify the connection protocol to use. | 1.3.0 |
| [Harmony.useFeatureOptions](https://developer.mastersoftgroup.com/harmony/client/js/api.html#useFeatureOptions) | Specify the feature options value to use. | 1.4.0 |
| [Harmony.Parse.address](https://developer.mastersoftgroup.com/harmony/client/js/api.html#parseAddress) | Parses a free-form address string. | 1.1.0 |
| [Harmony.International.reverseGeocode](https://developer.mastersoftgroup.com/harmony/client/js/api.html#internationalReverseGeocode) | International reverseGeocode lookup based on the input latitude and longitude. | 1.8.0 |
| [Harmony.International.getGeocode](https://developer.mastersoftgroup.com/harmony/client/js/api.html#internationalGetGeocode) | Retrieves and provides geocode information for international addresses. | 1.8.0 |
| [Harmony.Validate.email](https://developer.mastersoftgroup.com/harmony/client/js/api.html#validateEmail) | Validates an email address. | 1.2.0 |
| [Harmony.Validate.phone](https://developer.mastersoftgroup.com/harmony/client/js/api.html#validatePhone) | Validates a mobile phone number. | 1.2.0 |
| [Harmony.Company.abn](https://developer.mastersoftgroup.com/harmony/client/js/api.html#abn) | Look up ABN. | 1.6.0 |
### Harmony.v2.find(address, sourceOfTruth, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [find](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraFind) service.
#### address
Type: AddressThe input Address object.
#### sourceOfTruth
Type: StringThe Source of Truth to use for overriding default SOT for Australia or New Zealand address lookup. It is Optional.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example performs a single-line address search for '1 abc street' in Canada:
```
Harmony.v2.find({ fullAddress: "1 abc street", country: "CA"}, null,
function(response) {
if (response.status == Harmony.SUCCESS) {
// Do something with the response payload.
for (var i = 0; i < response.payload.length; i++) {
var address = response.payload[i];
...
}
} else {
// Show any error messages.
for (var i = 0; i < response.messages.length; i++) {
alert(response.messages[i]);
...
}
}
}
);
```
### Harmony.v2.retrieve(address, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [retrieve](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraRetrieve) service.
#### address
Type: AddressThe input Address object.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example identifies the input address with id of the address from the above find API.
```
Harmony.v2.retrieve({ id: "xx|xx|xxx"},
function(response) {
if (response.status == Harmony.SUCCESS) {
// Do something with the response payload.
var result = response.payload[0];
...
} else {
// Show any error messages.
for (var i = 0; i < response.messages.length; i++) {
alert(response.messages[i]);
...
}
}
}
);
```
### Harmony.reverseGeocode(address, sourceOfTruth, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [combined reverseGeo](https://developer.mastersoftgroup.com/harmony/api/method/reverse-geocode.html#combined) service to get addresses with input latitude and longitude
#### address
Type: AddressThe input Address object.
#### sourceOfTruth
Type: StringIt is optional for Australia and New Zealand. If value is specified it will only reverse geocode lookup for this country only.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example performs a combined reverseGeocode lookup:
```
Harmony.reverseGeocode({"latitude": "xxx", "longitude": "xxx"}, null,
function(response) {
if (response.status == Harmony.SUCCESS) {
// Do something with the response payload.
for (var i = 0; i < response.payload.length; i++) {
var address = response.payload[i];
...
}
} else {
// Show any error messages.
for (var i = 0; i < response.messages.length; i++) {
alert(response.messages[i]);
...
}
}
}
);
```
### Harmony.init(username, password, locale)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Initialises the client.
#### username
Type: StringThe username used to connect to Harmony RightAddress.
#### password
Type: StringThe password used to connect to Harmony RightAddress.
#### locale
Type: StringThe locale used when connecting to Harmony RightAddress.
The following example initialises the Harmony client with the credentials 'bob'/'password' and the Australian locale:
```
Harmony.init("bob", "password", Harmony.AUSTRALIA);
```
### Harmony.useEnv(environment)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Specifies the non-production service environment to be used for the requests. The default environment is Production.
#### environment
Type: StringThe non-production service environment to use.
The following example configures the Harmony client to use the PREVIEW environment:
```
Harmony.useEnv(Harmony.ENV_PREVIEW);
```
### Harmony.useProtocol(protocol)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Specifies the protocol to be used for the service requests. The default protocol is Cross-Origin Resource Sharing (CORS).
#### protocol
Type: StringThe protocol to use.
The following example configures the Harmony client to use the JSONP protocol over GET requests:
```
Harmony.useProtocol(Harmony.JSONP);
```
### Harmony.useFeatureOptions(featureOptions)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Specifies the [FeatureOptions](https://developer.mastersoftgroup.com/harmony/api/object/address.html#FeatureOption) value when invoking the address lookup REST service methods.
#### featureOptions
Type: String or FeatureOptionThe option values when invoking the address lookup REST service methods. Only need to specify it if you want a different value from the default value.
The following example configures feature options for address lookup service methods:(Only need to specify the option value if want a different value from system default)
```
Harmony.useFeatureOptions({singleLineHitNumber:'10', displayGnafLot: 1,
exposeAttributes:'1', exposePhantom:'0'});
```
### Harmony.Parse.address(address, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [address](https://developer.mastersoftgroup.com/harmony/api/method/parse.html#address) parse service.
#### address
Type: String or AddressThe input address String or the input Address object. The Address object input only available for harmony.min.js since version 1.6.0.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example parses the input address '220 george street, sydney 2000' as a String:
```
Harmony.Parse.address("220 george street, sydney 2000",
function(response) {
// Perform any action with the response
...
}
);
```
The following example parses the input address '220 george street, sydney 2000' in an Address object (only available for harmony.min.js since version 1.6.0):
```
Harmony.Parse.address({ fullAddress: "220 george street, sydney 2000" },
function(response) {
// Perform any action with the response
...
}
);
```
### Harmony.International.reverseGeocode(address, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [international reverseGeo](https://developer.mastersoftgroup.com/harmony/api/method/reverse-geocode.html#international) service to get addresses with input latitude and longitude
#### address
Type: AddressThe input Address object.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example performs the international reverseGeocode lookup:
```
Harmony.reverseGeocode({"latitude": "xxx", "longitude": "xxx"},
function(response) {
if (response.status == Harmony.SUCCESS) {
// Do something with the response payload.
for (var i = 0; i < response.payload.length; i++) {
var address = response.payload[i];
...
}
} else {
// Show any error messages.
for (var i = 0; i < response.messages.length; i++) {
alert(response.messages[i]);
...
}
}
}
);
```
### Harmony.International.getGeocode(address, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [internationalGeocode](https://developer.mastersoftgroup.com/harmony/api/method/address.html#internationalGeocode) service.
#### address
Type: AddressThe input Address object.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example get geocode information for an Australia Address:
```
Harmony.International.getGeocode({"fullAddress":"28 station st E,Harris park nsw 2150", "country":"Australia"},
function(response) {
if (response.status == Harmony.SUCCESS) {
// Do something with the response payload.
var resultGeocode = response.payload[0];
...
} else {
// Show any error messages.
for (var i = 0; i < response.messages.length; i++) {
alert(response.messages[i]);
...
}
}
}
);
```
### Harmony.Validate.email(emailAddress, sourceOfTruth, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [email](https://developer.mastersoftgroup.com/harmony/api/method/validate.html#email) validate service.
#### emailAddress
Type: String or EmailAddressThe input email address as a String or the input EmailAddress object. The EmailAddress object input only available for harmony.min.js since version 1.6.0.
#### sourceOfTruth
Type: StringThe Source of Truth to use for the validation - optional. The default Source of Truth is VE\_ALL.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example performs a validation on the email address '' as a String in VE\_ALL Source of Truth:
```
Harmony.Validate.email("bob@example.org", "VE_ALL",
function(response) {
// Perform any action with the response
...
}
);
```
The following example performs a validation on the email address '' in an EmailAddress object in VE\_ALL Source of Truth (only available for harmony.min.js since version 1.6.0.):
```
Harmony.Validate.email( {address: "bob@example.org" }, "VE_ALL",
function(response) {
// Perform any action with the response
...
}
);
```
### Harmony.Validate.phone(phone, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [phone](https://developer.mastersoftgroup.com/harmony/api/method/validate.html#phone) validate service.
#### phone
Type: PhoneThe input phone object containing a number and country code.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example performs a validation on the mobile phone number '0412341234' for Australia:
```
Harmony.Validate.phone({ fullPhone: "0412341234", country: "AU" },
function(response) {
// Perform any action with the response
...
}
);
```
### Harmony.Company.abn(company, apiName, optionalConfig, guid, callback)[\[Back to top\]](https://developer.mastersoftgroup.com/harmony/client/js/api.html#top)
Invokes the [Company Lookup/Validate](https://developer.mastersoftgroup.com/harmony/api/method/validate.html#auCompanyLookup) service. The following are the explanations of the parameters used. Please refer to [CompanyRestRequest](https://developer.mastersoftgroup.com/harmony/api/object/validate.html#CompanyRestRequest) for more details.
#### company
Type: StringThe input company name for lookup/validation
#### apiName
Type: StringThe name of the API used for lookup, for example "SearchByABNv201408", "SearchByASICv201408", and etc.
#### optionalConfig
Type: StringThe optional configuration
#### guid
Type: StringYou only need to specify this value if you want to use your own guid, otherwise, use null or empty string as the value.
#### callback
Type: FunctionThe function that will be invoked when the service response is received.
The following example performs a lookup on the company name 'mastersoft':
```
Harmony.Company.abn("mastersoft", "", "", "",
function(response) {
// Perform any action with the response
...
}
);
```
# Deprecated JQuery Library v1.8.1
The UI client uses jQuery and jQuery UI to create 'auto-complete' fields that invoke the Harmony API service methods.
{% hint style="warning" %}
**We recommend** [Harmony API JavaScript client version 2.0.0](/loqate-harmony-api/integrations/client-libraries/javascript-library-v2.7.0)+, a lightweight vanilla address auto-complete implementation is already included without the dependency on jQuery and jQuery UI.
{% endhint %}
### Pre-requisites
Before you can use the Harmony API client, you must make sure you have:
* An active Harmony API account
* A Harmony API username and password for your domain
### Getting the client
The versions of the JavaScript UI client can be downloaded using the following links:
* [harmony-ui-1.8.1.min.js](http://common.mastersoftgroup.com/scripts/harmony-ui-1.8.1.min.js)
* For any earlier versions of client please contact us.
### Configuring the client dependencies
The UI client is dependent on the following JavaScript libraries:
* [jQuery](http://jquery.com/) 3.5.1+
* [jQuery UI](http://jqueryui.com/) 1.12.1+
* [Harmony RightAddress JavaScript Client](https://developer.mastersoftgroup.com/harmony/client/js) 1.8.1+
These dependencies should be included on the web page before the UI client. In the following example, the three JavaScript files have been downloaded to the 'scripts' folder in the root of the website.
```
```
### Initialising the client
Before making service requests, the client must be initialised. This is done by invoking the `init` method on the global `Harmony` object.
```
Harmony.init({String} username, {String} password, {String} locale);
```
This method must be called before any other methods are invoked on the `Harmony` object.
```
```
### Creating a single-line international address lookup with v2 APIs
Once the Harmony API client has been initialised, lookup fields can be created using the global `Harmony.UI` object.
The following example creates a international single-line address lookup on a text input with the id 'address' and 'country'.
```
```
### Specifying output fields
As well as performing address lookups, the UI client can output additional fields from the lookups performed. This is done by adding fields using the global `Harmony.UI` object.
The following example configures a single-line address lookup which then outputs the component parts of the resulting address to separate fields on the page.
```
```
The following example configures two single-line address lookups which then outputs the component parts of the resulting address to separate fields on the page.
```
```
When an address is selected from the lookup, the postcode, locality and street fields will automatically be populated with the corresponding values from the selected address.
### Additional information
See the [Harmony RightAddress JavaScript UI client API](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html) documentation for details on configuring the other lookup components.
## Extending Library for JQuery
The UI client library acts as a further abstraction wrapper for the [Harmony RightAddress JavaScript client](https://developer.mastersoftgroup.com/harmony/client/js). As with the Harmony API JavaScript client, the objects used by the library are JavaScript representations of those found in the [Harmony RightAddress service API](https://developer.mastersoftgroup.com/harmony/api/).
**It is recommended to use the current Javascript UI Client Address lookup methods.** However [the previous version of JavaScript UI Client Address lookup methods](https://developer.mastersoftgroup.com/harmony/client/jsui/v1/api.html) are still available.
### Constants
| Name | Type | Description |
| ------------------ | --------- | ------------------------------------------------------------------------------------ |
| Harmony.UI.LOADING | CSS class | The CSS class added to the `input` element during the service method invocation. |
| Harmony.UI.OUTPUT | Field | The field used to output any errors that occur during the service method invocation. |
### Methods
| Name | Description |
| ------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------- |
| [Harmony.UI.addField](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html#addField) | Adds a new field specifying the field name (e.g. `Harmony.POSTCODE`, `Harmony.LOCALITY`, etc) and the input element. |
| [Harmony.UI.addressLookupV2](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html#addressLookupV2) | Single-line address lookup version 2 for international address lookup on the supplied `input` element. |
| [Harmony.UI.parseAddress](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html#parseAddress) | Parses the value retrieved from the `Harmony.ADDRESS` field and populates any other specified fields with the results. |
| [Harmony.UI.setOutputElement](https://developer.mastersoftgroup.com/harmony/client/jsui/api.html#setOutputElement) | Sets the element to use to display the Harmony UI output. |
### Harmony.UI.addField(field, element, index)
Adds a new field specifying the field name (e.g. `Harmony.POSTCODE`, `Harmony.LOCALITY`, etc) and the input element.
#### field
Type: StringThe name of the field to be added (e.g. `Harmony.POSTCODE`).
#### element
Type: ObjectThe `input` element to be assigned to the field (e.g. `document.getElementById("postcodeField"))`.
#### index
Type: IntegerThe optional index if there are multiple sets of lookups on the same page (e.g. one for residential addresses and the other one for postal addresses). Currently only available for `addressLookupV2`.
The following example assigns the `Harmony.LOCALITY` field to the input element with the ID `localityField`:
```
// Perform the assignment using standard JavaScript.
Harmony.UI.addField(Harmony.LOCALITY, document.getElementById("localityField"));
// Perform the assignment using a jQuery selector.
Harmony.UI.addField(Harmony.LOCALITY, $("#localityField"));
/* Perform the assignment using a jQuery selector with index
for the second set address lookup. */
Harmony.UI.addField(Harmony.LOCALITY, $("#localityField"), 1);
```
### Harmony.UI.addressLookupV2(element, countryElement, sourceOfTruth, opts, index)
Creates international single-line address lookup with v2 APIs on the supplied `input` and `country` elements. It returns the response from [find](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraFind) service and the callback is available via `onSelect` option.
For [retrieve](https://developer.mastersoftgroup.com/harmony/api/method/address.html#hraRetrieve) service, the response is available via `ui.onRetrieveItem` and the callback is available via `onRetrieve` option. For [internationalGeocode](https://developer.mastersoftgroup.com/harmony/api/method/address.html#internationalGeocode) service, if `getIntlGeocode` options is enabled, the response is available via `ui.onIntlGeocodeItem` and the callback is available via `onIntlGeocode` option.
#### element
Type: ObjectThe `input` address element to create the lookup for (e.g. `document.getElementById("address")`).
#### countryElement
Type: ObjectThe `input` country element to create the lookup for (e.g. `document.getElementById("country")`).
#### sourceOfTruth
Type: StringThe Source of Truth to override the default Australia and New Zealand SOTs. It is optional.(e.g. `Harmony.AUPAF` for Australia).
#### opts
Type: ObjectOptional parameter to be passed into the [jQuery UI Autocomplete](http://jqueryui.com/autocomplete/) component (e.g. `getIntlGeocode` true/false to enable international geocode call for the selected address, default is false. And callback functions e.g. `onRetrieve` and `onIntlGeocode` in below sample).
#### index
Type: StringOptional index to indicate which set of fields to populate if there are multiple lookups.
The following example creates a single-line address lookup (use AUPAF for Australian addresses) on the input element with ID `singleLineAddress` and `country` and customized `opts`:
```
var opt = {
// min 3 chars to trigger the lookup
minLength:3,
// enable Harmony.International.getGeocode for non-AU/NZ countries when address selected.
getIntlGeocode:true,
//Override onSelect function if applicable. It is Optional
onSelect: function(event, ui) {
console.log('address selected: ' + JSON.stringify(ui.item));
},
//Override onIntlGeocode function if applicable. It is Optional
//e.g. get ui.onIntlGeocodeItem object for address payload after onIntlGeocode call.
onIntlGeocode: function(event, ui) {
console.log('geocode address selected: ' + JSON.stringify(ui.onIntlGeocodeItem));
},
//Override onRetrieve function if applicable. It is Optional
//e.g. get ui.onRetrieveItem object for address payload after onRetrieve call.
onRetrieve: function(event, ui) {
console.log('onRetrieve address selected: ' + JSON.stringify(ui.onRetrieveItem));
}
};
// Perform the assignment using a jQuery selector.
Harmony.UI.addressLookupV2($("#singleLineAddress"), $("#country"), Harmony.AUPAF, opt);
```
### Harmony.UI.parseAddress()
Parses the value entered in the `Harmony.ADDRESS` field and populates any other specified fields with the parse results.
The following example uses jQuery to assign a `click` event to a button with the ID `parseButton`, which then parses the value in the `address` input and outputs the generated address components into the `postcode`, `locality` and `street` inputs:
```
// Add the address field using jQuery selectors.
Harmony.addField($("#address"), Harmony.ADDRESS);
// Add the output fields using jQuery selectors.
Harmony.addField($("#postcode"), Harmony.POSTCODE);
Harmony.addField($("#locality"), Harmony.LOCALITY);
Harmony.addField($("#street"), Harmony.STREET);
// Use jQuery to generate the click event for the button.
$("#parseButton").click(function(event) {
// Perform the parse.
Harmony.UI.parseAddress();
});
```
### Harmony.UI.setOutputElement(element)
Sets the element to use to display the Harmony UI output.
#### element
Type: ObjectThe element (can be any type) in which to post the Harmony UI output (e.g. `document.getElementById("output")`).
The following example sets the output element to the element with the ID `outputDiv`:
```
// Perform the assignment using standard JavaScript.
Harmony.UI.setOutputElement(document.getElementById("outputDiv"));
// Perform the assignment using a jQuery selector.
Harmony.UI.setOutputElement($("#outputDiv"));
```
# Coverage
Regions of coverage used by our services.
Each service has different coverage characteristics. This section provides you with outline of coverage for each service
### **Address Lookup & Validation**
Coverage for API Services Global Address Data.
Best in class Datasets for Australia, New Zealand and much of the Globe.
**Australia:** AUPAF, GNAF, AU Combined & Parcel Locker Plus
**New Zealand:** NZPAF, NZAD and CNAR
**See our global address data coverage here:**
{% embed url="" %}
### Address Cleanse
Address Cleanse coverage is Global Address Data.
Best in class Datasets for Australia, New Zealand and much of the Globe.
**Australia:** AUPAF, GNAF, AU Combined & Parcel Locker Plus
**New Zealand:** NZPAF, NZAD and CNAR
**See our global address data coverage here:**
{% embed url="" %}
### Reverse Geocoding / Address by Geocode
Coverage for API Services Global Address Data.
**See our global address data coverage here:**
{% embed url="" %}
### Geocodes
Coverage for Geocodes via API Services Global based on Address data using our INTL data.
### Address Parse
Address Parse is tuned to parse Australia and New Zealand addresses. It will work for Global address provided that the input address components are similar to that of Australia and New Zealand addresses.
### Business Validation and Lookup
Business Lookup and Validation has coverage for Australia and New Zealand businesses, companies, sole traders and partnerships registered as business entities within these regions.
### Business Cleanse
Business Cleanse has coverage for Australia and New Zealand businesses, companies, sole traders and partnerships registered as business entities within these regions.
### Email Validation
Email validation is Global and run in real time to valid an email against its email server.
### Phone Validation
Phone validation is Global mobile coverage when submitted in ITU E.123 International format
*Examples: '+{country code} {number}'*
*+22 607 123 4567*
*+61 412 123 456*
COUNTRY
CC ISO
Country Code
Network Carriers
Abkhazia
AB
+7
1
Afghanistan
AF
+93
1
Albania
AL
+355
2
American Samoa
AS
+1684
1
Angola
AO
+244
1
Anguilla
AI
+1264
1
Antigua and Barbuda
AG
+1268
2
Armenia
AM
+374
2
Aruba
AW
+297
2
Australia
AU
+61
4
Austria
AT
+43
5
Bahamas
BS
+1242
1
Bahrain
BH
+973
3
Barbados
BB
+1246
1
Belarus
BY
+375
2
Belgium
BE
+32
9
Belize
BZ
+501
1
Bermuda
BM
+1441
2
Bhutan
BT
+975
2
Bosnia and Herzegovina
BA
+387
1
Botswana
BW
+267
1
British Indian Ocean Territory
IO
+246
1
Brunei Darussalam
BN
+673
2
Bulgaria
BG
+359
2
Burkina Faso
BF
+226
1
Burundi
BI
+257
1
Cabo Verde
CV
+238
1
Cambodia
KH
+855
2
Cameroon
CM
+237
1
Caribbean Netherlands
BQ
+599
3
Central African Republic
CF
+236
1
Chile
CL
+56
1
Congo
CG
+242
1
Congo (Democratic Republic)
CD
+243
2
Cook Islands
CK
+682
1
Costa Rica
CR
+506
1
Cote d'Ivoire
CI
+225
1
Croatia
HR
+385
2
Curacao
CW
+599
2
Cyprus
CY
+357
2
Czech Republic
CZ
+420
4
Denmark
DK
+45
48
Dominica
DM
+1767
1
El Salvador
SV
+503
2
Equatorial Guinea
GQ
+240
1
Estonia
EE
+372
3
Eswatini
SZ
+268
1
Falkland Islands
FK
+500
1
Faroe Islands
FO
+298
2
Finland
FI
+358
4
France
FR
+33
5
French Guiana
GF
+594
4
French Polynesia
PF
+689
3
Gabon
GA
+241
1
Gambia
GM
+220
3
Georgia
GE
+995
2
Germany
DE
+49
3
Ghana
GH
+233
1
Gibraltar
GI
+350
1
Greece
GR
+30
3
Greenland
GL
+299
1
Grenada
GD
+1473
1
Guadeloupe
GP
+590
6
Guam
GU
+1
1
Guernsey
GG
+44
2
Guinea-Bissau
GW
+245
1
Guyana
GY
+592
2
Hong Kong
HK
+852
6
Hungary
HU
+36
2
Iceland
IS
+354
2
India
IN
+91
115
Indonesia
ID
+62
1
Ireland
IE
+353
6
Isle of Man
IM
+44
3
Israel
IL
+972
6
Jersey
JE
+44
3
Kazakhstan
KZ
+7
2
Kenya
KE
+254
3
Kiribati
KI
+686
1
Kuwait
KW
+965
3
Latvia
LV
+371
4
Lebanon
LB
+961
1
Lesotho
LS
+266
2
Libya
LY
+218
1
Liechtenstein
LI
+423
3
Lithuania
LT
+370
3
Luxembourg
LU
+352
3
Macao
MO
+853
4
Malawi
MW
+265
1
Malaysia
MY
+60
8
Maldives
MV
+960
1
Malta
MT
+356
3
Martinique
MQ
+596
2
Mauritania
MR
+222
1
Mauritius
MU
+230
1
Mexico
MX
+52
1
Moldova
MD
+373
2
Mongolia
MN
+976
1
Montenegro
ME
+382
2
Morocco
MA
+212
2
Mozambique
MZ
+258
1
Myanmar
MM
+95
1
Namibia
NA
+264
1
Nauru
NR
+674
1
Netherlands
NL
+31
9
New Caledonia
NC
+687
1
New Zealand
NZ
+64
1
North Macedonia
MK
+389
2
Northern Cyprus
KK
+90
2
Norway
NO
+47
6
Oman
OM
+968
2
Panama
PA
+507
2
Paraguay
PY
+595
3
Philippines
PH
+63
1
Poland
PL
+48
7
Portugal
PT
+351
6
Qatar
QA
+974
1
Reunion
RE
+262
2
Romania
RO
+40
4
Russian Federation
RU
+7
6
Rwanda
RW
+250
1
Saint Kitts and Nevis
KN
+1869
2
Saint Lucia
LC
+1758
1
Saint Vincent and The Grenadines
VC
+1784
1
Samoa
WS
+685
2
Sao Tome and Principe
ST
+239
1
Saudi Arabia
SA
+966
1
Senegal
SN
+221
1
Serbia
RS
+381
2
Seychelles
SC
+248
2
Sierra Leone
SL
+232
2
Singapore
SG
+65
2
Sint Maarten
SX
+1721
2
Slovakia
SK
+421
2
Slovenia
SI
+386
2
Solomon Islands
SB
+677
1
Somalia
SO
+252
2
South Africa
ZA
+27
1
South Sudan
SS
+211
1
Spain
ES
+34
31
Sri Lanka
LK
+94
2
Sudan
SD
+249
1
Suriname
SR
+597
1
Sweden
SE
+46
73
Switzerland
CH
+41
1
Taiwan
TW
+886
4
Tajikistan
TJ
+992
2
Tanzania
TZ
+255
3
Thailand
TH
+66
3
Timor-Leste
TL
+670
1
Togo
TG
+228
1
Tonga
TO
+676
2
Trinidad and Tobago
TT
+1868
2
Turkey
TR
+90
3
Turkmenistan
TM
+993
1
Turks and Caicos Islands
TC
+1649
1
Uganda
UG
+256
1
Ukraine
UA
+380
2
United Arab Emirates
AE
+971
2
United Kingdom
GB
+44
14
Uzbekistan
UZ
+998
3
Venezuela
VE
+58
1
Virgin Islands (British)
VG
+1284
1
### NZ property title
NZ property title is New Zealand only.
### Suppressions
Suppressions are Australia only.
# Address Exchange (Beta)
\`
{% content-ref url="/pages/A65CbVBE7sSaUbk02GZM" %}
[ADX Console](/loqate-harmony-api/address-exchange-beta/adx-console)
{% endcontent-ref %}
{% content-ref url="/pages/FyKAW2d6EYtfxz0SwpQH" %}
[ADX API Specification](/loqate-harmony-api/address-exchange-beta/adx-api-specification)
{% endcontent-ref %}
{% content-ref url="/pages/VsHuo2U91WLZNQXEQaay" %}
[Reserved Attributes](/loqate-harmony-api/address-exchange-beta/reserved-attributes)
{% endcontent-ref %}
# ADX Console
Address Exchange for Console Service Users
Using the console to use Address Exchange is often the first place to start.
**Before you start:**
You need to be a registered user of Address Exchange:
1. You will need an account.
2. You will need to Address Exchange permissions on your account.
3. Individual users will need to be 'console users'. If you need a console user please contact us.
The console use is allow users to conduct the features of searching and monitoring addresses, creating addresses and creating actions
{% content-ref url="/pages/q5eUXmWNiSRXJ3LpORyV" %}
[Create Address in console](/loqate-harmony-api/address-exchange-beta/adx-console/create-address-in-console)
{% endcontent-ref %}
{% content-ref url="/pages/zmLqoUAS25bmKnWjVFK3" %}
[Create Actions in console](/loqate-harmony-api/address-exchange-beta/adx-console/create-actions-in-console)
{% endcontent-ref %}
# Searching Addresses in console
Search and understand the history of address in Address Exchange
## 1. Search for an address
Use the search bar to find addresses within address exchange and click on the result
## 2. Understanding actions and events recorded
This gives you the key information recorded on the address (Address Fields, Geocodes, Attributes and All Actions) recorded.
Reviewing these actions helps understand the interactions that have occurred to that address.
It's important that you [contribute your actions ](/loqate-harmony-api/address-exchange-beta/adx-console/create-actions-in-console)as these helps build up confidence in a particular address.
# Create Address in console
Console creating address in address exchange
This is a two step process of ensuring the address is not already in the exchange and then creating an address if it doesn't exist.
**Before any address is created its important to check that the address does not already exist.**
It is possible that an address exists but has not been 'accepted'. This could be due to many reasons and we recommend reviewing the previous actions and events to assist you in decision to use an address.
## 1. Click 'Add new address'
## 2. Check for the address
Important feature of Address Exchange contribution to a single address record. This helps grow the overall confidence of an address.
**Type in the full address and review potential candidates.**
## 3. Enter new address
Entering the full address in the top line then press proceed when you cannot find a matching address. This opens the form to allow you to enter in the address information.
You can then move the map to the right co-ordinates to update the Latitude or Longitude.
## 4. Submit for Review
Simply, submit the address for review. Now the address will be searchable and others can contribution events and knowledge to the confidence of the address
# Create Actions in console
Create events about about your interactions with a created address
## 1. Find the address
URL:
Find the address you want to create an actoionon and click on it.
## 2. Add New Action
Click the Add New Action button which display's the form to add an action.
**Action:** We defined many different action types available in the dropdown.
**Result:** Result can be 'Success' or 'Fail'. Depending on the Action this field may not appear.
**Description:** Is free text to describe any additional information that may be important.
**Once an action is added it cannot be edited via the console.**
# ADX API Specification
---
[Next Page](/llms-full.txt/1)