Suburb Lookup

Typeahead service for Searching for Suburbs and Postcodes

Suburb lookup

get

Authorizations

Query parameters

countrystringrequired

country/region ISO2 code

Example: AU

sourceOfTruthstringoptional

optional source of truth for certain country/region

Example: GNAF

statestringoptional

state that narrrows down the search

Example: NSW

localitystringrequired

search input for suburb, locality or postcode

Example: syd 2000

featureOptionsstringoptional

feature options

Example: exposeAttributes:1

Responses

application/json

objectoptional

get

HTTPcURLJavaScriptPython

GET /harmony/rest/v2/suburb/find HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Accept: */*

200

OK

{
  "status": "SUCCESS",
  "messages": [
    "text"
  ],
  "payload": {
    "sourceReduced": true,
    "empty": true,
    "first": {
      "uuid": "text",
      "createDate": "2025-04-16T19:48:38.724Z",
      "updateDate": "2025-04-16T19:48:38.724Z",
      "assessments": [
        {
          "uuid": "text",
          "assessmentDate": "2025-04-16T19:48:38.724Z",
          "events": [
            {
              "uuid": "text",
              "action": "accept",
              "source": {
                "id": 1,
                "code": "text",
                "externalCode": "text",
                "description": "text",
                "internalOnly": true,
                "descriptionOnly": true
              },
              "customerId": 1,
              "eventDate": "2025-04-16T19:48:38.724Z",
              "score": 1,
              "description": "text",
              "attributes": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            }
          ],
          "score": 1
        }
      ],
      "attributes": [
        {
          "uuid": "text",
          "name": "text",
          "value": "text"
        }
      ],
      "country": "text",
      "postcode": "text",
      "suburb": "text",
      "state": "text",
      "line1": "text",
      "line2": "text",
      "streetNumber1Prefix": "text",
      "streetNumber1": "text",
      "streetNumber1Suffix": "text",
      "streetNumber2Prefix": "text",
      "streetNumber2": "text",
      "streetNumber2Suffix": "text",
      "postalType": "text",
      "postalNumber": "text",
      "buildingName": "text",
      "subdwelling": "text",
      "lotNumber": "text",
      "flatUnitNumber": "text",
      "flatUnitType": "text",
      "floorLevelNumber": "text",
      "floorLevelType": "text",
      "streetSuffix": "text",
      "streetType": "text",
      "streetName": "text",
      "rdNumber": "text",
      "district": "text",
      "latitude": "text",
      "longitude": "text",
      "description": "text",
      "fullAddress": "text",
      "locality": "text",
      "_type": "text"
    },
    "last": {
      "uuid": "text",
      "createDate": "2025-04-16T19:48:38.724Z",
      "updateDate": "2025-04-16T19:48:38.724Z",
      "assessments": [
        {
          "uuid": "text",
          "assessmentDate": "2025-04-16T19:48:38.724Z",
          "events": [
            {
              "uuid": "text",
              "action": "accept",
              "source": {
                "id": 1,
                "code": "text",
                "externalCode": "text",
                "description": "text",
                "internalOnly": true,
                "descriptionOnly": true
              },
              "customerId": 1,
              "eventDate": "2025-04-16T19:48:38.724Z",
              "score": 1,
              "description": "text",
              "attributes": {
                "ANY_ADDITIONAL_PROPERTY": "text"
              }
            }
          ],
          "score": 1
        }
      ],
      "attributes": [
        {
          "uuid": "text",
          "name": "text",
          "value": "text"
        }
      ],
      "country": "text",
      "postcode": "text",
      "suburb": "text",
      "state": "text",
      "line1": "text",
      "line2": "text",
      "streetNumber1Prefix": "text",
      "streetNumber1": "text",
      "streetNumber1Suffix": "text",
      "streetNumber2Prefix": "text",
      "streetNumber2": "text",
      "streetNumber2Suffix": "text",
      "postalType": "text",
      "postalNumber": "text",
      "buildingName": "text",
      "subdwelling": "text",
      "lotNumber": "text",
      "flatUnitNumber": "text",
      "flatUnitType": "text",
      "floorLevelNumber": "text",
      "floorLevelType": "text",
      "streetSuffix": "text",
      "streetType": "text",
      "streetName": "text",
      "rdNumber": "text",
      "district": "text",
      "latitude": "text",
      "longitude": "text",
      "description": "text",
      "fullAddress": "text",
      "locality": "text",
      "_type": "text"
    }
  }
}

Resource URL

    GET    https://hosted.mastersoftgroup.com/harmony/rest/v2/suburb/find?country=AU&locality=XXXX&

Required Parameters

Name	Description	Type
country*	country/region ISO2 code	string
locality*	search input for suburb, locality or postcode	string

Resource URL with optional parameters

GET    https://hosted.mastersoftgroup.com/harmony/rest/v2/suburb/find?country=AU&locality=3004&sourceOfTruth=AUPAF&state=VIC

Optional Parameters

Name	Description	Type
featureOptions	Set featureOptions	string
sourceOfTruth	Set source of truth for certain country/region	string
state	Filter to a particular State	string

Response AU

The response body is a JSON object. The following is an example:

{
  "status":"SUCCESS",
  "messages":[],
  "payload":[
    {
      "_type":"LocalityAu",
      "fullAddress":"BRISBANE CITY QLD 4000",
      "country":"AU",
      "postcode":"4000",
      "attributes":{
        "GNAFReliability":"5",
        "GNAFPID":"QLD3356",
        "GNAFLocalityPID":"QLD3356",
        "Latitude":"-27.46977630",
        "Longitude":"153.02514222"
      },
      "state":"QLD",
      "locality":"BRISBANE CITY"
    },
    {
      "_type":"LocalityAu",
      "fullAddress":"BRISBANE AIRPORT QLD 4008",
      "country":"AU",
      "postcode":"4008",
      "attributes":{
        "GNAFReliability":"5",
        "GNAFPID":"QLD3377",
        "GNAFLocalityPID":"QLD3377",
        "Latitude":"-27.38836933",
        "Longitude":"153.11320402"
      },
      "state":"QLD",
      "locality":"BRISBANE AIRPORT"
    },
    {
      "_type":"LocalityAu",
      "fullAddress":"SOUTH BRISBANE QLD 4101",
      "country":"AU",
      "postcode":"4101",
      "attributes":{
        "GNAFReliability":"5",
        "GNAFPID":"QLD2652",
        "GNAFLocalityPID":"QLD2652",
        "Latitude":"-27.47806742",
        "Longitude":"153.01941190"
      },
      "state":"QLD",
      "locality":"SOUTH BRISBANE"
    },
    {
      "_type":"LocalityAu",
      "fullAddress":"EAST BRISBANE QLD 4169",
      "country":"AU",
      "postcode":"4169",
      "attributes":{
        "GNAFReliability":"5",
        "GNAFPID":"QLD933",
        "GNAFLocalityPID":"QLD933",
        "Latitude":"-27.48334169",
        "Longitude":"153.04671989"
      },
      "state":"QLD",
      "locality":"EAST BRISBANE"
    },
    {
      "_type":"LocalityAu",
      "fullAddress":"PORT OF BRISBANE QLD 4178",
      "country":"AU",
      "postcode":"4178",
      "attributes":{
        "GNAFReliability":"5",
        "GNAFPID":"QLD2413",
        "GNAFLocalityPID":"QLD2413",
        "Latitude":"-27.38999869",
        "Longitude":"153.17820559"
      },
      "state":"QLD",
      "locality":"PORT OF BRISBANE"
    }
  ]
}

Response NZ

The response body is a JSON object. The following is an example:

{
    "status": "SUCCESS",
    "messages": [],
    "payload": [
        {
            "_type": "LocalityNz",
            "fullAddress": "AVONDALE, AUCKLAND 0600",
            "country": "NZ",
            "postcode": "0600",
            "attributes": {
                "ProvinceName": "AUCKLAND REGION",
                "regional_council_name": "AUCKLAND REGION",
                "City": "AUCKLAND",
                "ProvinceCode": ""
            },
            "suburb": "AVONDALE",
            "townCity": "AUCKLAND"
        },
        {
            "_type": "LocalityNz",
            "fullAddress": "BLOCKHOUSE BAY, AUCKLAND 0600",
            "country": "NZ",
            "postcode": "0600",
            "attributes": {
                "ProvinceName": "AUCKLAND REGION",
                "regional_council_name": "AUCKLAND REGION",
                "City": "AUCKLAND",
                "ProvinceCode": ""
            },
            "suburb": "BLOCKHOUSE BAY",
            "townCity": "AUCKLAND"
        },
        {
            "_type": "LocalityNz",
            "fullAddress": "MOUNT ALBERT, AUCKLAND 0600",
            "country": "NZ",
            "postcode": "0600",
            "attributes": {
                "ProvinceName": "AUCKLAND REGION",
                "regional_council_name": "AUCKLAND REGION",
                "City": "AUCKLAND",
                "ProvinceCode": ""
            },
            "suburb": "MOUNT ALBERT",
            "townCity": "AUCKLAND"
        }
    ]
}