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 - Returns a list of valid addresses based on partial or complete address information.

2. 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.

Looking for Address by Geocode or Reverse Geocoding? Click here

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.

International addresses lookup using a single-line input address

GET//hosted.mastersoftgroup.com/harmony/rest/v2/address/find

Authorization

rightaddress

Query parameters

Response

200401403404

OK

Body

application/json

messagesarray of string

payloadarray of Address

statusenum

SUCCESSERROR

Request

JavaScriptCurlPython

const response = await fetch('//hosted.mastersoftgroup.com/harmony/rest/v2/address/find?country=text&fullAddress=text', {
    method: 'GET',
    headers: {
      "Authorization": "basic <token>"
    },
});
const data = await response.json();

Response

200

{
  "messages": [
    "text"
  ],
  "payload": [
    {
      "buildingName": "text",
      "country": "text",
      "eid": "text",
      "flatUnitNumber": "text",
      "flatUnitType": "text",
      "floorLevelNumber": "text",
      "floorLevelType": "text",
      "fullAddress": "text",
      "id": "text",
      "lotNumber": "text",
      "postal": "text",
      "postalNumber": "text",
      "postalType": "text",
      "postcode": "text",
      "sourceOfTruth": "text",
      "street": "text",
      "street2": "text",
      "streetName": "text",
      "streetNumber": "text",
      "streetSuffix": "text",
      "streetType": "text",
      "subLocality": "text",
      "subdwelling": "text"
    }
  ],
  "status": "SUCCESS"
}

International addresses lookup using a single-line input address

POST//hosted.mastersoftgroup.com/harmony/rest/v2/address/find

Authorization

rightaddress

Body

application/json

addressRequest

featureOptionsobject

payloadarray of Address

sourceOfTruthenum

AUPAFGNAFAUSOTSAUPOSTNZPAFNZADCNARADDRESS_EXCHANGERIG_AURIG_NZSENDRIGHT_SOARIG_AU_IDRIG_NZ_IDRDAMDSASGSSEIFA2011VE_INTERNALVE_VERIFYVE_ALLCUSTOM_AU_1CUSTOM_AU_2CUSTOM_NZ_1CUSTOM_NZ_2

transactionIDstring

Response

200201401403404

OK

Body

application/json

messagesarray of string

payloadarray of Address

statusenum

SUCCESSERROR

Request

JavaScriptCurlPython

const response = await fetch('//hosted.mastersoftgroup.com/harmony/rest/v2/address/find', {
    method: 'POST',
    headers: {
      "Authorization": "basic <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "messages": [
    "text"
  ],
  "payload": [
    {
      "buildingName": "text",
      "country": "text",
      "eid": "text",
      "flatUnitNumber": "text",
      "flatUnitType": "text",
      "floorLevelNumber": "text",
      "floorLevelType": "text",
      "fullAddress": "text",
      "id": "text",
      "lotNumber": "text",
      "postal": "text",
      "postalNumber": "text",
      "postalType": "text",
      "postcode": "text",
      "sourceOfTruth": "text",
      "street": "text",
      "street2": "text",
      "streetName": "text",
      "streetNumber": "text",
      "streetSuffix": "text",
      "streetType": "text",
      "subLocality": "text",
      "subdwelling": "text"
    }
  ],
  "status": "SUCCESS"
}

Demo available here: https://www.loqate.com/anz/address-validation/****

Resource

GET/POST    https://hosted.mastersoftgroup.com/harmony/rest/v2/address/find

Request

The request body is an 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.
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.

Find AUPAF

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"
            }
        ]
    }

Find GNAF

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"
            }
        ]
    }

Find GNAF with Suppress Lot

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 =1is 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

Find sub-premises by using ID

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

Find NZAD

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"
            }
        ]
    }

Find CNAR

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"
        }
    ]
}

Find UK/INTL with Grouped addresses

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"
        }
    ]
}

Find UK/INTL with Street Type

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"
            }
        ]
    }

Find sourceOfTruth with AU Parcel Locker Plus

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 Asset

Find AU Parcel Locker Plus (Aust Post Assets)

You 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 Asset

Request 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"
        }
    ]
}

Find Derived Address

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"
        }
    ]
}

Using the id you can call retrieve function see Retrieve Derived Address

Find AU & NZ multi search

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": "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 idusing the Find method.

International addresses retrieve by id

GET//hosted.mastersoftgroup.com/harmony/rest/v2/address/retrieve

Authorization

rightaddress

Query parameters

Response

200401403404

OK

Body

application/json

messagesarray of string

payloadarray of Address

statusenum

SUCCESSERROR

Request

JavaScriptCurlPython

const response = await fetch('//hosted.mastersoftgroup.com/harmony/rest/v2/address/retrieve?id=text', {
    method: 'GET',
    headers: {
      "Authorization": "basic <token>"
    },
});
const data = await response.json();

Response

200

{
  "messages": [
    "text"
  ],
  "payload": [
    {
      "buildingName": "text",
      "country": "text",
      "eid": "text",
      "flatUnitNumber": "text",
      "flatUnitType": "text",
      "floorLevelNumber": "text",
      "floorLevelType": "text",
      "fullAddress": "text",
      "id": "text",
      "lotNumber": "text",
      "postal": "text",
      "postalNumber": "text",
      "postalType": "text",
      "postcode": "text",
      "sourceOfTruth": "text",
      "street": "text",
      "street2": "text",
      "streetName": "text",
      "streetNumber": "text",
      "streetSuffix": "text",
      "streetType": "text",
      "subLocality": "text",
      "subdwelling": "text"
    }
  ],
  "status": "SUCCESS"
}

International addresses retrieve by id

POST//hosted.mastersoftgroup.com/harmony/rest/v2/address/retrieve

Authorization

rightaddress

Body

application/json

addressRequest

featureOptionsobject

payloadarray of Address

sourceOfTruthenum

AUPAFGNAFAUSOTSAUPOSTNZPAFNZADCNARADDRESS_EXCHANGERIG_AURIG_NZSENDRIGHT_SOARIG_AU_IDRIG_NZ_IDRDAMDSASGSSEIFA2011VE_INTERNALVE_VERIFYVE_ALLCUSTOM_AU_1CUSTOM_AU_2CUSTOM_NZ_1CUSTOM_NZ_2

transactionIDstring

Response

200201401403404

OK

Body

application/json

messagesarray of string

payloadarray of Address

statusenum

SUCCESSERROR

Request

JavaScriptCurlPython

const response = await fetch('//hosted.mastersoftgroup.com/harmony/rest/v2/address/retrieve', {
    method: 'POST',
    headers: {
      "Authorization": "basic <token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

200

{
  "messages": [
    "text"
  ],
  "payload": [
    {
      "buildingName": "text",
      "country": "text",
      "eid": "text",
      "flatUnitNumber": "text",
      "flatUnitType": "text",
      "floorLevelNumber": "text",
      "floorLevelType": "text",
      "fullAddress": "text",
      "id": "text",
      "lotNumber": "text",
      "postal": "text",
      "postalNumber": "text",
      "postalType": "text",
      "postcode": "text",
      "sourceOfTruth": "text",
      "street": "text",
      "street2": "text",
      "streetName": "text",
      "streetNumber": "text",
      "streetSuffix": "text",
      "streetType": "text",
      "subLocality": "text",
      "subdwelling": "text"
    }
  ],
  "status": "SUCCESS"
}

Resource

    GET/POST    https://hosted.mastersoftgroup.com/harmony/rest/v2/address/retrieve

Request

The request body is an 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 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.

Retrieve validated: AUPAF

Request 1: Retrieve address AUPAF with Find ID

{
        "payload": [ { "id": "AU|AUPAF|48318069" } ],
        "featureOptions":{"exposeAttributes":"1","caseType":"title"}
}

Response to Request 1: Includes DPID, Barcode and Address mapping

{
    "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 =1is 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": [{"id": "AU|GNAF|GANSW705038278"}], 
        "featureOptions": { "exposeAttributes": "1", "suppressLot": "1","displayGnafLot":"1" }
    }

Response of Request 1:

{
    "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.

    {
        "payload": [{"id": "NZ|NZAD|1154050"}], 
        "featureOptions": { "exposeAttributes": "1", "caseType": "TITLE" }
    }

Response of Request 3:

    {
    "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.

{
        "payload": [{ "id": "NZ|CNAR|10519716" , "country": "NZ"}]
}

Response of Request 3:

{
    "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.

{
        "payload": [ { "id": "GB|RM|A|12799601|ENG" , "country": "GB"} ]
}

Response of Request 1:

{
    "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.

{
        "payload": [ { "id": "US|LP|B|113264667|100_ENG" , "country": "UK"} ]
}

Response of Request 1:

{
    "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

    {
        "payload": [ { "id": "AU|AUPOST|RED0010639" } ], 
        "featureOptions": { "exposeAttributes": "1"}
    }

Response to Request 1:

{
    "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.

{
        "payload": [ { "id": "AU|GNAF|GANSW704282071|Unit 888" } ],
        "featureOptions":{"exposeAttributes":"1","caseType":"title","suppressLot":"1", "displayGnafLot":"1"}
 }

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.

{
    "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"
        }
    ]
}