Website logo

Retrieve Property, Jobs and Services districts

Returns the districts and suburbs within the region with the given ID. These values are used in Trade Me Property, Trade Me Jobs and Services.

URL: https://api.trademe.co.nz/v1/localities/region/{regionId}.{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 to get districts and suburbs for.
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 district. Defaults to false.

Returns

Collection of <Locality>

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

Examples

https://api.trademe.co.nz/v1/Localities/Region/9.xml - Retrieves the districts and suburbs within Northland.

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
  }
]