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.
suburb (NZ only) Lookup suburbs.
townCity (NZ only) Lookup towns/cities in 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
    

Request

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

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
    

Request

The request body is an AddressRestRequest object:

  • The buildName 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": [ { "buildingName": "anz" } ],
        "sourceOfTruth": "AUPAF"
    }
    

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
    

Request

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

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
    

Request

The request body is an AddressRestRequest object:

  • The postal is required
  • Either the postcode or locality attribute is required

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

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
    

Request

The request body is an AddressRestRequest object:

  • The postcode attribute is required

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

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
    

Request

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

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
    

Request

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

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
    

Request

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

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

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
    

Request

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

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
   

Request

The request body is an AddressRestRequest object:

  • The townCity attribute is required
  • The postcode attribute is optional

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

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

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
    

Request

The request body is an AddressRestRequest object:


    { 
        "sourceOfTruth": "AUPAF" 
    }
    

Response

The response body is an AddressRestResponse object:


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