Website logo

Retrieve your favourite searches

Retrieves the list of favourite searches for the currently authenticated user.

URL: https://api.trademe.co.nz/v1/Favourites/Searches/{filter}.{file_format}
HTTP Method: GET
Requires Authentication? Yes
Permission Required: MyTradeMeRead: Read your membership & listing data.
Supported Formats: XML, JSON
Rate Limited? Yes

URL parameters

filter String (required)

Filters the list of searches to those of a given type. Must be "All", "General", "Job", "Motor" or "Property".

file_format Enumeration (required) The format of the response.
xml Serialize responses into XML.
json Serialize responses into JSON.

Query String parameters

page Integer (optional)

The page number of the set of results to return, starting from 1. Defaults to 1.

rows Integer (optional)

The number of results per page; also the maximum number of results to return. Defaults to all favourites.

Returns

<SavedSearches>

A list of favourite searches.

TotalCount Integer

The total number of results in the collection. Can be larger than the number of returned results.

Page Integer

The index of the current page of results (starts at 1).

PageSize Integer

The number of results in the current page.

List Collection of <SavedSearch> or null

A list of the results in the current page.

FavouriteId Integer

The ID of the favourite.

SearchApi Enumeration

The search API endpoint that should be used in conjunction with the SearchString property to build up a search URL. Examples include "General", "Motors/Used", etc.

General 0

General search.

UsedMotors 1

Used cars.

MotorBoat 2

Motor boats.

MotorBike 3

Motor bikes.

Residential 4

Residential property for sale.

Rental 5

Residential property to rent.

CommercialSale 6

Commercial property for sale.

CommercialLease 7

Commercial property leases.

Rural 8

Rural property.

Lifestyle 9

Lifestyle blocks.

Flatmate 10

Flatmates.

OpenHomes 11

Open homes.

Retirement 12

Retirement villages.

Job 13

Jobs.

NewHomes 14

New Homes property.

Caravan 15

Motors caravan property

Motorhome 16

Motors motorhomes property

SearchString String or null

A string containing the search parameters. This is formatted like a HTTP query string (but without a leading question mark) and can include any of the parameters accepted by the search APIs.

Attributes <SearchAttributes> or null

The attributes saved in the search.

TotalCount Integer

The total number of results in the collection. Can be larger than the number of returned results.

Page Integer

The index of the current page of results (starts at 1).

PageSize Integer

The number of results in the current page.

List Collection of <SearchAttribute> or null

A list of the results in the current page.

Name String or null

A name which uniquely identifies the attribute. Required when selling or editing.

DisplayName String or null

The name of the attribute, in a form suitable for displaying to users. Not required when selling or editing.

Value String or null

The string value of the attribute. When listing, the valid values for the attribute can be determined using the "Retrieve attributes for a category" API. Use "false" or "true" for boolean attributes. Required when selling or editing.

DisplayValue String or null

The value of the attribute as it needs to be displayed to the end users

SearchParameterName String or null

The name of the attribute when used in a search string.

EmailOptions Enumeration

Indicates how often the email updates should be sent for this favourite.

None 0

No emails are sent.

Daily 1

An email is sent every day.

Every3Days 3

An email is sent each third day.

Weekly 7

An email is sent every week.

Option Enumeration

The favourite type. Only used when updating and deleting.

None 0

Nothing

Category 1

Category

Search 3

General search

AttributeSearch 4

Attributed search

Seller 6

Seller

LastAccessed DateTime or null

The date the favourite was last accessed in UTC format.

FavouritePushFrequency Enumeration

The push notification of the favourite, which the FavouriteId property refers to.

None 0

Push not enabled for this favourite.

Instant 1

Push is enabled for this favourite.

CategoryPath String or null

The breadcrumb trail for the category, e.g. "Books > Children & babies > Picture books > Beatrix Potter".

CategoryName String or null

The name of the category.

Category String or null

The full category identifier, e.g. "0193-0462-0255-6659-".

CategoryId Integer

The category ID, e.g. 6659.

Keywords String or null

The search query for the search.

SearchType Enumeration

The type of saved search (motors, jobs, etc).

All 0

General items.

General 1

General items.

Job 2

Jobs.

Motor 3

Motors.

Property 4

Property.

RegionId Integer

The ID of the region this seach is for (doesn't apply to jobs, property or services).

DistrictId Integer

The ID of the district this seach is for (doesn't apply to jobs, property or services).

StaticMapsImage String or null

The Google static maps image URL belonging to the saved search

Example XML Response (switch to JSON)

<SavedSearches xmlns="http://api.trademe.co.nz/v1">
  <TotalCount>123</TotalCount>
  <Page>123</Page>
  <PageSize>123</PageSize>
  <List>
    <SavedSearch>
      <FavouriteId>123</FavouriteId>
      <SearchApi>General</SearchApi>
      <SearchString>ABC</SearchString>
      <Attributes>
        <TotalCount>123</TotalCount>
        <Page>123</Page>
        <PageSize>123</PageSize>
        <List>
          <SearchAttribute>
            <Name>ABC</Name>
            <DisplayName>ABC</DisplayName>
            <Value>ABC</Value>
            <DisplayValue>ABC</DisplayValue>
            <SearchParameterName>ABC</SearchParameterName>
          </SearchAttribute>
          <SearchAttribute>
            <Name>ABC</Name>
            <DisplayName>ABC</DisplayName>
            <Value>ABC</Value>
            <DisplayValue>ABC</DisplayValue>
            <SearchParameterName>ABC</SearchParameterName>
          </SearchAttribute>
        </List>
      </Attributes>
      <EmailOptions>None</EmailOptions>
      <Option>None</Option>
      <LastAccessed>2018-01-01T00:00:00Z</LastAccessed>
      <FavouritePushFrequency>None</FavouritePushFrequency>
      <CategoryPath>ABC</CategoryPath>
      <CategoryName>ABC</CategoryName>
      <Category>ABC</Category>
      <CategoryId>123</CategoryId>
      <Keywords>ABC</Keywords>
      <SearchType>All</SearchType>
      <RegionId>123</RegionId>
      <DistrictId>123</DistrictId>
      <StaticMapsImage>ABC</StaticMapsImage>
    </SavedSearch>
    <SavedSearch>
      <FavouriteId>123</FavouriteId>
      <SearchApi>General</SearchApi>
      <SearchString>ABC</SearchString>
      <Attributes>
        <TotalCount>123</TotalCount>
        <Page>123</Page>
        <PageSize>123</PageSize>
        <List>
          <SearchAttribute>
            <Name>ABC</Name>
            <DisplayName>ABC</DisplayName>
            <Value>ABC</Value>
            <DisplayValue>ABC</DisplayValue>
            <SearchParameterName>ABC</SearchParameterName>
          </SearchAttribute>
          <SearchAttribute>
            <Name>ABC</Name>
            <DisplayName>ABC</DisplayName>
            <Value>ABC</Value>
            <DisplayValue>ABC</DisplayValue>
            <SearchParameterName>ABC</SearchParameterName>
          </SearchAttribute>
        </List>
      </Attributes>
      <EmailOptions>None</EmailOptions>
      <Option>None</Option>
      <LastAccessed>2018-01-01T00:00:00Z</LastAccessed>
      <FavouritePushFrequency>None</FavouritePushFrequency>
      <CategoryPath>ABC</CategoryPath>
      <CategoryName>ABC</CategoryName>
      <Category>ABC</Category>
      <CategoryId>123</CategoryId>
      <Keywords>ABC</Keywords>
      <SearchType>All</SearchType>
      <RegionId>123</RegionId>
      <DistrictId>123</DistrictId>
      <StaticMapsImage>ABC</StaticMapsImage>
    </SavedSearch>
  </List>
</SavedSearches>

Example JSON Response (switch to XML)

{
  "TotalCount": 123,
  "Page": 123,
  "PageSize": 123,
  "List": [
    {
      "FavouriteId": 123,
      "SearchApi": 0,
      "SearchString": "ABC",
      "Attributes": {
        "TotalCount": 123,
        "Page": 123,
        "PageSize": 123,
        "List": [
          {
            "Name": "ABC",
            "DisplayName": "ABC",
            "Value": "ABC",
            "DisplayValue": "ABC",
            "SearchParameterName": "ABC"
          },
          {
            "Name": "ABC",
            "DisplayName": "ABC",
            "Value": "ABC",
            "DisplayValue": "ABC",
            "SearchParameterName": "ABC"
          }
        ]
      },
      "EmailOptions": 0,
      "Option": 0,
      "LastAccessed": "\/Date(1514764800)\/",
      "FavouritePushFrequency": 0,
      "CategoryPath": "ABC",
      "CategoryName": "ABC",
      "Category": "ABC",
      "CategoryId": 123,
      "Keywords": "ABC",
      "SearchType": 0,
      "RegionId": 123,
      "DistrictId": 123,
      "StaticMapsImage": "ABC"
    },
    {
      "FavouriteId": 123,
      "SearchApi": 0,
      "SearchString": "ABC",
      "Attributes": {
        "TotalCount": 123,
        "Page": 123,
        "PageSize": 123,
        "List": [
          {
            "Name": "ABC",
            "DisplayName": "ABC",
            "Value": "ABC",
            "DisplayValue": "ABC",
            "SearchParameterName": "ABC"
          },
          {
            "Name": "ABC",
            "DisplayName": "ABC",
            "Value": "ABC",
            "DisplayValue": "ABC",
            "SearchParameterName": "ABC"
          }
        ]
      },
      "EmailOptions": 0,
      "Option": 0,
      "LastAccessed": "\/Date(1514764800)\/",
      "FavouritePushFrequency": 0,
      "CategoryPath": "ABC",
      "CategoryName": "ABC",
      "Category": "ABC",
      "CategoryId": 123,
      "Keywords": "ABC",
      "SearchType": 0,
      "RegionId": 123,
      "DistrictId": 123,
      "StaticMapsImage": "ABC"
    }
  ]
}