Website logo

Retrieve Property, Jobs and Services localities

Returns a three-tier locality hierarchy of regions, districts and their respective suburbs (including adjacent suburbs, if they have them). These values are used in Trade Me Property, Trade Me Jobs and Services.

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

URL parameters

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 locality. Defaults to false. This option currently does not work.

Returns

Collection of <Locality>

A list of all localities.

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)

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