# Suburb Lookup

## GET /rest/v2/suburb/find

> Suburb lookup

```json
{"openapi":"3.0.1","info":{"title":"Harmony RightAddress REST API","version":"2.13.0"},"tags":[{"name":"findSuburb","description":"Find suburb under a country/state"}],"servers":[{"url":"https://hosted.mastersoftgroup.com/harmony","description":"Generated server url"}],"security":[{"rightaddress":[]}],"components":{"securitySchemes":{"rightaddress":{"type":"http","scheme":"basic"}},"schemas":{"AddressRestResponse":{"type":"object","properties":{"status":{"type":"string","enum":["SUCCESS","ERROR"]},"messages":{"type":"array","items":{"type":"string"}},"payload":{"type":"array","properties":{"sourceReduced":{"type":"boolean"},"empty":{"type":"boolean"},"first":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]},"last":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}},"items":{"oneOf":[{"$ref":"#/components/schemas/AddressAu"},{"$ref":"#/components/schemas/AddressIntl"},{"$ref":"#/components/schemas/AddressNz"},{"$ref":"#/components/schemas/AddressV2"},{"$ref":"#/components/schemas/InternalParsedAddressAu"},{"$ref":"#/components/schemas/ParsedAddressAu"},{"$ref":"#/components/schemas/ValidatedAddressAu"},{"$ref":"#/components/schemas/AddressIntlV2"},{"$ref":"#/components/schemas/InternalParsedAddressNz"},{"$ref":"#/components/schemas/ParsedAddressNz"},{"$ref":"#/components/schemas/ValidatedAddressNz"}]}}}},"AddressAu":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"locality":{"type":"string"},"state":{"type":"string"},"_type":{"type":"string"}}}]},"Address":{"required":["_type"],"type":"object","properties":{"fullAddress":{"type":"string"},"country":{"type":"string"},"postcode":{"type":"string"},"subLocality":{"type":"string"},"street2":{"type":"string"},"street":{"type":"string"},"streetNumber":{"type":"string"},"postal":{"type":"string"},"postalType":{"type":"string"},"postalNumber":{"type":"string"},"buildingName":{"type":"string"},"subdwelling":{"type":"string"},"eid":{"type":"string"},"lotNumber":{"type":"string"},"flatUnitNumber":{"type":"string"},"flatUnitType":{"type":"string"},"floorLevelNumber":{"type":"string"},"floorLevelType":{"type":"string"},"streetSuffix":{"type":"string"},"streetType":{"type":"string"},"streetName":{"type":"string"},"attributes":{"type":"object","additionalProperties":{"type":"string"}},"id":{"type":"string"},"sourceOfTruth":{"type":"string"},"_type":{"type":"string"}},"discriminator":{"propertyName":"_type"}},"AddressIntl":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"district":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"},"_type":{"type":"string"}}}]},"AddressNz":{"required":["_type"],"type":"object","discriminator":{"propertyName":"_type"},"allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"rdNumber":{"type":"string"},"deliveredTo":{"type":"string"},"townCity":{"type":"string"},"suburb":{"type":"string"},"_type":{"type":"string"}}}]},"AddressV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/Address"},{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"line3":{"type":"string"},"city":{"type":"string"},"province":{"type":"string"}}}]},"InternalParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"}]},"ParsedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"PDPChangedItem":{"type":"object","properties":{"componentID":{"type":"string"},"actionType":{"type":"string","enum":["ADD","MODIFY","REMOVE","INFO"]},"affectedElement":{"type":"string"},"oldValue":{"type":"string"},"newValue":{"type":"string"}}},"ValidatedAddressAu":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressAu"},{"type":"object","properties":{"exception":{"type":"string"}}}]},"AddressIntlV2":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressIntl"}]},"InternalParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"}]},"ParsedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"careOf":{"type":"string"},"exception":{"type":"string"},"unknown":{"type":"string"},"changedItems":{"type":"array","items":{"$ref":"#/components/schemas/PDPChangedItem"}}}}]},"ValidatedAddressNz":{"type":"object","allOf":[{"$ref":"#/components/schemas/AddressNz"},{"type":"object","properties":{"exception":{"type":"string"}}}]}}},"paths":{"/rest/v2/suburb/find":{"get":{"tags":["findSuburb"],"summary":"Suburb lookup","operationId":"findSuburb","parameters":[{"name":"country","in":"query","description":"country/region ISO2 code","required":true,"schema":{"type":"string"}},{"name":"sourceOfTruth","in":"query","description":"optional source of truth for certain country/region","required":false,"schema":{"type":"string"}},{"name":"state","in":"query","description":"state that narrrows down the search","required":false,"schema":{"type":"string"}},{"name":"locality","in":"query","description":"search input for suburb, locality or postcode","required":true,"schema":{"type":"string"}},{"name":"featureOptions","in":"query","description":"feature options","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressRestResponse"}}}}}}}}}
```

#### Resource URL

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

#### Required Parameters

<table><thead><tr><th>Name</th><th width="303.2155805977462">Description</th><th>Type</th></tr></thead><tbody><tr><td>country*</td><td>country/region ISO2 code</td><td>string</td></tr><tr><td>locality*</td><td>search input for suburb, locality or postcode</td><td>string</td></tr></tbody></table>

#### 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**

<table><thead><tr><th>Name</th><th width="303.2155805977462">Description</th><th>Type</th></tr></thead><tbody><tr><td>featureOptions</td><td>Set featureOptions</td><td>string</td></tr><tr><td>sourceOfTruth</td><td>Set source of truth for certain country/region</td><td>string</td></tr><tr><td>state</td><td>Filter to a particular State</td><td>string</td></tr></tbody></table>

#### Response AU

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

```json
{
  "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:

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mastersoftgroup.com/loqate-harmony-api/api-specification/suburb-postcode-search.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.