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