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.
The API Specification, also available on each method below - it requires valid username and password.
| address | Lookup addresses using a single-line input address. |
| buildingName | Lookup building names. |
| locality (AU only) | Lookup Australian localities. |
| postal | Lookup postal addresses (such as PO Boxes). |
| postcode | Lookup postcodes. |
| street | Lookup streets. |
| streetNumber | Lookup street numbers. |
| subdwelling | Lookup subdwellings. |
| subdwellingAddress | List all subdwellings under a given address. |
| suburb (NZ only) | Lookup suburbs. |
| townCity (NZ only) | Lookup towns/cities in New Zealand. |
| auNzReverseGeocode | Lookup addresses within a certain distance using geocode input - for Australia and New Zealand. |
| transaction | Indicate that an address lookup transaction has been completed. |
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
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/address
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/address
The request body is an AddressRestRequest object:
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"
}
fullAddress attribute is requiredsourceOfTruth attribute is requiredlocality attribute is optionalpostcode attribute is optionalstate attribute is optionaltransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
}
]
}
Performs a search for building names using the supplied buildingName.
Additional information supplied in the request will further filter the results.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/buildingName
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/buildingName
The request body is an AddressRestRequest object:
buildingName attribute is requiredpostcode attribute is optionallocality attribute is optionaltownCity attribute is optional (New Zealand)suburb attribute is optional (New Zealand)street attribute is optionalstreetNumber attribute is optionalfeatureOptions attribute is optional
{
"payload": [ { "buildingName": "anz" } ],
"sourceOfTruth": "AUPAF"
}
buildingName attribute is requiredsourceOfTruth attribute is requiredpostcode attribute is optionallocality attribute is optionaltransactionID attribute is optionalThe response body is an 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"
},
...
]
}
Performs an Australian locality search using the supplied information.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/locality
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/locality
The request body is an AddressRestRequest object:
locality attribute is required for non-semi locality searchpostcode attribute is optionalfullAddress attribute is required for semi locality search
{
"payload": [ { "locality": "SYD" } ],
"sourceOfTruth": "AUPAF"
}
For Semi structure locality search:
{
"payload": [ { "fullAddress":"SYDNEY 2000"} ],
"sourceOfTruth": "AUPAF"
}
sourceOfTruth attribute is requiredlocality attribute is required for non-semi locality searchpostcode attribute is optionalfullAddress attribute is required for semi locality searchtransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
},
...
]
}
Performs a search for a postal address using the supplied information.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postal
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postal
The request body is an AddressRestRequest object:
postal is requiredpostcode or locality attribute is required
{
"payload": [ { "postcode": "2000", "postal": "Locked Bag 1" } ],
"sourceOfTruth": "AUPAF"
}
sourceOfTruth attribute is requiredpostal is requiredpostcode or locality attribute is requiredtransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
},
...
]
}
Performs a postcode search using the supplied information.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postcode
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postcode
The request body is an AddressRestRequest object:
postcode attribute is required
{
"payload": [ { "postcode": "3000" } ],
"sourceOfTruth": "AUPAF"
}
sourceOfTruth attribute is requiredpostcode attribute is requiredtransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
},
...
]
}
Performs a street search using the supplied information.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/street
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/street
The request body is an AddressRestRequest object:
street attribute is requiredpostcode attribute is optionallocality attribute is optionaltownCity attribute is optional (New Zealand)suburb attribute is optional (New Zealand)
{
"payload": [ { "street": "GEORGE" } ],
"sourceOfTruth": "AUPAF"
}
sourceOfTruth attribute is requiredstreet attribute is requiredpostcode attribute is optionallocality attribute is optionaltransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
},
...
]
}
Performs a street number search using the supplied information.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/streetNumber
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/streetNumber
The request body is an AddressRestRequest object:
streetNumber attribute is requiredpostcode attribute is requiredlocality attribute is requiredtownCity attribute is optional (New Zealand)suburb attribute is optional (New Zealand)street attribute is required
{
"payload": [
{
"postcode": "2000",
"locality": "SYDNEY",
"street": "GEORGE",
"streetNumber": "220"
}
],
"sourceOfTruth": "AUPAF"
}
sourceOfTruth attribute is requiredstreetNumber attribute is requiredpostcode attribute is requiredlocality attribute is requiredstreet attribute is requiredtransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
}
]
}
Performs a subdwelling search using the supplied information.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwelling
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwelling
The request body is an AddressRestRequest object:
subdwelling attribute is requiredpostcode attribute is optionallocality attribute is optionaltownCity attribute is optional (New Zealand)suburb attribute is optional (New Zealand)street attribute is optionalstreetNumber attribute is optional
{
"payload": [
{
"postcode": "2000",
"locality": "SYDNEY",
"street": "GEORGE",
"streetNumber": "220",
"subdwelling": "202"
}
],
"sourceOfTruth": "AUPAF"
}
sourceOfTruth attribute is requiredsubdwelling attribute is requiredpostcode attribute is requiredlocality attribute is requiredstreet attribute is requiredstreetNumber attribute is requiredtransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
}
]
}
List all subdwellings under a given address.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwellingAddress
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwellingAddress
The request body is an AddressRestRequest object:
id attribute is required
{
"payload": [
{
"id":"59676232"
}
],
"sourceOfTruth": "AUPAF"
}
sourceOfTruth attribute is requiredid attribute is requiredfeatureOptions attribute is optionalThe response body is an 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 "
}
]
}
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.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/suburb
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/suburb
The request body is an AddressRestRequest object:
suburb attribute is requiredpostcode attribute is optionaltownCity attribute is optional
{
"payload": [ { "suburb": "WELL" } ],
"sourceOfTruth": "NZPAF"
}
sourceOfTruth attribute is requiredsuburb attribute is requiredpostcode attribute is optionaltownCity attribute is optionaltransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
}
]
}
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.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/townCity
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/townCity
The request body is an AddressRestRequest object:
townCity attribute is requiredpostcode attribute is optional
{
"payload": [ { "townCity": "WELL" } ],
"sourceOfTruth": "NZPAF"
}
sourceOfTruth attribute is requiredtownCity attribute is requiredpostcode attribute is optionaltransactionID attribute is optionalfeatureOptions attribute is optionalThe response body is an 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"
},
...
]
}
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).
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/reverseGeocode
The request body is an AddressRestRequest object:
attributes with latitude and longitude is requiredsourceOfTruth is optional. The supported Source of Truths are GNAF, NZPAF, NZAD, CNAR
(default is GNAF for Australia and NZPAF for New Zealand).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"}
}
The response body is an 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"
},
...
]
}
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.
POST https://hosted.mastersoftgroup.com/harmony/rest/{locale}/transaction
GET https://hosted.mastersoftgroup.com/harmony/rest/{locale}/transaction
The request body is an AddressRestRequest object:
{
"sourceOfTruth": "AUPAF"
}
sourceOfTruth attribute is requiredThe response body is an AddressRestResponse object:
{
"status": "SUCCESS",
"messages": [],
"payload": null
}