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 LocalityId
Name String or null Name
Districts Collection of <District> or null Districts
DistrictId Integer DistrictId
Name String or null Name
Suburbs Collection of <Suburb> or null Suburbs
SuburbId Integer SuburbId
Name String or null Name
AdjacentSuburbs Collection of Integer or null AdjacentSuburbs
Count Integer Count
Count Integer Count
Count Integer Count

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>
          </Suburb>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
          </Suburb>
        </Suburbs>
        <Count>123</Count>
      </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>
          </Suburb>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
          </Suburb>
        </Suburbs>
        <Count>123</Count>
      </District>
    </Districts>
    <Count>123</Count>
  </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>
          </Suburb>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
          </Suburb>
        </Suburbs>
        <Count>123</Count>
      </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>
          </Suburb>
          <Suburb>
            <SuburbId>123</SuburbId>
            <Name>ABC</Name>
            <AdjacentSuburbs>
              <SuburbId>123</SuburbId>
              <SuburbId>123</SuburbId>
            </AdjacentSuburbs>
            <Count>123</Count>
          </Suburb>
        </Suburbs>
        <Count>123</Count>
      </District>
    </Districts>
    <Count>123</Count>
  </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
          },
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123
          }
        ],
        "Count": 123
      },
      {
        "DistrictId": 123,
        "Name": "ABC",
        "Suburbs": [
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123
          },
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123
          }
        ],
        "Count": 123
      }
    ],
    "Count": 123
  },
  {
    "LocalityId": 123,
    "Name": "ABC",
    "Districts": [
      {
        "DistrictId": 123,
        "Name": "ABC",
        "Suburbs": [
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123
          },
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123
          }
        ],
        "Count": 123
      },
      {
        "DistrictId": 123,
        "Name": "ABC",
        "Suburbs": [
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123
          },
          {
            "SuburbId": 123,
            "Name": "ABC",
            "AdjacentSuburbs": [
              123,
              123
            ],
            "Count": 123
          }
        ],
        "Count": 123
      }
    ],
    "Count": 123
  }
]