Website logo

Save a search, category or seller to your favourites

Saves a search to the currently authenticated user's list of favourite searches. Can also be used to save a favourite category or seller with the option of specifying basic filters (condition, Buy Now, Pay Now) and sort order.

URL: https://api.trademe.co.nz/v1/Favourites/Search.{file_format}
HTTP Method: POST
Requires Authentication? Yes
Permission Required: MyTradeMeWrite: Maintain your watchlist, answer questions and post comments.
Supported Formats: XML, JSON
Rate Limited? Yes

URL parameters

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

POST Data

<SaveSearchRequest>

Email Enumeration (required)

The frequency that emails should be sent.
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.
Push Enumeration (optional)

The frequency that push notifications should be sent.
None 0

Push not enabled for this favourite.
Instant 1

Push is enabled for this favourite.
SearchString String (required)

A string containing the search parameters. This should be formatted like a HTTP query string (but without a leading question mark) and can include any of the parameters accepted by a search API (you can specify which search API using the SearchType field).
Type Enumeration (required)

The type of search to save. The value of this field changes the allowed parameters in SearchString. For example, if this is "UsedMotors" then "make" and "model" parameters become available (see the search API documentation for details on exactly what parameters are allowed). When saving a category or seller, use "General".
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

Returns

<SavedFavouriteResponse>

Details of the saved favourite, including the ID.

SearchId Integer

The ID of the saved favourite.
Response String or null

A description of the error, if the operation failed.
Saved Boolean

Indicates whether the favourite was saved.
FavouriteType Enumeration

Indicates what type of favourite was saved.
None 0

Nothing
Category 1

Category
Search 3

General search
AttributeSearch 4

Attributed search
Seller 6

Seller

Examples

Example of a saving a simple keyword search:

<SaveSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <Email>None</Email>
  <SearchString>search_string=Karen%20Walker</SearchString>
  <Type>General</Type>
</SaveSearchRequest>

Example of a saving a simple keyword search sorted by highest number of bids:

<SaveSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <Email>None</Email>
  <SearchString>search_string=Karen%20Walker&amp;sort_order=BidsMost</SearchString>
  <Type>General</Type>
</SaveSearchRequest>

Example of a saving a motors search with price range and automatic transmission filters:

<SaveSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <Email>None</Email>
  <SearchString>price_min=20000&amp;price_max=30000&amp;transmission=Automatic</SearchString>
  <Type>UsedMotors</Type>
</SaveSearchRequest>

Example of a saving a category (with a daily email):

<SaveSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <Email>Daily</Email>
  <SearchString>category=4295</SearchString>
  <Type>General</Type>
</SaveSearchRequest>

Example of saving a category with a region filter:

<SaveSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <Email>None</Email>
  <SearchString>category=4295&amp;user_region=12</SearchString>
  <Type>General</Type>
</SaveSearchRequest>

Example of a saving a seller (with a weekly email):

<SaveSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <Email>Weekly</Email>
  <SearchString>member_listing=158286</SearchString>
  <Type>General</Type>
</SaveSearchRequest>

Example of saving a seller with a Buy Now filter:

<SaveSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <Email>None</Email>
  <SearchString>member_listing=158286&amp;buy=BuyNow</SearchString>
  <Type>General</Type>
</SaveSearchRequest>

Example XML Request (switch to JSON) 

<SaveSearchRequest xmlns="http://api.trademe.co.nz/v1">
  <Email>None</Email>
  <Push>None</Push>
  <SearchString>ABC</SearchString>
  <Type>General</Type>
</SaveSearchRequest>

Example JSON Request (switch to XML) 

{
  "Email": 0,
  "Push": 0,
  "SearchString": "ABC",
  "Type": 0
}

Example XML Response (switch to JSON) 

<SavedFavouriteResponse xmlns="http://api.trademe.co.nz/v1">
  <SearchId>123</SearchId>
  <Response>ABC</Response>
  <Saved>false</Saved>
  <FavouriteType>None</FavouriteType>
</SavedFavouriteResponse>

Example JSON Response (switch to XML) 

{
  "SearchId": 123,
  "Response": "ABC",
  "Saved": false,
  "FavouriteType": 0
}