# Yahoo! Auctions Japan API scraper (ヤフオク!) - search live auctions, sold prices (落札相場) with price statistics, full auction records with tax-included prices and shipping to any prefecture, seller inventory, categories and keyword suggestions. Prices in JPY. No account, no browser.

> Search live Yahoo! Auctions listings by keyword: auction id, title, image, the current price and buy-now price (tax included), bid and watch counts, end time, condition, category path, where it ships from, the shipping fee to your chosen prefecture, and the seller's id and positive rating. Filter by condition, individual/store/flea-market seller, auction or fixed price, price, buy-now price, free shipping, minimum bids, featured, new arrivals, prefecture, brand and category; sort by relevance, ending soon, newest, price, bids or buy-now price.
> ReefAPI engine `yahoo-auctions` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/yahoo-auctions/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 /yahoo-auctions/v1/search — 2 credits
Search live Yahoo! Auctions listings by keyword: auction id, title, image, the current price and buy-now price (tax included), bid and watch counts, end time, condition, category path, where it ships from, the shipping fee to your chosen prefecture, and the seller's id and positive rating. Filter by condition, individual/store/flea-market seller, auction or fixed price, price, buy-now price, free shipping, minimum bids, featured, new arrivals, prefecture, brand and category; sort by relevance, ending soon, newest, price, bids or buy-now price.

**Parameters:**
- `query` (string, required) — Keyword, in Japanese or English (both are matched, e.g. 'nintendo' also finds ニンテンドー).
- `category_id` (integer, optional) — Restrict to one category (and everything under it).
- `sort` (enum, optional, default "relevance") — Order. Only orderings measured to change the results are accepted. [one of: relevance, ending_soon, newest, price_asc, price_desc, most_bids, buy_now_price_asc, featured]
- `page` (integer, optional, default 1) — Result page, 1-based. Yahoo! Auctions serves results up to position 15,000 + limit; deeper pages are rejected. A page past the end returns an empty list.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50).
- `condition` (array, optional) — Item condition, Yahoo! Auctions' six grades. Several may be given, comma-separated. [one of: new, like_new, good, fair, worn, poor]
- `seller_type` (array, optional) — Who is selling. Several may be given, comma-separated. [one of: individual, store, fleamarket]
- `listing_format` (enum, optional) — Bidding auctions only, or fixed-price listings only. [one of: auction, fixed_price]
- `price_min` (integer, optional) — Lowest current (or sold) price, whole yen, tax included.
- `price_max` (integer, optional) — Highest current (or sold) price, whole yen, tax included.
- `buy_now_price_min` (integer, optional) — Lowest buy-now (即決) price, whole yen. Implies listings that have one.
- `buy_now_price_max` (integer, optional) — Highest buy-now (即決) price, whole yen.
- `has_buy_now` (boolean, optional) — Only listings with a buy-now (即決) price.
- `free_shipping` (boolean, optional) — Only listings with free shipping (送料無料).
- `min_bids` (integer, optional) — Only listings with at least this many bids.
- `featured_only` (boolean, optional) — Only paid featured listings (注目のオークション).
- `new_arrivals` (boolean, optional) — Only listings the site marks as new arrivals.
- `item_location` (string, optional) — Only listings shipped from these prefectures, by JIS number 1-47 (1 Hokkaido, 13 Tokyo, 23 Aichi, 27 Osaka, 40 Fukuoka), comma-separated.
- `shipping_destination` (integer, optional, default 13) — Prefecture (JIS 1-47) the shipping fees are quoted for. Default 13 (Tokyo), as on the site. Fees differ by destination.
- `brand_id` (integer, optional) — Yahoo! Auctions brand id (every row returns `brand_id`).
- `exclude_suspected_fakes` (boolean, optional, default true) — Drop listings Yahoo! Auctions flags as suspected counterfeits (the site's default).
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** items[]{auction_id, title, url, image, price (number, JPY, tax included - the current bid), buy_now_price (tax included, null when none), buy_now_price_excluding_tax, start_price_excluding_tax, currency, bid_count, watch_count, quantity, is_fixed_price, listing_type (individual|store|fleamarket), condition, condition_code, category{id, name, path[]{id, name}}, brand_id, catalog_id, item_location{code, name}, free_shipping, shipping_fee (to shipping_destination; null when the seller has not fixed one), shipping_fee_type, shipping_fee_timing (fixed|decided_after_sale|cash_on_delivery), buy_now_shipping_fee, seller{id, name (null on rows - the site masks it), url, positive_percent, is_store, is_best_store, city}, is_featured (paid placement), is_new_arrival, is_appraised, easy_payment, start_time, end_time, rating (null), review_count (null), rating_scale (null)}, count, total_results, page, has_more, filters{}, category_facets[]{id, name, count}, query

**Example request body:**
```json
{
  "query": "ポケモンカード",
  "limit": 20
}
```

### POST /yahoo-auctions/v1/sold/search — 5 credits
Sold Yahoo! Auctions listings (落札相場) from roughly the last six months: the price each item actually sold for (tax included), bid count, end date, condition and seller, plus the average, lowest and highest sold price across every match. Search by keyword, category or seller; filter by condition, seller type and price.

**Parameters:**
- `query` (string, optional) — Optional keyword to narrow the listing.
- `category_id` (integer, optional) — Restrict to one category (and everything under it).
- `seller_id` (string, optional) — Only this seller's sold listings (their sales history).
- `sort` (enum, optional, default "recently_ended") — Order of sold listings. [one of: recently_ended, oldest_ended, price_asc, price_desc, most_bids, fewest_bids]
- `page` (integer, optional, default 1) — Result page, 1-based. Yahoo! Auctions serves results up to position 15,000 + limit; deeper pages are rejected. A page past the end returns an empty list.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50).
- `condition` (array, optional) — Item condition, Yahoo! Auctions' six grades. Several may be given, comma-separated. [one of: new, like_new, good, fair, worn, poor]
- `seller_type` (array, optional) — Who is selling. Several may be given, comma-separated. [one of: individual, store, fleamarket]
- `price_min` (integer, optional) — Lowest current (or sold) price, whole yen, tax included.
- `price_max` (integer, optional) — Highest current (or sold) price, whole yen, tax included.
- `exclude_suspected_fakes` (boolean, optional, default true) — Drop listings Yahoo! Auctions flags as suspected counterfeits (the site's default).
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** items[]{sold_price, sold_at, auction_id, title, url, image, price (number, JPY, tax included - the current bid), buy_now_price (tax included, null when none), buy_now_price_excluding_tax, start_price_excluding_tax, currency, bid_count, watch_count, quantity, is_fixed_price, listing_type (individual|store|fleamarket), condition, condition_code, category{id, name, path[]{id, name}}, brand_id, catalog_id, item_location{code, name}, free_shipping, shipping_fee (to shipping_destination; null when the seller has not fixed one), shipping_fee_type, shipping_fee_timing (fixed|decided_after_sale|cash_on_delivery), buy_now_shipping_fee, seller{id, name (null on rows - the site masks it), url, positive_percent, is_store, is_best_store, city}, is_featured (paid placement), is_new_arrival, is_appraised, easy_payment, start_time, end_time, rating (null), review_count (null), rating_scale (null)}, count, total_results, page, has_more, filters{}, price_statistics{average, min, max, currency, over}, query

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

### POST /yahoo-auctions/v1/product/detail — 2 credits
One Yahoo! Auctions auction in full, live or ended: title, full description, every image, the current or final price tax included (with the pre-tax figure and tax rate for stores), start and buy-now price, bids, bidders, watchers, quantity, start/end time and time left, auto-extension, condition, category path, brand, item specifics, the seller (name, positive %, good/bad counts, store and verification badges, prefecture), shipping (who pays, methods and the fee to your chosen prefecture, handling time, anonymous delivery) and the returns policy.

**Parameters:**
- `auction_id` (string, required) — Yahoo! Auctions auction id (the code at the end of /jp/auction/<id>, e.g. k1244566600; 8-11 digits, usually with one leading letter). A full auction URL works.
- `shipping_destination` (integer, optional, default 13) — Prefecture (JIS 1-47) the shipping fees are quoted for. Default 13 (Tokyo), as on the site. Fees differ by destination.
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** item{auction_id, title, url, status (open|closed), is_ended, price (tax included), price_excluding_tax, tax_rate, start_price, buy_now_price, buy_now_price_excluding_tax, currency, bid_count, bidder_count, watch_count, quantity, start_time, end_time, time_left_seconds, auto_extension, early_end_allowed, price_negotiable, condition, condition_label, listing_type, description, images[], image, category{id, name, path[]}, brand{id, name, path[]}, product_name, catalog_id, item_specifics{}, gtin (null), seller{id, name, url, positive_percent, rating_score, good_count, bad_count, is_store, is_best_store, is_excellent_seller, identity_verified, fast_shipper, location{code, name}}, shipping{paid_by (seller|buyer), free_shipping, destination{code, name}, fee_to_destination, methods[]{name, fee, is_official, anonymous, tracking}, ships_within, ships_from, anonymous_delivery_available, worldwide}, returns{accepted, note}, store_platform, is_featured, questions_answered, rating (null), review_count (null), rating_scale (null)}

### POST /yahoo-auctions/v1/seller/listings — 2 credits
A Yahoo! Auctions seller's profile and live listings: display name, store or individual, rating total and positive ratio, identity verification, fast-shipper badge and profile message, then the seller's current auctions with the same row fields, filters and sorts as search.

**Parameters:**
- `seller_id` (string, required) — Seller id (the code in /seller/<id>). Every row returns it as `seller.id`. A seller page URL works.
- `query` (string, optional) — Optional keyword to narrow the listing.
- `sort` (enum, optional, default "relevance") — Order. Only orderings measured to change the results are accepted. [one of: relevance, ending_soon, newest, price_asc, price_desc, most_bids, buy_now_price_asc, featured]
- `page` (integer, optional, default 1) — Result page, 1-based. Yahoo! Auctions serves results up to position 15,000 + limit; deeper pages are rejected. A page past the end returns an empty list.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50).
- `condition` (array, optional) — Item condition, Yahoo! Auctions' six grades. Several may be given, comma-separated. [one of: new, like_new, good, fair, worn, poor]
- `seller_type` (array, optional) — Who is selling. Several may be given, comma-separated. [one of: individual, store, fleamarket]
- `listing_format` (enum, optional) — Bidding auctions only, or fixed-price listings only. [one of: auction, fixed_price]
- `price_min` (integer, optional) — Lowest current (or sold) price, whole yen, tax included.
- `price_max` (integer, optional) — Highest current (or sold) price, whole yen, tax included.
- `buy_now_price_min` (integer, optional) — Lowest buy-now (即決) price, whole yen. Implies listings that have one.
- `buy_now_price_max` (integer, optional) — Highest buy-now (即決) price, whole yen.
- `has_buy_now` (boolean, optional) — Only listings with a buy-now (即決) price.
- `free_shipping` (boolean, optional) — Only listings with free shipping (送料無料).
- `min_bids` (integer, optional) — Only listings with at least this many bids.
- `featured_only` (boolean, optional) — Only paid featured listings (注目のオークション).
- `new_arrivals` (boolean, optional) — Only listings the site marks as new arrivals.
- `item_location` (string, optional) — Only listings shipped from these prefectures, by JIS number 1-47 (1 Hokkaido, 13 Tokyo, 23 Aichi, 27 Osaka, 40 Fukuoka), comma-separated.
- `shipping_destination` (integer, optional, default 13) — Prefecture (JIS 1-47) the shipping fees are quoted for. Default 13 (Tokyo), as on the site. Fees differ by destination.
- `brand_id` (integer, optional) — Yahoo! Auctions brand id (every row returns `brand_id`).
- `exclude_suspected_fakes` (boolean, optional, default true) — Drop listings Yahoo! Auctions flags as suspected counterfeits (the site's default).
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** seller{id, name, url, is_store, store_url, rating_total, positive_percent, identity_verified, fast_shipper, profile_message, icon}, items[]{auction_id, title, url, image, price (number, JPY, tax included - the current bid), buy_now_price (tax included, null when none), buy_now_price_excluding_tax, start_price_excluding_tax, currency, bid_count, watch_count, quantity, is_fixed_price, listing_type (individual|store|fleamarket), condition, condition_code, category{id, name, path[]{id, name}}, brand_id, catalog_id, item_location{code, name}, free_shipping, shipping_fee (to shipping_destination; null when the seller has not fixed one), shipping_fee_type, shipping_fee_timing (fixed|decided_after_sale|cash_on_delivery), buy_now_shipping_fee, seller{id, name (null on rows - the site masks it), url, positive_percent, is_store, is_best_store, city}, is_featured (paid placement), is_new_arrival, is_appraised, easy_payment, start_time, end_time, rating (null), review_count (null), rating_scale (null)}, count, total_results, page, has_more, filters{}

### POST /yahoo-auctions/v1/category/products — 2 credits
Browse one Yahoo! Auctions category: the category's name, parent and sub-categories, then its live listings with the same row fields, filters and sorts as search (a keyword is optional).

**Parameters:**
- `category_id` (integer, required) — Yahoo! Auctions category id (the number in /category/list/<id>/). `categories` walks the tree; every row returns `category.id`.
- `query` (string, optional) — Optional keyword to narrow the listing.
- `sort` (enum, optional, default "relevance") — Order. Only orderings measured to change the results are accepted. [one of: relevance, ending_soon, newest, price_asc, price_desc, most_bids, buy_now_price_asc, featured]
- `page` (integer, optional, default 1) — Result page, 1-based. Yahoo! Auctions serves results up to position 15,000 + limit; deeper pages are rejected. A page past the end returns an empty list.
- `limit` (integer, optional, default 50) — Listings per page, 1-100 (default 50).
- `condition` (array, optional) — Item condition, Yahoo! Auctions' six grades. Several may be given, comma-separated. [one of: new, like_new, good, fair, worn, poor]
- `seller_type` (array, optional) — Who is selling. Several may be given, comma-separated. [one of: individual, store, fleamarket]
- `listing_format` (enum, optional) — Bidding auctions only, or fixed-price listings only. [one of: auction, fixed_price]
- `price_min` (integer, optional) — Lowest current (or sold) price, whole yen, tax included.
- `price_max` (integer, optional) — Highest current (or sold) price, whole yen, tax included.
- `buy_now_price_min` (integer, optional) — Lowest buy-now (即決) price, whole yen. Implies listings that have one.
- `buy_now_price_max` (integer, optional) — Highest buy-now (即決) price, whole yen.
- `has_buy_now` (boolean, optional) — Only listings with a buy-now (即決) price.
- `free_shipping` (boolean, optional) — Only listings with free shipping (送料無料).
- `min_bids` (integer, optional) — Only listings with at least this many bids.
- `featured_only` (boolean, optional) — Only paid featured listings (注目のオークション).
- `new_arrivals` (boolean, optional) — Only listings the site marks as new arrivals.
- `item_location` (string, optional) — Only listings shipped from these prefectures, by JIS number 1-47 (1 Hokkaido, 13 Tokyo, 23 Aichi, 27 Osaka, 40 Fukuoka), comma-separated.
- `shipping_destination` (integer, optional, default 13) — Prefecture (JIS 1-47) the shipping fees are quoted for. Default 13 (Tokyo), as on the site. Fees differ by destination.
- `brand_id` (integer, optional) — Yahoo! Auctions brand id (every row returns `brand_id`).
- `exclude_suspected_fakes` (boolean, optional, default true) — Drop listings Yahoo! Auctions flags as suspected counterfeits (the site's default).
- `max_rotations` (integer, optional, default 3) — Advanced: how many times to retry a difficult request (1-5).

**Returns:** category{id, name, is_leaf, open_listing_count}, parent{id, name}, children[]{id, name, is_leaf}, items[]{auction_id, title, url, image, price (number, JPY, tax included - the current bid), buy_now_price (tax included, null when none), buy_now_price_excluding_tax, start_price_excluding_tax, currency, bid_count, watch_count, quantity, is_fixed_price, listing_type (individual|store|fleamarket), condition, condition_code, category{id, name, path[]{id, name}}, brand_id, catalog_id, item_location{code, name}, free_shipping, shipping_fee (to shipping_destination; null when the seller has not fixed one), shipping_fee_type, shipping_fee_timing (fixed|decided_after_sale|cash_on_delivery), buy_now_shipping_fee, seller{id, name (null on rows - the site masks it), url, positive_percent, is_store, is_best_store, city}, is_featured (paid placement), is_new_arrival, is_appraised, easy_payment, start_time, end_time, rating (null), review_count (null), rating_scale (null)}, count, total_results, page, has_more, filters{}

### POST /yahoo-auctions/v1/categories — 1 credit
The Yahoo! Auctions category tree one level at a time: a category's name, whether it is a leaf, how many live listings it holds, its parent, and its sub-categories with their ids.

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

**Returns:** category{id, name, is_leaf, open_listing_count}, parent{id, name}, children[]{id, name, is_leaf}

### POST /yahoo-auctions/v1/suggest — 1 credit
Yahoo! Auctions' own keyword suggestions for the start of a search term.

**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[], count

**Example request body:**
```json
{
  "query": "ポケモンカード"
}
```

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