# Trade Me API scraper (New Zealand) - search Trade Me marketplace auctions and Buy Now listings, used cars and property for sale or rent, full listing records with current bid, Buy Now and reserve status, closing time, shipping options, seller feedback, categories and suggestions. Prices in NZD. No account, no browser.

> Search Trade Me marketplace listings by keyword, category or seller: listing id, title, the current bid, start price, Buy Now price and what the headline price is, bid count, reserve met or not, closing time, condition, region and suburb, pick-up and free shipping, suggested shipping price, was-price and discount, and the paid upgrades each listing bought. Sponsored listings are separated. Filter by condition, Buy Now, shipping, clearance, region, price (with a category), $1 reserve; sort by best match, price, Buy Now price, most bids, latest, closing soon, title or discount.
> ReefAPI engine `trademe` · 8 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/trademe/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /trademe/v1/search — 1 credit
Search Trade Me marketplace listings by keyword, category or seller: listing id, title, the current bid, start price, Buy Now price and what the headline price is, bid count, reserve met or not, closing time, condition, region and suburb, pick-up and free shipping, suggested shipping price, was-price and discount, and the paid upgrades each listing bought. Sponsored listings are separated. Filter by condition, Buy Now, shipping, clearance, region, price (with a category), $1 reserve; sort by best match, price, Buy Now price, most bids, latest, closing soon, title or discount.

**Parameters:**
- `query` (string, optional) — Keyword. Optional when a category or seller_id is given.
- `category` (string, optional) — Trade Me category number (0005-0380- = Sports > Cycling). Every row returns category.number; `categories` walks the tree. Required for price_min/price_max.
- `condition` (enum, optional) — New or used items. [one of: new, used]
- `buy_now_only` (boolean, optional) — Only listings with a Buy Now price (includes auctions that also offer one).
- `shipping` (enum, optional) — Free shipping, or pick-up available. [one of: free, pickup]
- `clearance` (enum, optional) — Clearance listings, or listings on sale with a was-price. [one of: clearance, on_sale]
- `region` (enum, optional) — Where the seller is located (Trade Me's region list). [one of: northland, auckland, waikato, bay_of_plenty, gisborne, hawkes_bay, taranaki, whanganui, manawatu, wairarapa, wellington, nelson_bays, marlborough, west_coast, canterbury, timaru_oamaru, otago, southland, international]
- `price_min` (number, optional) — Lowest price, NZD.
- `price_max` (number, optional) — Highest price, NZD.
- `dollar_reserve_only` (boolean, optional) — Only $1 reserve auctions. Works with query, region, condition, shipping and sort; not with category.
- `seller_id` (integer, optional) — Only this member's listings (every listing record returns seller.member_id).
- `sort` (enum, optional, default "relevance") — Order of results. [one of: relevance, featured_first, price_asc, price_desc, buy_now_asc, buy_now_desc, most_bids, newest, closing_soon, title, largest_discount]
- `page` (integer, optional, default 1) — Result page, 1-based.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50). Sponsored rows are extra.
- `include_sponsored` (boolean, optional, default false) — Also return the sponsored listings Trade Me injects into every page, flagged sponsored=true. They are left out by default and counted in sponsored_dropped.
- `include_fallback_results` (boolean, optional, default false) — If no listing on the page mentions any query word, the page is returned empty with fallback_results_dropped; true also returns those rows in fallback_results.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** results[]{listing_id, title, subtitle, url, vertical (marketplace|motors|property), listing_type (auction|buy_now|classified), category{number, path}, price (number, NZD), price_type (current_bid|start_price|buy_now|asking|asking_or_near_offer|enquiries_over|rent_per_week|null), price_display (the site's own text), currency, start_price, current_bid, minimum_next_bid, buy_now_price, asking_price, rent_per_week, was_price, discount_percent, bid_count (auctions; null otherwise), reserve_state (no_reserve|met|not_met|not_applicable), reserve_met, is_clearance, condition (new|used, marketplace only), region, suburb, start_date, search_index_end_date (closing time as the search index publishes it - one hour later than the listing record after a NZ daylight-saving change; listing.end_date is the record's), image, images[], seller_id, is_super_seller, is_dealer, dealer_name, pickup (allowed|required|not_available), free_shipping, suggested_shipping{price, destination, delivery_days_min, delivery_days_max, rural}, has_afterpay, has_ping, has_variants, is_featured, is_super_featured, has_gallery, is_bold, is_highlighted (paid upgrades), sponsored, vehicle{…} (motors), property{…} (property)}, count (organic rows), total_results, page, limit, has_more, sponsored_count, sponsored_dropped, fallback_results_dropped, did_you_mean, category_facets[]{number, id, name, count}, filters{}, query

**Example request body:**
```json
{
  "query": "bike",
  "limit": 20
}
```

### POST /trademe/v1/listing — 1 credit
One Trade Me listing in full, live or closed: title, description, every photo, the start price, current bid, minimum next bid, Buy Now price or asking price, bid count and bid history amounts, reserve met or not, closing time, time left, status (active or closed) and how a closed auction ended, quantity left, condition, brand, SKU and attributes, shipping options with prices, pick-up, payment methods, questions and answers, the seller's feedback score and positive percentage, the store, car dealer or real-estate agency, and car or property facts.

**Parameters:**
- `listing_id` (string, required) — Trade Me listing number (from a search row, or the number at the end of a listing URL). A full listing URL works.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** listing{listing_id, title, subtitle, url, vertical, listing_type, status (active|closed), closed_result (no_bids|reserve_not_met|highest_bid_met_reserve, closed auctions), time_left_seconds, start_date, end_date, as_at, category{number, name, path}, price, price_type, price_display, currency, start_price, current_bid, minimum_next_bid, buy_now_price, asking_price, rent_per_week, was_price, discount_percent, bid_count, reserve_state, reserve_met, is_clearance, condition, quantity_remaining, available_to_buy, sku, gtin, brand, manufacturer_code, description, images[], image, attributes{}, view_count, bidders_and_watchers, unanswered_question_count, region, suburb, location{latitude, longitude, accuracy} (business sellers and property only), pickup, shipping_options[]{type, type_code, price, method}, cheapest_shipping_price, payment_methods[], buyer_protection, seller{member_id, nickname, member_since, feedback_score, positive_count, negative_count, positive_percent, address_verified, authenticated, in_trade, suburb, region}, store{…}, dealership{…}, agency{…}, is_super_seller, is_featured, is_super_featured, has_gallery, is_bold, is_highlighted, bids[]{amount, date, is_buy_now}, bid_history_count, questions[]{question, asked_at, answer, answered_at, is_seller_comment}, question_count, vehicle{…}, property{…}, rating (null), review_count (null), rating_scale (null)}

### POST /trademe/v1/cars/search — 1 credit
Used and new cars on Trade Me Motors: make, model, year, odometer, fuel, transmission, body style, engine size, owners, import history, WoF and registration expiry, plate and VIN, asking price or auction bids, dealer or private seller. Filter by make, model, year, odometer, price, body style, fuel, transmission, condition, dealer/private, auction/classified and region.

**Parameters:**
- `query` (string, optional) — Optional keyword.
- `make` (string, optional) — Car make (any capitalisation).
- `model` (string, optional) — Model of that make (needs make).
- `year_min` (integer, optional) — Oldest year.
- `year_max` (integer, optional) — Newest year.
- `odometer_min` (integer, optional) — Lowest km.
- `odometer_max` (integer, optional) — Highest km.
- `price_min` (number, optional) — Lowest price, NZD.
- `price_max` (number, optional) — Highest price, NZD.
- `body_style` (enum, optional) — Body style. [one of: convertible, coupe, hatchback, sedan, station_wagon, suv, ute, van]
- `fuel_type` (enum, optional) — Fuel. [one of: petrol, diesel, hybrid, plug_in_hybrid, electric, lpg, alternative]
- `transmission` (enum, optional) — Gearbox. [one of: manual, automatic]
- `vehicle_condition` (enum, optional) — New, used, classic, ex-demo or certified pre-owned. [one of: new, used, classic, ex_demo, certified_pre_owned]
- `seller_type` (enum, optional) — Private sellers or dealers. [one of: private, dealer]
- `listing_format` (enum, optional) — Auctions or classified ads. [one of: auction, classified]
- `region` (enum, optional) — Where the seller is located (Trade Me's region list). [one of: northland, auckland, waikato, bay_of_plenty, gisborne, hawkes_bay, taranaki, whanganui, manawatu, wairarapa, wellington, nelson_bays, marlborough, west_coast, canterbury, timaru_oamaru, otago, southland, international]
- `sort` (enum, optional) — Order of results. Without it the site's own default order is used. [one of: featured_first, price_asc, price_desc, buy_now_asc, buy_now_desc, oldest_vehicle, newest_vehicle, lowest_km, highest_km, newest, closing_soon]
- `page` (integer, optional, default 1) — Result page, 1-based.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50). Sponsored rows are extra.
- `include_sponsored` (boolean, optional, default false) — Also return the sponsored listings Trade Me injects into every page, flagged sponsored=true. They are left out by default and counted in sponsored_dropped.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** results[]{listing_id, title, subtitle, url, vertical (marketplace|motors|property), listing_type (auction|buy_now|classified), category{number, path}, price (number, NZD), price_type (current_bid|start_price|buy_now|asking|asking_or_near_offer|enquiries_over|rent_per_week|null), price_display (the site's own text), currency, start_price, current_bid, minimum_next_bid, buy_now_price, asking_price, rent_per_week, was_price, discount_percent, bid_count (auctions; null otherwise), reserve_state (no_reserve|met|not_met|not_applicable), reserve_met, is_clearance, condition (new|used, marketplace only), region, suburb, start_date, search_index_end_date (closing time as the search index publishes it - one hour later than the listing record after a NZ daylight-saving change; listing.end_date is the record's), image, images[], seller_id, is_super_seller, is_dealer, dealer_name, pickup (allowed|required|not_available), free_shipping, suggested_shipping{price, destination, delivery_days_min, delivery_days_max, rural}, has_afterpay, has_ping, has_variants, is_featured, is_super_featured, has_gallery, is_bold, is_highlighted (paid upgrades), sponsored, vehicle{make, model, model_detail, year, odometer_km, fuel, transmission, body_style, engine_size_cc, cylinders, doors, seats, owners, exterior_colour, import_history, is_4wd, number_plate, vin, wof_expires, registration_expires, on_road_costs_included}, property{…} (property)}, count (organic rows), total_results, page, limit, has_more, sponsored_count, sponsored_dropped, fallback_results_dropped, did_you_mean, category_facets[]{number, id, name, count}, filters{}

**Example request body:**
```json
{
  "make": "Toyota",
  "limit": 20
}
```

### POST /trademe/v1/real_estate/search — 1 credit
Residential property on Trade Me Property, for sale or for rent: address, suburb, district, region, property type, bedrooms, bathrooms, land and floor area, parking, how it is being sold (asking price, enquiries over, negotiation, auction, tender, deadline sale) or the weekly rent, available date, agency and open homes. Filter by region, district, price, bedrooms, bathrooms, property type and sale method.

**Parameters:**
- `purpose` (enum, optional, default "sale") — For sale (default) or for rent. Rent prices are NZD per week. [one of: sale, rent]
- `query` (string, optional) — Optional keyword.
- `region` (enum, optional) — Region of the property. [one of: northland, auckland, waikato, bay_of_plenty, gisborne, hawkes_bay, taranaki, manawatu_whanganui, wellington, nelson_tasman, marlborough, west_coast, canterbury, otago, southland]
- `district_id` (integer, optional) — Trade Me district number inside the region (7 = Auckland City). Needs region.
- `price_min` (number, optional) — Lowest price, NZD (per week for rent).
- `price_max` (number, optional) — Highest price, NZD (per week for rent).
- `bedrooms_min` (integer, optional) — Fewest bedrooms (0 = studio).
- `bedrooms_max` (integer, optional) — Most bedrooms.
- `bathrooms_min` (integer, optional) — Fewest bathrooms.
- `bathrooms_max` (integer, optional) — Most bathrooms.
- `property_type` (enum, optional) — Property type. lifestyle_bare_land, lifestyle_dwelling and section exist for sale only; car_park for rent only. [one of: apartment, house, lifestyle_bare_land, lifestyle_dwelling, section, townhouse, unit, car_park]
- `sales_method` (enum, optional) — How the property is being sold (for sale only). [one of: price_displayed, negotiation, auction, tender, deadline_sale]
- `sort` (enum, optional, default "relevance") — Order of results. [one of: relevance, price_asc, price_desc, newest, earliest_open_home]
- `page` (integer, optional, default 1) — Result page, 1-based.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50). Sponsored rows are extra.
- `include_sponsored` (boolean, optional, default false) — Also return the sponsored listings Trade Me injects into every page, flagged sponsored=true. They are left out by default and counted in sponsored_dropped.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** results[]{listing_id, title, subtitle, url, vertical (marketplace|motors|property), listing_type (auction|buy_now|classified), category{number, path}, price (number, NZD), price_type (current_bid|start_price|buy_now|asking|asking_or_near_offer|enquiries_over|rent_per_week|null), price_display (the site's own text), currency, start_price, current_bid, minimum_next_bid, buy_now_price, asking_price, rent_per_week, was_price, discount_percent, bid_count (auctions; null otherwise), reserve_state (no_reserve|met|not_met|not_applicable), reserve_met, is_clearance, condition (new|used, marketplace only), region, suburb, start_date, search_index_end_date (closing time as the search index publishes it - one hour later than the listing record after a NZ daylight-saving change; listing.end_date is the record's), image, images[], seller_id, is_super_seller, is_dealer, dealer_name, pickup (allowed|required|not_available), free_shipping, suggested_shipping{price, destination, delivery_days_min, delivery_days_max, rural}, has_afterpay, has_ping, has_variants, is_featured, is_super_featured, has_gallery, is_bold, is_highlighted (paid upgrades), sponsored, vehicle{…} (motors), property{address, suburb, district, region, property_type, bedrooms, bathrooms, lounges, parking, total_parking, land_area_m2, floor_area_m2, rateable_value, rent_per_week, available_from (YYYY-MM-DD), max_tenants, sale_method, agency{id, name}, agency_reference, open_homes[]{start, end}, location{latitude, longitude, accuracy}}}, count (organic rows), total_results, page, limit, has_more, sponsored_count, sponsored_dropped, fallback_results_dropped, did_you_mean, category_facets[]{number, id, name, count}, filters{}

### POST /trademe/v1/seller_listings — 1 credit
A Trade Me member's profile and current marketplace listings: nickname, member since, feedback score, positive and negative counts and positive percentage, address verified, in-trade flag, store, then their listings with the same row fields and sorts as search.

**Parameters:**
- `seller_id` (integer, required) — Trade Me member number (every listing record returns seller.member_id; rows return seller_id).
- `sort` (enum, optional, default "relevance") — Order of results. [one of: relevance, featured_first, price_asc, price_desc, buy_now_asc, buy_now_desc, most_bids, newest, closing_soon, title, largest_discount]
- `page` (integer, optional, default 1) — Result page, 1-based.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50). Sponsored rows are extra.
- `include_sponsored` (boolean, optional, default false) — Also return the sponsored listings Trade Me injects into every page, flagged sponsored=true. They are left out by default and counted in sponsored_dropped.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** seller{member_id, nickname, member_since, feedback_score, positive_count, negative_count, positive_percent, address_verified, authenticated, in_trade, suburb, region, store{…}, biography, enabled}, results[]{listing_id, title, subtitle, url, vertical (marketplace|motors|property), listing_type (auction|buy_now|classified), category{number, path}, price (number, NZD), price_type (current_bid|start_price|buy_now|asking|asking_or_near_offer|enquiries_over|rent_per_week|null), price_display (the site's own text), currency, start_price, current_bid, minimum_next_bid, buy_now_price, asking_price, rent_per_week, was_price, discount_percent, bid_count (auctions; null otherwise), reserve_state (no_reserve|met|not_met|not_applicable), reserve_met, is_clearance, condition (new|used, marketplace only), region, suburb, start_date, search_index_end_date (closing time as the search index publishes it - one hour later than the listing record after a NZ daylight-saving change; listing.end_date is the record's), image, images[], seller_id, is_super_seller, is_dealer, dealer_name, pickup (allowed|required|not_available), free_shipping, suggested_shipping{price, destination, delivery_days_min, delivery_days_max, rural}, has_afterpay, has_ping, has_variants, is_featured, is_super_featured, has_gallery, is_bold, is_highlighted (paid upgrades), sponsored, vehicle{…} (motors), property{…} (property)}, count (organic rows), total_results, page, limit, has_more, sponsored_count, sponsored_dropped, fallback_results_dropped, did_you_mean, category_facets[]{number, id, name, count}, filters{}

### POST /trademe/v1/seller_feedback — 1 credit
Feedback left for a Trade Me member, newest first: positive or negative, the comment, date, whether a buyer or a seller left it, the listing and price it was for, and the member's reply.

**Parameters:**
- `seller_id` (integer, required) — Trade Me member number (every listing record returns seller.member_id; rows return seller_id).
- `page` (integer, optional, default 1) — Result page, 1-based.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50). Sponsored rows are extra.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** seller_id, feedback[]{feedback_id, type (positive|negative; null for other codes), type_code, text, date, left_by (buyer|seller), listing_id, purchase_price, response, responded_at}, count, total_results, page, has_more

### POST /trademe/v1/categories — 1 credit
The Trade Me category tree one level at a time: a category's number, name and path and its sub-categories, with whether each carries classified ads.

**Parameters:**
- `category` (string, optional) — Category number to open; omit for the top level.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** category{number, name, path, is_leaf}, children[]{number, name, path, is_leaf, has_classifieds}, count

### POST /trademe/v1/suggest — 1 credit
Trade Me's own search suggestions for the start of a keyword, with suggested categories.

**Parameters:**
- `query` (string, required) — The start of a keyword.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** query, suggestions[]{keyword, categories[]{id, name}}, count, category_suggestions[]{id, name, path[]}

**Example request body:**
```json
{
  "query": "bike"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=trademe
- Human docs page: https://reefapi.com/docs/trademe
- Overview page: https://reefapi.com/trademe-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt