Comment on page
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.
Supported Countries: All countries including Australia and New Zealand. See our global data coverage.
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
https://hosted.mastersoftgroup.com/harmony
/rest/v2/address/find
International addresses lookup using a single-line input address
post
https://hosted.mastersoftgroup.com/harmony
/rest/v2/address/find
International addresses lookup using a single-line input address
GET/POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/find
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, doorstop, both | 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 |
Our API is highly configurable for your use case. Contact us to help get guidance on optimal settings.
Request: 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:
{
"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 1: 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 1:
{
"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 1: lookup 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.
{
"payload": [ { "country": "au", "fullAddress": "twentie Lot 2" } ],
"sourceOfTruth": "GNAF",
"featureOptions": { "caseType": "TITLE", "singleLineHitNumber": "3","suppressLot":"1", "displayGnafLot":"1" }
}
Response of Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "Lot 2 Twentieth Street, Renmark SA 5341",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GASA_424216948"
},
{
"_type": "AddressIntlV2",
"fullAddress": "6 Twentieth Avenue, Brighton QLD 4017",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GAQLD162919174"
},
{
"_type": "AddressIntlV2",
"fullAddress": "8 Twentieth Avenue, Brighton QLD 4017",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GAQLD155074339"
}
]
}
n
Request 1: 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 1:
{
"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"
}
]
}
n
Request 1: lookup addresses with NZAD Source of Truth.
{
"payload": [ { "country": "NZ", "fullAddress": "20 bond st, marton" } ],
"sourceOfTruth": "NZAD",
"featureOptions": { "singleLineHitNumber": "3" }
}
Response of Request 1:
{
"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 1: lookup addresses with NZAD Source of Truth.
{
"payload": [ { "fullAddress": "10 LIVERPOOL", "country": "NZ"} ],
"sourceOfTruth": "CNAR",
"featureOptions":{"singleLineHitNumber":"3"}
}
Response of Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "10 LIVERPOOL STREET, PAPAKURA, AUCKLAND 2110",
"attributes": {
"Type": "Address"
},
"id": "NZ|CNAR|13433417"
},
{
"_type": "AddressIntlV2",
"fullAddress": "10 LIVERPOOL STREET, EPSOM, AUCKLAND 1023",
"attributes": {
"Type": "Address"
},
"id": "NZ|CNAR|13526909"
},
{
"_type": "AddressIntlV2",
"fullAddress": "10 LIVERPOOL STREET, DARGAVILLE 0310",
"attributes": {
"Type": "Address"
},
"id": "NZ|CNAR|10519716"
}
]
}
Request 1: lookup UK addresses including group addresses.
{
"payload": [ { "country": "GB", "fullAddress": "bond st" } ],
"featureOptions": { "groupAddresses": "1", "singleLineHitNumber": "3" }
}
Response of Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "Bond Street St. Helier Jersey JE2 3NP",
"attributes": {
"Type": "Container",
"subdwellings": " - 44 Addresses"
},
"id": "gb-rm|6GF2wIoBX8V_g8REAb7E"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Bond Street Hull HU1 3EY",
"attributes": {
"Type": "Container",
"subdwellings": " - 43 Addresses"
},
"id": "gb-rm|-GB1wIoBX8V_g8REXblr"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Bond Street Bristol BS2 9AW",
"attributes": {
"Type": "Container",
"subdwellings": " - 51 Addresses"
},
"id": "gb-rm|5lRswIoBX8V_g8RE_gPz"
}
]
}
Request 1: 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 1:
{
"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"
}
]
}
Request 1: lookup addresses with AUPAF and AUPOST Assets (All: Parcel Locker, Offices, Shops)
{
"payload": [ { "country": "AU", "fullAddress": "parcel 3000 " } ],
"sourceOfTruth": "AUPAF",
"featureOptions": { "moreSources": "AUPOST", "singleLineHitNumber": "5"}
}
Response of Request 1:
As AUPOST is listed as moreSource the Source of Truth addresses are prioritized.
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "U 3000 668 BOURKE ST, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|88745091"
},
{
"_type": "AddressIntlV2",
"fullAddress": "CARE PO, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|43777876"
},
{
"_type": "AddressIntlV2",
"fullAddress": "RSD 3000, DELORAINE TAS 7304",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|31144512"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Melbourne GPO Parcel Locker, 260 Elizabeth Street, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|51097582_UPL"
},
{
"_type": "AddressIntlV2",
"fullAddress": "360 Collins Street Parcel Locker, 360 Collins St, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|45897528_UPL"
}
]
}
Request 2: lookup addresses with AUPAF and AUPOST Assets (Filter specific Aupost assests using addressTypeFilter)
{
"payload": [ { "fullAddress": "Kingswood", "country": "AU","state":"NSW","postcode":"2747"} ],
"sourceOfTruth": "AUPAF",
"featureOptions":{"caseType":"UP","moreSources":"AUPOST","singleLineHitNumber":"8","addressTypeFilter":"rspb,cspb,-rp","strictFieldValidation":"1"}
}
Response of Request 2:
As AUPOST is listed as moreSource the Source of Truth addresses are prioritized.
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "1 CALLOW LANE, KINGSWOOD NSW 2747",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|82993174"
},
{
"_type": "AddressIntlV2",
"fullAddress": "2 CALLOW LANE, KINGSWOOD NSW 2747",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|96069249"
},
{
"_type": "AddressIntlV2",
"fullAddress": "12 RICHMOND RD, KINGSWOOD NSW 2747",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|94959954"
},
{
"_type": "AddressIntlV2",
"fullAddress": "16 RICHMOND RD, KINGSWOOD NSW 2747",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPAF|49041044"
},
{
"_type": "AddressIntlV2",
"fullAddress": "RED STREET POSTING BOX, 2 RICHMOND ROAD, KINGSWOOD NSW 2747",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|RED0005682"
},
{
"_type": "AddressIntlV2",
"fullAddress": "COMBINED STREET POSTING BOX, 9 BRINGELLY ROAD, KINGSWOOD NSW 2747",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|RED0005670"
},
{
"_type": "AddressIntlV2",
"fullAddress": "RED STREET POSTING BOX, 61 DERBY STREEET, KINGSWOOD NSW 2747",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|RED0005680"
},
{
"_type": "AddressIntlV2",
"fullAddress": "RED STREET POSTING BOX, 42 BRINGELLY ROAD, KINGSWOOD NSW 2747",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|RED0005671"
}
]
}
Using the
id
you can call retrieve function see Retrieve AustPost AssetYou can apply filters depending on AustPost Asset (see addressTypeFilter). See Request 2 in this section
Request 1: lookup addresses with AUPOST Assets (All: Parcel Locker, Offices, Shops).
{
"payload": [ { "country": "AU", "fullAddress": "parcel 3000 " } ],
"sourceOfTruth": "AUPOST",
"featureOptions": {"singleLineHitNumber": "5"}
}
Response of Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "Melbourne GPO Parcel Locker, 260 Elizabeth Street, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|51097582_UPL"
},
{
"_type": "AddressIntlV2",
"fullAddress": "360 Collins Street Parcel Locker, 360 Collins St, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|45897528_UPL"
},
{
"_type": "AddressIntlV2",
"fullAddress": "452 Flinders Street Parcel Locker, 452 Flinders Street, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|35165839_UPL"
},
{
"_type": "AddressIntlV2",
"fullAddress": "RMIT Library Parcel Locker, 124 La Trobe Street, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|70135061_UPL"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Melbourne Bourke Street Parcel Locker, 15 Southern Cross Lane, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|95803441_UPL"
}
]
}
Using the
id
you can call retrieve function see Retrieve AustPost AssetRequest 2: lookup addresses with AUPOST Assets filtering only Parcel Lockers
{
"payload": [ { "country": "AU", "fullAddress": "3000 " } ],
"sourceOfTruth": "AUPOST",
"featureOptions": {"singleLineHitNumber": "3","addressTypeFilter":"UPL"}
}
Response of Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "Melbourne GPO Box Room Parcel Locker, 380 Bourke St, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|77153239_UPL"
},
{
"_type": "AddressIntlV2",
"fullAddress": "360 Collins Street Parcel Locker, 360 Collins St, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|45897528_UPL"
},
{
"_type": "AddressIntlV2",
"fullAddress": "452 Flinders Street Parcel Locker, 452 Flinders Street, MELBOURNE VIC 3000",
"attributes": {
"Type": "Address"
},
"id": "AU|AUPOST|35165839_UPL"
}
]
}
Request 1: lookup addresses with derived sub-premises enabled.
{
"payload": [ { "fullAddress": "Unit 888 100 john", "country": "AU"} ],
"sourceOfTruth": "GNAF",
"featureOptions":{"userInferred":"1","singleLineHitNumber":"3", "suppressLot":"1", "displayGnafLot":"1"}
}
Response to Request 1:
{
"status": "SUCCESS",
"messages": [],
"payload": [
{
"_type": "AddressIntlV2",
"fullAddress": "Unit 888 100 St Johns Road, Cabramatta NSW 2166",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GANSW704282071|Unit 888"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Unit 1 100 Johnston Street, Newport VIC 3015",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GAVIC411988613"
},
{
"_type": "AddressIntlV2",
"fullAddress": "Unit 2 100 Johnston Street, Newport VIC 3015",
"attributes": {
"Type": "Address"
},
"id": "AU|GNAF|GAVIC411989640"
}
]
}
Request 1: lookup addresses with AU & NZ within one search
{
"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.
{
"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"