Website logo

Retrieve location hierarchy for multi-region search

Retrieves the complete location hierarchy (regions, districts, suburbs) in a single call. Supports multi-region selection by echoing the selection state.

URL: https://api.trademe.co.nz/v1/SearchOptions/Locations.{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

districts String (optional)

Optional comma-separated list of selected district IDs. Example: ?districts=7,12
regions String (optional)

Optional comma-separated list of selected region IDs. Example: ?regions=1,3
suburbs String (optional)

Optional comma-separated list of selected suburb IDs. Example: ?suburbs=42,100

Returns

Collection of <LocationOption>

A flat array of all locations with parent-child relationships and selection state.

Value String or null

The unique identifier for this location.
Display String or null

Name of this location.
Count Integer or null

The number of child locations (districts for regions, suburbs for districts, 0 for suburbs).
Level String or null

The hierarchy level of this location: "region", "district", or "suburb".
ParentId String or null

The ID of the parent location. Null for regions, region ID for districts, district ID for suburbs.
Selected Boolean

Whether this location is included in the current selection.

Example XML Response (switch to JSON) 

<LocationOptionCollection xmlns="http://api.trademe.co.nz/v1">
  <LocationOption>
    <Value>ABC</Value>
    <Display>ABC</Display>
    <Count>123</Count>
    <Level>ABC</Level>
    <ParentId>ABC</ParentId>
    <Selected>false</Selected>
  </LocationOption>
  <LocationOption>
    <Value>ABC</Value>
    <Display>ABC</Display>
    <Count>123</Count>
    <Level>ABC</Level>
    <ParentId>ABC</ParentId>
    <Selected>false</Selected>
  </LocationOption>
</LocationOptionCollection>

Example JSON Response (switch to XML) 

[
  {
    "Value": "ABC",
    "Display": "ABC",
    "Count": 123,
    "Level": "ABC",
    "ParentId": "ABC",
    "Selected": false
  },
  {
    "Value": "ABC",
    "Display": "ABC",
    "Count": 123,
    "Level": "ABC",
    "ParentId": "ABC",
    "Selected": false
  }
]