Address v1

These methods have been deprecated.

We recommend you upgrade your service to the latest Address Validation method. Upgrade at no cost and improved performance.

Address lookup methods (AU/NZ)

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.

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.

address

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

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/address
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/address
    

Request (POST)

The request body is an AddressRestRequest object:

• The 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"
    }
 

Request Parameters (GET)

• The fullAddress attribute is required

• The sourceOfTruth attribute is required

• The locality attribute is optional

• The postcode attribute is optional

• The state attribute is optional

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

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

buildingName

Performs a search for building names using the supplied buildingName.

Additional information supplied in the request will further filter the results.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/buildingName
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/buildingName
    

Request (POST)

The request body is an AddressRestRequest object:

• The buildingName attribute is required

• The postcode attribute is optional

• The locality attribute is optional

• The townCity attribute is optional (New Zealand)

• The suburb attribute is optional (New Zealand)

• The street attribute is optional

• The streetNumber attribute is optional

• The featureOptions attribute is optional

    {
        "payload": [ { "buildingName": "anz" } ],
        "sourceOfTruth": "AUPAF"
    }
    

Request Parameters (GET)

• The buildingName attribute is required

• The sourceOfTruth attribute is required

• The postcode attribute is optional

• The locality attribute is optional

• The transactionID attribute is optional

Response

The 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"
            }, 
            ...
        ]
    }
    

locality

Performs an Australian locality search using the supplied information.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/locality
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/locality
    

Request (POST)

The request body is an AddressRestRequest object:

• The locality attribute is required for non-semi locality search

• The postcode attribute is optional

• The fullAddress attribute is required for semi locality search

    {
        "payload": [ { "locality": "SYD" } ],
        "sourceOfTruth": "AUPAF"
    }
    
    For Semi structure locality search:    
    {
        "payload": [ { "fullAddress":"SYDNEY 2000"} ],
        "sourceOfTruth": "AUPAF"
    }

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The locality attribute is required for non-semi locality search

• The postcode attribute is optional

• The fullAddress attribute is required for semi locality search

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

The 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"
            },
            ...
        ]
    }
    

postal

Performs a search for a postal address using the supplied information.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postal
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postal
    

Request (POST)

The request body is an AddressRestRequest object:

• The postal is required

• Either the postcode or locality attribute is required

    {
        "payload": [ { "postcode": "2000", "postal": "Locked Bag 1" } ],
        "sourceOfTruth": "AUPAF"
    }
    

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The postal is required

• Either the postcode or locality attribute is required

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

The 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"
            },
            ...
        ]
    }
    

postcode

Performs a postcode search using the supplied information.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postcode
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/postcode
    

Request (POST)

The request body is an AddressRestRequest object:

• The postcode attribute is required

    {
        "payload": [ { "postcode": "3000" } ],
        "sourceOfTruth": "AUPAF"
    }
    

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The postcode attribute is required

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

The 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"
            },
            ...
        ]
    }
    

street

Performs a street search using the supplied information.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/street
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/street
    

Request (POST)

The request body is an AddressRestRequest object:

• The street attribute is required

• The postcode attribute is optional

• The locality attribute is optional

• The townCity attribute is optional (New Zealand)

• The suburb attribute is optional (New Zealand)

    {
        "payload": [ { "street": "GEORGE" } ],
        "sourceOfTruth": "AUPAF"
    }
    

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The street attribute is required

• The postcode attribute is optional

• The locality attribute is optional

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

The 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"
            },
            ...
        ]
    }
    

streetNumber

Performs a street number search using the supplied information.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/streetNumber
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/streetNumber
    

Request (POST)

The request body is an AddressRestRequest object:

• The streetNumber attribute is required

• The postcode attribute is required

• The locality attribute is required

• The townCity attribute is optional (New Zealand)

• The suburb attribute is optional (New Zealand)

• The street attribute is required

    {
        "payload": [ 
            { 
                "postcode": "2000",
                "locality": "SYDNEY",
                "street": "GEORGE",
                "streetNumber": "220"
            } 
        ],
        "sourceOfTruth": "AUPAF"
    }
    

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The streetNumber attribute is required

• The postcode attribute is required

• The locality attribute is required

• The street attribute is required

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

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

subdwelling

Performs a subdwelling search using the supplied information.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwelling
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwelling
    

Request (POST)

The request body is an AddressRestRequest object:

• The subdwelling attribute is required

• The postcode attribute is optional

• The locality attribute is optional

• The townCity attribute is optional (New Zealand)

• The suburb attribute is optional (New Zealand)

• The street attribute is optional

• The streetNumber attribute is optional

    {
        "payload": [ 
            {
                "postcode": "2000",
                "locality": "SYDNEY",
                "street": "GEORGE",
                "streetNumber": "220",
                "subdwelling": "202"
            } 
        ],
        "sourceOfTruth": "AUPAF"
    }
    

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The subdwelling attribute is required

• The postcode attribute is required

• The locality attribute is required

• The street attribute is required

• The streetNumber attribute is required

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

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

subdwellingAddress

List all subdwellings under a given address.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwellingAddress
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/subdwellingAddress
    

Request (POST)

The request body is an AddressRestRequest object:

• The id attribute is required

    {
        "payload": [ 
            {
                "id":"59676232"
            } 
        ],
        "sourceOfTruth": "AUPAF"
    }

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The id attribute is required

• The featureOptions attribute is optional

Response

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

suburb

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.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/suburb
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/suburb
    

Request (POST)

The request body is an AddressRestRequest object:

• The suburb attribute is required

• The postcode attribute is optional

• The townCity attribute is optional

    {
        "payload": [ { "suburb": "WELL" } ],
        "sourceOfTruth": "NZPAF"
    }

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The suburb attribute is required

• The postcode attribute is optional

• The townCity attribute is optional

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

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

townCity

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.

Resource URL

   POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/townCity
   

Or if using GET

   GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/townCity
   

Request (POST)

The request body is an AddressRestRequest object:

• The townCity attribute is required

• The postcode attribute is optional

    {
        "payload": [ { "townCity": "WELL" } ],
        "sourceOfTruth": "NZPAF"
    }
    

Request Parameters (GET)

• The sourceOfTruth attribute is required

• The townCity attribute is required

• The postcode attribute is optional

• The transactionID attribute is optional

• The featureOptions attribute is optional

Response

The 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"
            },
            ...
        ]
    }
    

AUNZreverseGeocode

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

Resource URL

   GET/POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/reverseGeocode

Request

The request body is an AddressRestRequest object:

• The attributes with latitude and longitude is required

• The sourceOfTruth is optional. The supported Source of Truths are GNAF, NZPAF, NZAD, CNAR (default is GNAF for Australia and NZPAF for New Zealand).

• The 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"}
    }

Response

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

transaction

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.

Resource URL

    POST    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/transaction
    

Or if using GET

    GET    https://hosted.mastersoftgroup.com/harmony/rest/{locale}/transaction
    

Request (POST)

The request body is an AddressRestRequest object:

    { 
        "sourceOfTruth": "AUPAF" 
    }
    

Request Parameters (GET)

• The sourceOfTruth attribute is required

Response

The response body is an AddressRestResponse object:

    {
        "status": "SUCCESS", 
        "messages": [], 
        "payload": null 
    }