Website logo

Retrieve your watchlist

Retrieves a list of items on the authenticated user's watchlist.

URL: https://api.trademe.co.nz/v1/MyTradeMe/Watchlist/{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)

A filter on the results.

AllReturns all items from the watchlist.
ClosingTodayReturns listings that are closing today.
LeadingBidsReturns listings where the authenticated user leads the bidding.
ReserveMetReturns listings where highest bid is above the reserve price or the reserve price equals the start price (= no reserve).
ReserveNotMetReturns only listings where the reserve has not been met.
OpenHomesReturns only listings that have an open home. Listings that have multiple open homes will be returned multiple times. Results are ordered chronologically by open home start time.
file_format Enumeration (required) The format of the response.
xml Serialize responses into XML.
json Serialize responses into JSON.

Query String parameters

category String (optional)

The ID of a category to use as a filter. Only the items that reside within the given category will be returned.
category_ids String (optional)

Comma separated list of category Ids. Only the items that reside within the given categories and their sub-categories will be returned. Note: 1. This parameter overrides the category query parameter. 2. When this parameter is used, the FoundCategories property in the response will be empty.
page Integer (optional)

The page number of the set of results to return, starting from 1. Defaults to 1.
photo_size Enumeration (optional)

The size of the images to return in the results. Defaults to Thumbnail.
Thumbnail

The thumbnail sized photo (always 85x64, with white borders).
List

The list view sized photo (scaled down to fit 160x120).
Medium

The medium sized photo (scaled down to fit 175x175).
Gallery

The gallery sized photo (scaled down to fit 233x176).
Large

The large sized photo (scaled down to fit 352x264).
FullSize

The full sized photo (scaled down to fit 670x502).
JobSearchCard

The SearchCard photo (scaled down to fit 670x502).
rows Integer (optional)

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

Returns

<Watchlist>

The Watchlist for the authenticated user.

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 <WatchlistItem> or null

A list of the results in the current page.
ListingId Long Integer

The ID of the listing.
Title String or null

The listing title.
Category String or null

The listing category.
StartPrice Number

The start price.
BuyNowPrice Number

The Buy Now price.
StartDate DateTime

The date the listing was created.
EndDate DateTime

The date the listing will end.
MaxBidAmount Number

The current leading bid amount.
AsAt DateTime

The date and time the response was generated on the server.
CategoryPath String or null

The category path.
PictureHref String or null

The URL of the primary photo for the listing (if the listing has a photo). By default you'll get a thumbnail-sized photo, but you can control the size of the photo using the photo_size parameter.
PhotoId Long Integer

The ID of the primary photo for the listing (if the listing has a photo).
HasPayNow Boolean

Indicates whether the item has Pay Now.
IsNew Boolean

Indicates whether the item is marked as new.
RegionId Integer

The ID of the region where this item is located. In the general search, listing details and watchlist APIs this is the ID of the seller's region (using the two-tier region/suburb system), which means it might be inconsistent with the region name. In the property search API this is the ID of the property region, using the three-tier region/district/suburb system.

This field cannot cope with the two main geographical classification systems. Except for the property search API, it should not be used.

Region String or null

The name of the region where this item is located.
Suburb String or null

The name of the suburb where this item is located.
BidCount Integer

The number of bids on the item.
IsReserveMet Boolean

Indicates whether the item's reserve has been met.
HasReserve Boolean

Indicates whether the item has a reserve.
HasBuyNow Boolean

Indicates whether the item has Buy Now.
Note String or null

The note on an item.
NoteId Integer

The note id on an item.
NoteDate DateTime

The date of the note on an item.
CategoryName String or null

The display name of the category.
ReserveState Enumeration

The flag to display on an item.
None 0

There is no reserve on the item (i.e. the reserve price is the same as the starting price).
Met 1

The value of the highest bid has exceeded the reserve price.
NotMet 2

The value of the highest bid has not reached the reserve price.
NotApplicable 3

The listing cannot have a reserve because bidding is not allowed. This may be because it is a classified or because it is a Buy Now Only auction.
Attributes Collection of <Attribute> or null

The attributes for the item that are intended to be displayed on the UI.
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.
IsClassified Boolean

Indicates whether the item is a classified.
OpenHomes Collection of <OpenHome> or null

A collection of open home times for this listing. Only applies to open home listings.
Start DateTime

The date and time the open home is open for viewing. The date must be in the future and it must be less than 56 days from the current date. Specify dates in the UTC time zone.
End DateTime

The date and time the open home is no longer open for viewing. Must be the same day as Start.
Subtitle String or null

The subtitle, if present.
IsBuyNowOnly Boolean

Indicates whether or not this is a Buy Now Only listing.
RemainingGalleryPlusRelists Integer or null

The number of times the item can be relisted and get the gallery promotion for free. This value is only present if you are the seller and the listing had the gallery promotion applied due to the gallery plus promotion. Note that for this field, a value of zero is not the same as if the field is missing (a value of zero means gallery plus is in effect whereas if the field is missing it means that you are not the seller or gallery plus is not in effect).
MinimumNextBidAmount Number

The smallest amount that will be accepted for the next bid. Only applicable to auctions which allow bidding (i.e. not classifieds and not Buy Now Only auctions). You must still check for the "bid too small" error when using this value, as someone may make a bid after you have checked this value but before you have finished placing your bid.
IsOnWatchList Boolean

Indicates whether the item is on the authenticated member's watchlist.
GeographicLocation <GeographicLocation> or null

The geographic location (latitude and longitude) of a property.
Latitude Number

The latitude of the location, in degrees (WGS84).
Longitude Number

The longitude of the location, in degrees (WGS84).
Northing Integer

The northing of the location, in metres (NZTM).
Easting Integer

The easting of the location, in metres (NZTM).
Accuracy Enumeration

The accuracy of the geographic location (address, street or suburb).
None 0

The accuracy of the geographic location is not known.
Address 1

The geographic location is accurate to the address level.
Street 3

The geographic location is accurate to the street level.
Suburb 2

The geographic location is accurate to the suburb level.
AdminPinpoint 4

The geographic location is accurate to the AdminPinPoint level.
PriceDisplay String or null

The price, in a format suitable for displaying to the user. Some categories may have special pricing rules, e.g. properties may have "Price by negotiation".
HasAppliedForJob Boolean

Indicates whether the authenticated member has applied for the job. Only applies for job listings.
JobApplicationDate DateTime or null

The date and time of the member's most recent job application, if any. This field will only be populated if HasAppliedForJob is true.
IsClearance Boolean

This indicates that the listing is a clearance item. Clearance listings include listings with was/now pricing and general clearance stock.
WasPrice Number or null

The usual price that a product is sold at, or the price before it was marked down. This is always more than the Buy Now price for Auctions, or more than the asking price for Classifieds.This field will only be populated if IsClearance is true.
PercentageOff Integer or null

The percentage that a product has been discounted. This has been rounded for display purposes. This field will only be populated if IsClearance is true.
Branding <Branding> or null

A list of branding images associated with this listing.
LargeSquareLogo String or null

A large square branding image with dimensions of 480x480.
LargeWideLogo String or null

A large rectangular branding image with dimensions of 480x200.
LargeBannerURL String or null

The url of a larger version of the logo
ShortDescription String or null

Short description of a listing. This is Jobs and Services specfic.
Options Collection of <Option> or null

The combination of variant options that this variant represents.
(This type has already been defined)
ListingGroupId Long Integer or null

The identifier of the group of related multi-variant listings. Blank if the listing is not multi-variant
AdditionalData <AdditionalData> or null

Structured information for Listing Additional Data
BulletPoints Collection of String or null

The bullet points for display in the search results
Tags Collection of <Tag> or null

The tags for display in the search results
Name String or null

The name of the tag
PriceType Enumeration or null

Indicates the price type of boat and farming machinery listings
AskingPrice 0

Asking Price.
PriceOnApplication 1

Price On Application.
ExcludingGST 2

Excluding GST.
ListingPlatform Enumeration

The backend platform that controls the listing.
Unset 0

The platform has not been set.
TradeMe 1

The listing is controlled by Trade Me.
Koru 2

The listing is controlled by Koru.
IsDealer Boolean

Indicates whether the auction was listed by a dealer.
IsLeading Boolean

Indicates whether the authenticated user is leading the bidding.
IsOutbid Boolean

Indicates whether the authenticated user has been outbid. This will be false if the authenticated user has not made any bids.
IsInCart Boolean

Indicates if the item is also in the members cart.
MemberBidShippingOption Integer

If member has placed a bid, the watcher's selected shipping option for the listing
FoundCategories Collection of <FoundCategory> or null

A collection of suggested categories and the number of search results in each category.
Count Integer

The number of results that were found in this category.
Category String or null

The category identifier string in the form nnnn- (e.g. "0344-3357-6420-").
Name String or null

The name of the category (e.g. "Blackberry").
IsRestricted Boolean

True if the category is restricted. All R18 categories are restricted by default.
CategoryId Integer

The category id (e.g. 6420).
IsLeaf Boolean

True if the category is a leaf category

Example XML Response (switch to JSON) 

<Watchlist xmlns="http://api.trademe.co.nz/v1">
  <TotalCount>123</TotalCount>
  <Page>123</Page>
  <PageSize>123</PageSize>
  <List>
    <WatchlistItem>
      <ListingId>123</ListingId>
      <Title>ABC</Title>
      <Category>ABC</Category>
      <StartPrice>123.0</StartPrice>
      <BuyNowPrice>123.0</BuyNowPrice>
      <StartDate>2018-01-01T00:00:00Z</StartDate>
      <EndDate>2018-01-01T00:00:00Z</EndDate>
      <MaxBidAmount>123.0</MaxBidAmount>
      <AsAt>2018-01-01T00:00:00Z</AsAt>
      <CategoryPath>ABC</CategoryPath>
      <PictureHref>ABC</PictureHref>
      <PhotoId>123</PhotoId>
      <HasPayNow>false</HasPayNow>
      <IsNew>false</IsNew>
      <RegionId>123</RegionId>
      <Region>ABC</Region>
      <Suburb>ABC</Suburb>
      <BidCount>123</BidCount>
      <IsReserveMet>false</IsReserveMet>
      <HasReserve>false</HasReserve>
      <HasBuyNow>false</HasBuyNow>
      <Note>ABC</Note>
      <NoteId>123</NoteId>
      <NoteDate>2018-01-01T00:00:00Z</NoteDate>
      <CategoryName>ABC</CategoryName>
      <ReserveState>None</ReserveState>
      <Attributes>
        <Attribute>
          <Name>ABC</Name>
          <DisplayName>ABC</DisplayName>
          <Value>ABC</Value>
        </Attribute>
        <Attribute>
          <Name>ABC</Name>
          <DisplayName>ABC</DisplayName>
          <Value>ABC</Value>
        </Attribute>
      </Attributes>
      <IsClassified>false</IsClassified>
      <OpenHomes>
        <OpenHome>
          <Start>2018-01-01T00:00:00Z</Start>
          <End>2018-01-01T00:00:00Z</End>
        </OpenHome>
        <OpenHome>
          <Start>2018-01-01T00:00:00Z</Start>
          <End>2018-01-01T00:00:00Z</End>
        </OpenHome>
      </OpenHomes>
      <Subtitle>ABC</Subtitle>
      <IsBuyNowOnly>false</IsBuyNowOnly>
      <RemainingGalleryPlusRelists>123</RemainingGalleryPlusRelists>
      <MinimumNextBidAmount>123.0</MinimumNextBidAmount>
      <IsOnWatchList>false</IsOnWatchList>
      <GeographicLocation>
        <Latitude>123.0</Latitude>
        <Longitude>123.0</Longitude>
        <Northing>123</Northing>
        <Easting>123</Easting>
        <Accuracy>None</Accuracy>
      </GeographicLocation>
      <PriceDisplay>ABC</PriceDisplay>
      <HasAppliedForJob>false</HasAppliedForJob>
      <JobApplicationDate>2018-01-01T00:00:00Z</JobApplicationDate>
      <IsClearance>false</IsClearance>
      <WasPrice>123.0</WasPrice>
      <PercentageOff>123</PercentageOff>
      <Branding>
        <LargeSquareLogo>ABC</LargeSquareLogo>
        <LargeWideLogo>ABC</LargeWideLogo>
        <LargeBannerURL>ABC</LargeBannerURL>
      </Branding>
      <ShortDescription>ABC</ShortDescription>
      <Options>
        <Option />
        <Option />
      </Options>
      <ListingGroupId>123</ListingGroupId>
      <AdditionalData>
        <BulletPoints>
          <BulletPoint>ABC</BulletPoint>
          <BulletPoint>ABC</BulletPoint>
        </BulletPoints>
        <Tags>
          <Tag>
            <Name>ABC</Name>
          </Tag>
          <Tag>
            <Name>ABC</Name>
          </Tag>
        </Tags>
      </AdditionalData>
      <PriceType>AskingPrice</PriceType>
      <ListingPlatform>Unset</ListingPlatform>
      <IsDealer>false</IsDealer>
      <IsLeading>false</IsLeading>
      <IsOutbid>false</IsOutbid>
      <IsInCart>false</IsInCart>
      <MemberBidShippingOption>123</MemberBidShippingOption>
    </WatchlistItem>
    <WatchlistItem>
      <ListingId>123</ListingId>
      <Title>ABC</Title>
      <Category>ABC</Category>
      <StartPrice>123.0</StartPrice>
      <BuyNowPrice>123.0</BuyNowPrice>
      <StartDate>2018-01-01T00:00:00Z</StartDate>
      <EndDate>2018-01-01T00:00:00Z</EndDate>
      <MaxBidAmount>123.0</MaxBidAmount>
      <AsAt>2018-01-01T00:00:00Z</AsAt>
      <CategoryPath>ABC</CategoryPath>
      <PictureHref>ABC</PictureHref>
      <PhotoId>123</PhotoId>
      <HasPayNow>false</HasPayNow>
      <IsNew>false</IsNew>
      <RegionId>123</RegionId>
      <Region>ABC</Region>
      <Suburb>ABC</Suburb>
      <BidCount>123</BidCount>
      <IsReserveMet>false</IsReserveMet>
      <HasReserve>false</HasReserve>
      <HasBuyNow>false</HasBuyNow>
      <Note>ABC</Note>
      <NoteId>123</NoteId>
      <NoteDate>2018-01-01T00:00:00Z</NoteDate>
      <CategoryName>ABC</CategoryName>
      <ReserveState>None</ReserveState>
      <Attributes>
        <Attribute>
          <Name>ABC</Name>
          <DisplayName>ABC</DisplayName>
          <Value>ABC</Value>
        </Attribute>
        <Attribute>
          <Name>ABC</Name>
          <DisplayName>ABC</DisplayName>
          <Value>ABC</Value>
        </Attribute>
      </Attributes>
      <IsClassified>false</IsClassified>
      <OpenHomes>
        <OpenHome>
          <Start>2018-01-01T00:00:00Z</Start>
          <End>2018-01-01T00:00:00Z</End>
        </OpenHome>
        <OpenHome>
          <Start>2018-01-01T00:00:00Z</Start>
          <End>2018-01-01T00:00:00Z</End>
        </OpenHome>
      </OpenHomes>
      <Subtitle>ABC</Subtitle>
      <IsBuyNowOnly>false</IsBuyNowOnly>
      <RemainingGalleryPlusRelists>123</RemainingGalleryPlusRelists>
      <MinimumNextBidAmount>123.0</MinimumNextBidAmount>
      <IsOnWatchList>false</IsOnWatchList>
      <GeographicLocation>
        <Latitude>123.0</Latitude>
        <Longitude>123.0</Longitude>
        <Northing>123</Northing>
        <Easting>123</Easting>
        <Accuracy>None</Accuracy>
      </GeographicLocation>
      <PriceDisplay>ABC</PriceDisplay>
      <HasAppliedForJob>false</HasAppliedForJob>
      <JobApplicationDate>2018-01-01T00:00:00Z</JobApplicationDate>
      <IsClearance>false</IsClearance>
      <WasPrice>123.0</WasPrice>
      <PercentageOff>123</PercentageOff>
      <Branding>
        <LargeSquareLogo>ABC</LargeSquareLogo>
        <LargeWideLogo>ABC</LargeWideLogo>
        <LargeBannerURL>ABC</LargeBannerURL>
      </Branding>
      <ShortDescription>ABC</ShortDescription>
      <Options>
        <Option />
        <Option />
      </Options>
      <ListingGroupId>123</ListingGroupId>
      <AdditionalData>
        <BulletPoints>
          <BulletPoint>ABC</BulletPoint>
          <BulletPoint>ABC</BulletPoint>
        </BulletPoints>
        <Tags>
          <Tag>
            <Name>ABC</Name>
          </Tag>
          <Tag>
            <Name>ABC</Name>
          </Tag>
        </Tags>
      </AdditionalData>
      <PriceType>AskingPrice</PriceType>
      <ListingPlatform>Unset</ListingPlatform>
      <IsDealer>false</IsDealer>
      <IsLeading>false</IsLeading>
      <IsOutbid>false</IsOutbid>
      <IsInCart>false</IsInCart>
      <MemberBidShippingOption>123</MemberBidShippingOption>
    </WatchlistItem>
  </List>
  <FoundCategories>
    <FoundCategory>
      <Count>123</Count>
      <Category>ABC</Category>
      <Name>ABC</Name>
      <IsRestricted>false</IsRestricted>
      <CategoryId>123</CategoryId>
      <IsLeaf>false</IsLeaf>
    </FoundCategory>
    <FoundCategory>
      <Count>123</Count>
      <Category>ABC</Category>
      <Name>ABC</Name>
      <IsRestricted>false</IsRestricted>
      <CategoryId>123</CategoryId>
      <IsLeaf>false</IsLeaf>
    </FoundCategory>
  </FoundCategories>
</Watchlist>

Example JSON Response (switch to XML) 

{
  "TotalCount": 123,
  "Page": 123,
  "PageSize": 123,
  "List": [
    {
      "ListingId": 123,
      "Title": "ABC",
      "Category": "ABC",
      "StartPrice": 123.0,
      "BuyNowPrice": 123.0,
      "StartDate": "\/Date(1514764800)\/",
      "EndDate": "\/Date(1514764800)\/",
      "MaxBidAmount": 123.0,
      "AsAt": "\/Date(1514764800)\/",
      "CategoryPath": "ABC",
      "PictureHref": "ABC",
      "PhotoId": 123,
      "HasPayNow": false,
      "IsNew": false,
      "RegionId": 123,
      "Region": "ABC",
      "Suburb": "ABC",
      "BidCount": 123,
      "IsReserveMet": false,
      "HasReserve": false,
      "HasBuyNow": false,
      "Note": "ABC",
      "NoteId": 123,
      "NoteDate": "\/Date(1514764800)\/",
      "CategoryName": "ABC",
      "ReserveState": 0,
      "Attributes": [
        {
          "Name": "ABC",
          "DisplayName": "ABC",
          "Value": "ABC"
        },
        {
          "Name": "ABC",
          "DisplayName": "ABC",
          "Value": "ABC"
        }
      ],
      "IsClassified": false,
      "OpenHomes": [
        {
          "Start": "\/Date(1514764800)\/",
          "End": "\/Date(1514764800)\/"
        },
        {
          "Start": "\/Date(1514764800)\/",
          "End": "\/Date(1514764800)\/"
        }
      ],
      "Subtitle": "ABC",
      "IsBuyNowOnly": false,
      "RemainingGalleryPlusRelists": 123,
      "MinimumNextBidAmount": 123.0,
      "IsOnWatchList": false,
      "GeographicLocation": {
        "Latitude": 123.0,
        "Longitude": 123.0,
        "Northing": 123,
        "Easting": 123,
        "Accuracy": 0
      },
      "PriceDisplay": "ABC",
      "HasAppliedForJob": false,
      "JobApplicationDate": "\/Date(1514764800)\/",
      "IsClearance": false,
      "WasPrice": 123.0,
      "PercentageOff": 123,
      "Branding": {
        "LargeSquareLogo": "ABC",
        "LargeWideLogo": "ABC",
        "LargeBannerURL": "ABC"
      },
      "ShortDescription": "ABC",
      "Options": [
        {
        },
        {
        }
      ],
      "ListingGroupId": 123,
      "AdditionalData": {
        "BulletPoints": [
          "ABC",
          "ABC"
        ],
        "Tags": [
          {
            "Name": "ABC"
          },
          {
            "Name": "ABC"
          }
        ]
      },
      "PriceType": 0,
      "ListingPlatform": 0,
      "IsDealer": false,
      "IsLeading": false,
      "IsOutbid": false,
      "IsInCart": false,
      "MemberBidShippingOption": 123
    },
    {
      "ListingId": 123,
      "Title": "ABC",
      "Category": "ABC",
      "StartPrice": 123.0,
      "BuyNowPrice": 123.0,
      "StartDate": "\/Date(1514764800)\/",
      "EndDate": "\/Date(1514764800)\/",
      "MaxBidAmount": 123.0,
      "AsAt": "\/Date(1514764800)\/",
      "CategoryPath": "ABC",
      "PictureHref": "ABC",
      "PhotoId": 123,
      "HasPayNow": false,
      "IsNew": false,
      "RegionId": 123,
      "Region": "ABC",
      "Suburb": "ABC",
      "BidCount": 123,
      "IsReserveMet": false,
      "HasReserve": false,
      "HasBuyNow": false,
      "Note": "ABC",
      "NoteId": 123,
      "NoteDate": "\/Date(1514764800)\/",
      "CategoryName": "ABC",
      "ReserveState": 0,
      "Attributes": [
        {
          "Name": "ABC",
          "DisplayName": "ABC",
          "Value": "ABC"
        },
        {
          "Name": "ABC",
          "DisplayName": "ABC",
          "Value": "ABC"
        }
      ],
      "IsClassified": false,
      "OpenHomes": [
        {
          "Start": "\/Date(1514764800)\/",
          "End": "\/Date(1514764800)\/"
        },
        {
          "Start": "\/Date(1514764800)\/",
          "End": "\/Date(1514764800)\/"
        }
      ],
      "Subtitle": "ABC",
      "IsBuyNowOnly": false,
      "RemainingGalleryPlusRelists": 123,
      "MinimumNextBidAmount": 123.0,
      "IsOnWatchList": false,
      "GeographicLocation": {
        "Latitude": 123.0,
        "Longitude": 123.0,
        "Northing": 123,
        "Easting": 123,
        "Accuracy": 0
      },
      "PriceDisplay": "ABC",
      "HasAppliedForJob": false,
      "JobApplicationDate": "\/Date(1514764800)\/",
      "IsClearance": false,
      "WasPrice": 123.0,
      "PercentageOff": 123,
      "Branding": {
        "LargeSquareLogo": "ABC",
        "LargeWideLogo": "ABC",
        "LargeBannerURL": "ABC"
      },
      "ShortDescription": "ABC",
      "Options": [
        {
        },
        {
        }
      ],
      "ListingGroupId": 123,
      "AdditionalData": {
        "BulletPoints": [
          "ABC",
          "ABC"
        ],
        "Tags": [
          {
            "Name": "ABC"
          },
          {
            "Name": "ABC"
          }
        ]
      },
      "PriceType": 0,
      "ListingPlatform": 0,
      "IsDealer": false,
      "IsLeading": false,
      "IsOutbid": false,
      "IsInCart": false,
      "MemberBidShippingOption": 123
    }
  ],
  "FoundCategories": [
    {
      "Count": 123,
      "Category": "ABC",
      "Name": "ABC",
      "IsRestricted": false,
      "CategoryId": 123,
      "IsLeaf": false
    },
    {
      "Count": 123,
      "Category": "ABC",
      "Name": "ABC",
      "IsRestricted": false,
      "CategoryId": 123,
      "IsLeaf": false
    }
  ]
}