Website logo

Retrieve Property, Jobs and Services individual suburb

Returns a specific suburb. These values are used in Trade Me Property, Trade Me Jobs and Services.

URL: https://api.trademe.co.nz/v1/localities/region/{regionId}/{districtId}/{suburbId}.{file_format}
HTTP Method: GET
Requires Authentication? No
Permission Required: Public
Supported Formats: XML, JSON
Rate Limited? No

URL parameters

regionId Integer (required)

The region ID.
districtId Integer (required)

The district ID.
suburbId Integer (required)

The suburb ID.
file_format Enumeration (required) The format of the response.
xml Serialize responses into XML.
json Serialize responses into JSON.

Query String parameters

listing_type String (optional)

The type of listing to include in the count property, if with_counts is true. Valid values are "HOUSES_TO_BUY", "HOUSES_TO_RENT", "COMMERCIAL_FOR_SALE", "COMMERCIAL_FOR_LEASE", "FLATMATES_WANTED", "RURAL", "RETIREMENT_VILLAGES" and "LIFESTYLE". Defaults to "HOUSES_TO_BUY".
with_counts Boolean (optional)

Indicates whether to include the listing count for each suburb. Defaults to false.

Returns

Collection of <Locality>

LocalityId Integer

The ID of the region.
Name String or null

The name of the region.
Districts Collection of <District> or null

The list of districts that belong to this region.
DistrictId Integer

The ID of the district.
Name String or null

The name of the district.
Suburbs Collection of <Suburb> or null

The list of suburbs that belong to this district.
SuburbId Integer

The ID of the suburb.
Name String or null

The name of the suburb.
AdjacentSuburbs Collection of Integer or null

A list containing the IDs of the suburbs adjacent to this suburb.
Count Integer

The number of items being sold in this suburb.
SeoDrivenUrl <SeoDrivenUrl> or null

Canonical URL to this suburb
SeoDrivenCanonicalUrl String or null

New Canonical Url structure Eg. "\/marketplace\/s\/bbqs-outdoor-ovens\/"
Count Integer

The number of items that are being sold in this district.
SeoDrivenUrl <SeoDrivenUrl> or null

Canonical URL to this district
(This type has already been defined)
Count Integer

The number of items being sold in this region.
SeoDrivenUrl <SeoDrivenUrl> or null

Canonical URL to this region
(This type has already been defined)

Examples

https://api.trademe.co.nz/v1/Localities/Region/9/2/3055.xml - Retrieves the suburb Central Whangarei within Whangarei.

Example XML Response (switch to JSON) 

<LocalityCollection xmlns="http://api.trademe.co.nz/v1">
  <Locality>
    <LocalityId>123</LocalityId>
    <Name>ABC</Name>
    <Districts>
      <District>
        <DistrictId>123</DistrictId>
        <Name>ABC</Name>
        <Suburbs>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
            <SeoDrivenUrl>
              <SeoDrivenCanonicalUrl>ABC</SeoDrivenCanonicalUrl>
            </SeoDrivenUrl>
          </Suburb>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
            <SeoDrivenUrl>
              <SeoDrivenCanonicalUrl>ABC</SeoDrivenCanonicalUrl>
            </SeoDrivenUrl>
          </Suburb>
        </Suburbs>
        <Count>123</Count>
        <SeoDrivenUrl />
      </District>
      <District>
        <DistrictId>123</DistrictId>
        <Name>ABC</Name>
        <Suburbs>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
            <SeoDrivenUrl>
              <SeoDrivenCanonicalUrl>ABC</SeoDrivenCanonicalUrl>
            </SeoDrivenUrl>
          </Suburb>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
            <SeoDrivenUrl>
              <SeoDrivenCanonicalUrl>ABC</SeoDrivenCanonicalUrl>
            </SeoDrivenUrl>
          </Suburb>
        </Suburbs>
        <Count>123</Count>
        <SeoDrivenUrl />
      </District>
    </Districts>
    <Count>123</Count>
    <SeoDrivenUrl />
  </Locality>
  <Locality>
    <LocalityId>123</LocalityId>
    <Name>ABC</Name>
    <Districts>
      <District>
        <DistrictId>123</DistrictId>
        <Name>ABC</Name>
        <Suburbs>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
            <SeoDrivenUrl>
              <SeoDrivenCanonicalUrl>ABC</SeoDrivenCanonicalUrl>
            </SeoDrivenUrl>
          </Suburb>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
            <SeoDrivenUrl>
              <SeoDrivenCanonicalUrl>ABC</SeoDrivenCanonicalUrl>
            </SeoDrivenUrl>
          </Suburb>
        </Suburbs>
        <Count>123</Count>
        <SeoDrivenUrl />
      </District>
      <District>
        <DistrictId>123</DistrictId>
        <Name>ABC</Name>
        <Suburbs>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
            <SeoDrivenUrl>
              <SeoDrivenCanonicalUrl>ABC</SeoDrivenCanonicalUrl>
            </SeoDrivenUrl>
          </Suburb>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
            <SeoDrivenUrl>
              <SeoDrivenCanonicalUrl>ABC</SeoDrivenCanonicalUrl>
            </SeoDrivenUrl>
          </Suburb>
        </Suburbs>
        <Count>123</Count>
        <SeoDrivenUrl />
      </District>
    </Districts>
    <Count>123</Count>
    <SeoDrivenUrl />
  </Locality>
</LocalityCollection>

Example JSON Response (switch to XML) 

[
  {
    "LocalityId": 123,
    "Name": "ABC",
    "Districts": [
      {
        "DistrictId": 123,
        "Name": "ABC",
        "Suburbs": [
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123,
            "SeoDrivenUrl": {
              "SeoDrivenCanonicalUrl": "ABC"
            }
          },
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123,
            "SeoDrivenUrl": {
              "SeoDrivenCanonicalUrl": "ABC"
            }
          }
        ],
        "Count": 123,
        "SeoDrivenUrl": {
        }
      },
      {
        "DistrictId": 123,
        "Name": "ABC",
        "Suburbs": [
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123,
            "SeoDrivenUrl": {
              "SeoDrivenCanonicalUrl": "ABC"
            }
          },
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123,
            "SeoDrivenUrl": {
              "SeoDrivenCanonicalUrl": "ABC"
            }
          }
        ],
        "Count": 123,
        "SeoDrivenUrl": {
        }
      }
    ],
    "Count": 123,
    "SeoDrivenUrl": {
    }
  },
  {
    "LocalityId": 123,
    "Name": "ABC",
    "Districts": [
      {
        "DistrictId": 123,
        "Name": "ABC",
        "Suburbs": [
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123,
            "SeoDrivenUrl": {
              "SeoDrivenCanonicalUrl": "ABC"
            }
          },
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123,
            "SeoDrivenUrl": {
              "SeoDrivenCanonicalUrl": "ABC"
            }
          }
        ],
        "Count": 123,
        "SeoDrivenUrl": {
        }
      },
      {
        "DistrictId": 123,
        "Name": "ABC",
        "Suburbs": [
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123,
            "SeoDrivenUrl": {
              "SeoDrivenCanonicalUrl": "ABC"
            }
          },
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123,
            "SeoDrivenUrl": {
              "SeoDrivenCanonicalUrl": "ABC"
            }
          }
        ],
        "Count": 123,
        "SeoDrivenUrl": {
        }
      }
    ],
    "Count": 123,
    "SeoDrivenUrl": {
    }
  }
]