Website logo

Retrieve general categories

Retrieves all or part of the Trade Me category tree.

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

URL parameters

number String (required)

The category number of the root of the returned tree. If this parameter is empty, it returns a fictional category named "Root" with all the top categories included as subcategories.
file_format Enumeration (required) The format of the response.
xml Serialize responses into XML.
json Serialize responses into JSON.

Query String parameters

depth Integer (optional)

The depth of the category tree to return. 0 = a single category. 1 = the specified category plus any subcategories. The default is to return all subcategories.
region Integer (optional)

The ID of the region used to filter listing counts. Only applicable if with_counts is true.
with_counts Boolean (optional)

Indicates whether to include the number of listings in each category. Defaults to false.

Returns

<Category>

A category tree.

Name String or null

The name of the category.
Number String or null

A unique identifier for the category e.g. "0004-0369-6076-". We plan to change this to a numeric identifier (e.g. "6076") so you should ensure you can cope with both formats.
Path String or null

The full URL path of this category e.g. "/Home-living/Beds-bedroom-furniture/Bedside-tables".
Subcategories Collection of <Category> or null

The list of subcategories belonging to this category.
(This type has already been defined)
Count Integer

The number of items for sale in this category.
IsRestricted Boolean

Indicates whether the category is restricted to adults only (i.e. the category is R18).
HasLegalNotice Boolean

Indicates whether the category has legal requirements. You should ask the user to accept the legal notice before listing in this category. There is an API to get the text of the legal notice.
HasClassifieds Boolean

Indicates whether classifieds are allowed in this category.
AreaOfBusiness Enumeration

Area of business this category is related to
NotSpecified 0

None specified.
All 0

All
Marketplace 1

Marketplace
Property 2

Property
Motors 3

Motors
Jobs 4

Jobs
Services 5

Services
CanHaveSecondCategory Boolean

Indicates whether this category can be paired with a second category.
CanBeSecondCategory Boolean

Indicates whether this category can be selected as a second category.
IsLeaf Boolean

Indicates whether the category is a leaf category (i.e. has no children).

Examples

https://api.trademe.co.nz/v1/Categories.xml - Retrieves all categories.
https://api.trademe.co.nz/v1/Categories/0001-.xml - Returns all Trade Me Motors subcategories (“0001” is the top level Trade Me Motors category).
https://api.trademe.co.nz/v1/Categories/0001-0026-1255-.xml - Returns all Motorbike subcategories (0001-0026-1255- is the Motorbikes category).

Example XML Response (switch to JSON) 

<Category xmlns="http://api.trademe.co.nz/v1">
  <Name>ABC</Name>
  <Number>ABC</Number>
  <Path>ABC</Path>
  <Subcategories>
    <Category />
    <Category />
  </Subcategories>
  <Count>123</Count>
  <IsRestricted>false</IsRestricted>
  <HasLegalNotice>false</HasLegalNotice>
  <HasClassifieds>false</HasClassifieds>
  <AreaOfBusiness>NotSpecified</AreaOfBusiness>
  <CanHaveSecondCategory>false</CanHaveSecondCategory>
  <CanBeSecondCategory>false</CanBeSecondCategory>
  <IsLeaf>false</IsLeaf>
</Category>

Example JSON Response (switch to XML) 

{
  "Name": "ABC",
  "Number": "ABC",
  "Path": "ABC",
  "Subcategories": [
    {
    },
    {
    }
  ],
  "Count": 123,
  "IsRestricted": false,
  "HasLegalNotice": false,
  "HasClassifieds": false,
  "AreaOfBusiness": 0,
  "CanHaveSecondCategory": false,
  "CanBeSecondCategory": false,
  "IsLeaf": false
}