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.
It is recommended to use the current Address lookup methods. However the previous version of Address lookup methods is still available.
| find | Lookup addresses using a single-line input address and optional id. |
| retrieve | Retrieve an address using the address id. |
| internationalGeocode | Retrieve WGS84 geocode information for the supplied countries and addresses. |
Lookup addresses using a single-line input address. It supports all countries including Australia and New Zealand.
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/POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/find
The request body is an AddressRestRequest object:
country attribute is required. It supports AU, NZ, or ISO-2 or ISO-3 country.fullAddress attribute is requiredid attribute is optionalsourceOfTruth attribute is optional - for Australia and New Zealand only.
Default is AUPAF for Australia and NZAD for New Zealand.featureOptions attribute is optional.
It supports Feature Options such as groupAddresses,
singleLineHitNumber (default 20). Some Feature Options for Australia and New Zealand only such as
displayGnafLot, caseType, positionFilter.The response body is an AddressRestResponse object
Request 1: lookup addresses with AUPAF Source of Truth including group addresses.
{
"payload": [ { "country": "au", "fullAddress": "20 bond st, nsw" } ],
"sourceOfTruth": "AUPAF",
"featureOptions": { "groupAddresses": "1", "singleLineHitNumber": "3" }
}
Response of Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "G 20 Bond St, Sydney NSW 2000",
"attributes": {
"Type": "Floor",
"subdwellings": "4 Addresses"
},
"id": "AU|AUPAF|G3860"
},
{
"_type": "AddressIntlV2",
"fullAddress": "20 Bond St, Maroubra NSW 2035",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|48318069"
},
{
"_type": "AddressIntlV2",
"fullAddress": "20 Bond St, Mosman NSW 2088",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|79044392"
}
]
}
Request 2: lookup addresses with GNAF Source of Truth including group addresses.
{
"payload": [ { "country": "au", "fullAddress": "20 bond st, nsw" } ],
"sourceOfTruth": "GNAF",
"featureOptions": { "groupAddresses": "1", "caseType": "TITLE", "singleLineHitNumber": "3" }
}
Response of Request 2:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_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"
},
{
"_type": "AddressIntlV2",
"fullAddress": "20 Bond Lane, Ballina NSW 2478",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GANSW718881455"
}
]
}
Request 3: lookup addresses further for BuildingNumber Type record below with GNAF Source of Truth.
{
"payload": [
{
"country": "au",
"fullAddress": "20 bond st, nsw",
"id": "AU|GNAF|GANSW710271307"
}
],
"sourceOfTruth": "GNAF",
"featureOptions": { "caseType": "TITLE", "singleLineHitNumber": "3" }
}
Response of Request 3:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "L 1 20 Bond Street, Sydney NSW 2000",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GANSW717802735"
},
{
"_type": "AddressIntlV2",
"fullAddress": "L 2 20 Bond Street, Sydney NSW 2000",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GANSW717802749"
},
{
"_type": "AddressIntlV2",
"fullAddress": "L 3 20 Bond Street, Sydney NSW 2000",
"attributes": {
"Type": "Floor",
"subdwellings": "3 Addresses"
},
"id": "AU|GNAF|GANSW717802752"
}
]
}
Request 4: lookup addresses with NZAD Source of Truth.
{
"payload": [ { "country": "NZ", "fullAddress": "20 bond st, marton" } ],
"sourceOfTruth": "NZAD",
"featureOptions": { "singleLineHitNumber": "3" }
}
Response of Request 4:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "20 Bond Street, Marton 4710",
"attributes": {
"Type": "Address"
},
"id": "NZ|NZAD|1154036"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Flat 20 30 Bond Street, Marton 4710",
"attributes": {
"Type": "Address"
},
"id": "NZ|NZAD|1154050"
}
]
}
Request 5: lookup UK addresses including group addresses.
{
"payload": [ { "country": "GB", "fullAddress": "bond st" } ],
"featureOptions": { "groupAddresses": "1", "singleLineHitNumber": "3" }
}
Response of Request 5:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_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"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Bond Street",
"attributes": {
"Type": "Street",
"subdwellings": "Hockley, Birmingham, B19 3LB - 11 Addresses"
},
"id": "GB|RM|ENG|BIRMINGHAM-HOCKLEY--STREET-BOND"
}
]
}
Request 6: lookup UK addresses further for Street Type record below.
{
"payload": [
{
"country": "GB",
"fullAddress": "bond rd marton",
"id": "GB|RM|ENG|MANCHESTER---WAY-MANCUNIAN-ESTATE-BOND_STREET_INDUSTRIAL"
}
]
}
Response of Request 6:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "Unit 1-2, Bond Street Industrial Estate Mancunian Way Manchester, M12 6HW",
"attributes": {
"Type": "Address"
},
"id": "GB|RM|A|14405045"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Dirt Factory, Unit 5, Bond Street Industrial Estate Mancunian Way Manchester, M12 6HW",
"attributes": {
"Type": "Address"
},
"id": "GB|RM|A|53184843"
}
]
}
Retrieves an address for the supplied id.
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/retrieve
The request body is an AddressRestRequest object:
id attribute is requiredfeatureOptions attribute is optional - for Australia and New Zealand only.
It supports Feature Options such as exposeAttributes,
caseType, splitNzFloorLevel, displayGnafLot.The response body is an AddressRestResponse object.
Request 1: retrieve an Australia address from GNAF Source of Truth with displayGnafLot.
{
"payload": [
{"id": "AU|GNAF|GANSW705038278"}
],
"featureOptions": { "exposeAttributes": "1", "displayGnafLot": "1" }
}
Response of Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "ValidatedAddressAu",
"fullAddress": "Lot 78 168 Lot Stafford Drive, Kalaru NSW 2550",
"country": "Australia",
"postcode": "2550",
"street2": null,
"street": "Lot Stafford Drive",
"streetNumber": "168",
"postal": "",
"postalType": "",
"postalNumber": "",
"buildingName": "",
"subdwelling": "Lot 78",
"eid": null,
"lotNumber": "78",
"flatUnitNumber": "",
"flatUnitType": "",
"floorLevelNumber": "",
"floorLevelType": "",
"streetSuffix": "",
"streetType": "Drive",
"streetName": "Lot Stafford",
"attributes": {
"GNAFGroupPID": "Nsw2857737",
"GNAFPIDPosition": "Single",
"ParcelID": "78//dp870178",
"CountryIso2": "AU",
"GNAFReliability": "2",
"CountryIso3": "AUS",
"GNAFConfidence": "2",
"GNAFLocalityPID": "Nsw2074",
"Latitude": "-36.72255996",
"Longitude": "149.92348752",
"MeshblockId": "10075730000",
"GNAFPointPID": "Gansw705038278",
"GNAFPID": "Gansw705038278",
"GeocodeLevel": "7"
},
"id": "AU|GNAF|GANSW705038278",
"exception": null,
"state": "NSW",
"locality": "Kalaru"
}
]
}
Request 2: retrieve an New Zealand address from NZAD Source of Truth.
{
"payload": [
{"id": "NZ|NZAD|1154050"}
],
"featureOptions": { "exposeAttributes": "1", "caseType": "TITLE" }
}
Response of Request 2:
{
"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",
"regional_council_id": "8",
"Latitude": "-40.06211544305106",
"source": "Nzpost",
"Longitude": "175.3759317179828",
"MeshblockId": "1735001",
"address_line2": "Marton 4710",
"address_line1": "20/30 Bond Street",
"regional_council_name": "Manawatu-wanganui Region",
"ta_name": "Rangitikei District",
"XCoordinate": "1802635.01420514",
"ta_id": "38",
"YCoordinate": "5562643.58308705"
},
"id": "NZ|NZAD|1154050",
"rdNumber": null,
"deliveredTo": "Y",
"exception": null,
"townCity": "Marton",
"suburb": ""
}
]
}
Request 3: retrieve a United Kingdom address.
{
"payload": [
{"id": "GB|RM|A|14405045"}
]
}
Response of Request 3:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "Unit 1-2, Bond Street Industrial Estate, Mancunian Way, MANCHESTER, M12 6HW, UNITED KINGDOM",
"country": "United Kingdom",
"postcode": "M12 6HW",
"street2": "Bond Street Industrial Estate",
"street": "Mancunian Way",
"streetNumber": "",
"postal": "",
"postalType": "",
"postalNumber": null,
"buildingName": "Unit 1-2",
"subdwelling": "",
"attributes": {
"CountryIso2": "GB",
"CountryIso3": "GBR",
"DomesticId": "14405045",
"DataLevel": "Premise",
"ProvinceName": "Greater Manchester",
"Type": "Residential",
"Language": "ENG",
"SortingNumber1": "26145",
"LanguageAlternatives": "ENG",
"Barcode": "(M126HW1HF)",
"CountryIsoNumber": "826",
"Line1": "Unit 1-2",
"Line2": "Bond Street Industrial Estate",
"Line3": "Mancunian Way",
"AdminAreaName": "Manchester"
},
"id": "GB|RM|A|14405045",
"district": "",
"city": "Manchester",
"province": "Greater Manchester"
}
]
}
Retrieves WGS84 geocode information for the supplied addresses.
It supports all countries including Australia and New Zealand. HTTP POST supports multiple records in the request.
Note: for Australia and New Zealand, the geocode information is already available from retrieve method.
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/intl/address/geocode
The request body is an AddressRestRequest object:
country field is required. The name or ISO-2 or ISO-3 country code (case-insensitive).
Most country names will be recognised but the use of ISO country code is recommended.fullAddress attribute is required. It can also be a postal code or a place name.The response body is an AddressRestResponse object.
Request 1: international geocoding with multiple records different countries.
{
"payload":[
{ "fullAddress": "G/R, 282 Hardgate Aberdeen, AB10 6AA", "country": "GB" },
{ "fullAddress": "13 Westdyke Terrace, Elrick, WESTHILL, AB32 6JA", "country": "United Kingdom" },
{ "fullAddress": "BASF SE / WERK 1051,CARL-BOSCH-STR. 38", "country": "Germany" },
{ "fullAddress": "1340 E 6th St Ste 628 Los Angeles CA 90021", "country": "US" },
{ "fullAddress": "12770 RUE BRAULT MIRABEL, QUEBEC J7J", "country": "CA" },
{ "fullAddress": "28 station st e,harris park nsw 2150", "country": "AUS" }
]
}
Response of Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "Hardgate, Aberdeen",
"country": "GB",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "57.1356",
"Longitude": "-2.1143"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "Westdyke Terrace, Elrick, Westhill",
"country": "United Kingdom",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "57.1536",
"Longitude": "-2.3003"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "",
"country": "Germany",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "47.80504",
"Longitude": "10.99786"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "1340 East 6th Street, Los Angeles, CA 90021",
"country": "US",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "34.03756",
"Longitude": "-118.23411"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "12770 Rue Brault, Mirabel QC J7J 0W3",
"country": "CA",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "45.69312",
"Longitude": "-73.92453"
},
"id": null,
"district": null,
"city": null,
"province": null
},
{
"_type": "AddressIntl",
"fullAddress": "28 Station Street East, Harris Park, Sydney, New South Wales, 2150",
"country": "AUS",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "-33.82135",
"Longitude": "151.00834"
},
"id": null,
"district": null,
"city": null,
"province": null
}
]
}
Request 2: request with some invalid records - the second and the fourth records in below request have
invalid country values.
{
"payload":[
{ "fullAddress": "G/R, 282 Hardgate Aberdeen, AB10 6AA", "country":"GB" },
{ "fullAddress": "13 Westdyke Terrace, Elrick, WESTHILL, AB32 6JA", "country":"United King" },
{ "fullAddress": "1340 E 6th St Ste 628 Los Angeles CA 90021", "country":"US" },
{ "fullAddress": "28 station st e,harris park nsw 2150", "country":"AUST" }
]
}
Response of Request 2: the invalid record returns null and the error message
is added in messages in processing order, for example the first message in messages
is the error message of the second record.
{
"status": "SUCCESS",
"messages": [
"Failed to get results from geocoding international geocode service",
"Failed to get results from geocoding international geocode service"
],
"payload": [
{
"_type": "AddressIntl",
"fullAddress": "Hardgate, Aberdeen",
"country": "GB",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "57.1356",
"Longitude": "-2.1143"
},
"id": null,
"district": null,
"city": null,
"province": null
},
null,
{
"_type": "AddressIntl",
"fullAddress": "1340 East 6th Street, Los Angeles, CA 90021",
"country": "US",
"postcode": null,
"street2": null,
"street": null,
"streetNumber": null,
"postal": null,
"postalType": null,
"postalNumber": null,
"buildingName": null,
"subdwelling": null,
"attributes": {
"Latitude": "34.03756",
"Longitude": "-118.23411"
},
"id": null,
"district": null,
"city": null,
"province": null
},
null
]
}