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 Thumbnail
List List
Medium Medium
Gallery Gallery
Large Large
FullSize FullSize
JobSearchCard JobSearchCard
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 TotalCount
Page Integer Page
PageSize Integer PageSize
List Collection of <WatchlistItem> or null InnerList
ListingId Integer ListingId
Title String or null Title
Category String or null Category
StartPrice Number StartPrice
BuyNowPrice Number BuyNowPrice
StartDate DateTime StartDate
EndDate DateTime EndDate
MaxBidAmount Number MaxBidAmount
AsAt DateTime AsAt
CategoryPath String or null CategoryPath
PictureHref String or null PictureHref
PhotoId Integer PhotoId
HasPayNow Boolean HasPayNow
IsNew Boolean IsNew
RegionId Integer RegionId

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 Region
Suburb String or null Suburb
BidCount Integer BidCount
IsReserveMet Boolean IsReserveMet
HasReserve Boolean HasReserve
HasBuyNow Boolean HasBuyNow
Note String or null Note
NoteId Integer NoteId
NoteDate DateTime NoteDate
CategoryName String or null CategoryName
ReserveState Enumeration ReserveState
None 0 None
Met 1 Met
NotMet 2 NotMet
NotApplicable 3 NotApplicable
Attributes Collection of <Attribute> or null Attributes
Name String or null Name
DisplayName String or null DisplayName
Value String or null Value
IsClassified Boolean IsClassified
OpenHomes Collection of <OpenHome> or null OpenHomes
Start DateTime Start
End DateTime End
Subtitle String or null Subtitle
IsBuyNowOnly Boolean IsBuyNowOnly
RemainingGalleryPlusRelists Integer or null RemainingGalleryPlusRelists
MinimumNextBidAmount Number MinimumNextBidAmount
IsOnWatchList Boolean IsOnWatchList
GeographicLocation <GeographicLocation> or null GeographicLocation
Latitude Number Latitude
Longitude Number Longitude
Northing Integer Northing
Easting Integer Easting
Accuracy Enumeration Accuracy
None 0 None
Address 1 Address
Street 3 Street
Suburb 2 Suburb
AdminPinpoint 4 AdminPinpoint
PriceDisplay String or null PriceDisplay
HasAppliedForJob Boolean HasAppliedForJob
JobApplicationDate DateTime or null JobApplicationDate
IsClearance Boolean IsClearance
WasPrice Number or null WasPrice
PercentageOff Integer or null PercentageOff
Branding <Branding> or null Branding
LargeSquareLogo String or null LargeSquareLogo
LargeWideLogo String or null LargeWideLogo
LargeBannerURL String or null LargeBannerURL
ShortDescription String or null ShortDescription
Options Collection of <Option> or null Options
(This type has already been defined)
ListingGroupId Integer or null ListingGroupId
AdditionalData <AdditionalData> or null AdditionalData
BulletPoints Collection of String or null BulletPoints
Tags Collection of <Tag> or null Tags
Name String or null Name
PriceType Enumeration or null PriceType
AskingPrice 0 AskingPrice
PriceOnApplication 1 PriceOnApplication
ExcludingGST 2 ExcludingGST
ListingPlatform Enumeration ListingPlatform
Unset 0 Unset
TradeMe 1 TradeMe
Koru 2 Koru
IsDealer Boolean IsDealer
IsLeading Boolean IsLeading
IsOutbid Boolean IsOutbid
IsInCart Boolean IsInCart
MemberBidShippingOption Integer MemberBidShippingOption
FoundCategories Collection of <FoundCategory> or null FoundCategories
Count Integer Count
Category String or null Category
Name String or null Name
IsRestricted Boolean IsRestricted
CategoryId Integer CategoryId
IsLeaf Boolean IsLeaf

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
    }
  ]
}