Suburb Lookup

Typeahead service for Searching for Suburbs and Postcodes

Suburb lookup

get

Authorizations

rightaddress

AuthorizationstringRequired

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

200

OK

application/json

get

/rest/v2/suburb/find

HTTPcURLJavaScriptPython

GET /harmony/rest/v2/suburb/find?country=text&locality=text HTTP/1.1
Host: hosted.mastersoftgroup.com
Authorization: Basic username:password
Accept: */*

200

OK

{
  "status": "SUCCESS",
  "messages": [
    "text"
  ],
  "payload": {
    "sourceReduced": true,
    "empty": true,
    "first": {
      "fullAddress": "text",
      "country": "text",
      "postcode": "text",
      "subLocality": "text",
      "street2": "text",
      "street": "text",
      "streetNumber": "text",
      "postal": "text",
      "postalType": "text",
      "postalNumber": "text",
      "buildingName": "text",
      "subdwelling": "text",
      "eid": "text",
      "lotNumber": "text",
      "flatUnitNumber": "text",
      "flatUnitType": "text",
      "floorLevelNumber": "text",
      "floorLevelType": "text",
      "streetSuffix": "text",
      "streetType": "text",
      "streetName": "text",
      "attributes": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "id": "text",
      "sourceOfTruth": "text",
      "_type": "text",
      "locality": "text",
      "state": "text"
    },
    "last": {
      "fullAddress": "text",
      "country": "text",
      "postcode": "text",
      "subLocality": "text",
      "street2": "text",
      "street": "text",
      "streetNumber": "text",
      "postal": "text",
      "postalType": "text",
      "postalNumber": "text",
      "buildingName": "text",
      "subdwelling": "text",
      "eid": "text",
      "lotNumber": "text",
      "flatUnitNumber": "text",
      "flatUnitType": "text",
      "floorLevelNumber": "text",
      "floorLevelType": "text",
      "streetSuffix": "text",
      "streetType": "text",
      "streetName": "text",
      "attributes": {
        "ANY_ADDITIONAL_PROPERTY": "text"
      },
      "id": "text",
      "sourceOfTruth": "text",
      "_type": "text",
      "locality": "text",
      "state": "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"
        }
    ]
}