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.
Find - Returns a list of valid addresses based on partial or complete address information.
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.
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.
groupAddresses:1;exposeAttributes:1GET /harmony/rest/v2/address/find HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Accept: */*
OK
{
"status": "SUCCESS",
"messages": [
"text"
],
"payload": {
"sourceReduced": true,
"empty": true,
"first": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
},
"last": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
}
}
}The get international geocode request body:
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'.fullAddress: the location to geocode. This can be a postal code or place name. Example: '13 Westdyke Terrace, Elrick, WESTHILL, AB32 6JA'.
POST /harmony/rest/v2/address/find HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 1273
{
"payload": {
"sourceReduced": true,
"empty": true,
"first": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
},
"last": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
}
},
"sourceOfTruth": "AUPAF",
"featureOptions": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"transactionID": "text"
}OK
{
"status": "SUCCESS",
"messages": [
"text"
],
"payload": {
"sourceReduced": true,
"empty": true,
"first": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
},
"last": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
}
}
}Resource
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/findRequest
The request body is an AddressRestRequest object.
We have a large amount of use case based performance tuning that can be done.
*=required field
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.
addressTypeFilter
string
urban, box, bag, rural, counter, cmb urban, cmb rural, upl, lpo, cpa, rp, ra, rspb, cspb
Default all
Array of filters to be applied to the lookup results. Used to control which addresses you have in your serviceable network.
exposePhantom
string
("0"|"1") default 0
Determines whether to expose phantom addresses for AUPAF. If the flag is set to "1", it will expose phantom address.
baseSource
string
"GNAF" |"AUPAF" default "GNAF"
Used when SourceOfTruth is AUSOTS. Specifies which data source is used as the base for the search result.
prioritizedSort
string
("0"|"1") default 1
Sorts locality information based on popularity of addresses.
splitNzFloorLevel
string
("0"|"1") default 0
Used when SourceOfTruth is NZPAF.
When "1", the floor information will be splitted into "floorLevelType" and "floorLevelNumber".
userInferred
string
("0"|"1") default 0
Takes user input relating to subdwellings and inferrers this into the find results. See our guide.
Response
The response body is an AddressRestResponse object.
See Address Field Mapping Guide for integration best practices.
Examples
Our API is highly configurable for your use case. Contact us to help get guidance on optimal settings.
Retrieve
Retrieves validated address for the supplied idusing the Find method.
groupAddresses:1;exposeAttributes:1GET /harmony/rest/v2/address/retrieve HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Accept: */*
OK
{
"status": "SUCCESS",
"messages": [
"text"
],
"payload": {
"sourceReduced": true,
"empty": true,
"first": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
},
"last": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
}
}
}The get international geocode request body:
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'.fullAddress: the location to geocode. This can be a postal code or place name. Example: '13 Westdyke Terrace, Elrick, WESTHILL, AB32 6JA'.
POST /harmony/rest/v2/address/retrieve HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 1273
{
"payload": {
"sourceReduced": true,
"empty": true,
"first": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
},
"last": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
}
},
"sourceOfTruth": "AUPAF",
"featureOptions": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"transactionID": "text"
}OK
{
"status": "SUCCESS",
"messages": [
"text"
],
"payload": {
"sourceReduced": true,
"empty": true,
"first": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
},
"last": {
"fullAddress": "text",
"country": "text",
"postcode": "text",
"subLocality": "text",
"street2": "text",
"street": "text",
"streetNumber": "text",
"postal": "text",
"postalType": "text",
"postalNumber": "text",
"buildingName": "text",
"subdwelling": "text",
"eid": "text",
"lotNumber": "text",
"flatUnitNumber": "text",
"flatUnitType": "text",
"floorLevelNumber": "text",
"floorLevelType": "text",
"streetSuffix": "text",
"streetType": "text",
"streetName": "text",
"attributes": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"id": "text",
"sourceOfTruth": "text",
"_type": "text",
"locality": "text",
"state": "text"
}
}
}Resource
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/retrieveRequest
The request body is an AddressRestRequest object:
*=required field
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 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.) Depending on country and dataset the response packages do change particularly in available attributes.
Last updated