# Suruga-ya API — Japan's big second-hand shop (駿河屋, suruga-ya.jp): what it sells trading cards (Pokémon, Yu-Gi-Oh!, One Piece, Duel Masters, Weiß Schwarz, MTG …), games, figures, anime goods, books and media for (new / used / each condition and PSA slab, JPY), its stock, the marketplace shops' offers, and what it pays to buy them (買取価格). No login, no key.

> Search Suruga-ya's catalogue: cards by game, set, rarity and single/box, or any department (games, figures, books, media …). Each row is one item with Suruga-ya's own new / used price, stock, time sale, the cheapest marketplace offer and the release date.
> ReefAPI engine `surugaya` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/surugaya/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.
- **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). Clients that add connectors by URL, such as ChatGPT and the Claude app, connect with OAuth 2.1 (the user pastes their key once on a ReefAPI page; discovery at `/.well-known/oauth-protected-resource/mcp`). Config files send the key as `Authorization: Bearer <key>`. `?key=<key>` in the URL also works as a last-resort fallback.

## Endpoints

### POST https://api.reefapi.com/surugaya/v1/search — 3 credits
Search Suruga-ya's catalogue: cards by game, set, rarity and single/box, or any department (games, figures, books, media …). Each row is one item with Suruga-ya's own new / used price, stock, time sale, the cheapest marketplace offer and the release date.

**Parameters:**
- `query` (string, optional) — Keyword as Suruga-ya writes the item (Japanese works best; card numbers such as '034/103', set codes such as 'OP05-060' and English titles also match). Give query, game or category (or a mix).
- `game` (enum, optional) — Trading-card game (a Suruga-ya card category): pokemon, pokemon_old_back, yugioh, yugioh_rush_duel, onepiece, duel_masters, mtg, weiss_schwarz, vanguard, digimon, shadowverse_evolve, battle_spirits, wixoss, zx, dragon_ball_heroes, rebirth_for_you, buddyfight, force_of_will, all_cards (every card category), tcg. Any other card game's numeric id from `categories` also works. [one of: pokemon, pokemon_old_back, yugioh, yugioh_rush_duel, onepiece, duel_masters, mtg, weiss_schwarz, vanguard, digimon, shadowverse_evolve, battle_spirits, wixoss, zx, dragon_ball_heroes, rebirth_for_you, buddyfight, force_of_will, all_cards, tcg]
- `category` (string, optional) — A department alias — games, tv_games, switch, switch2, ps5, portable_games, video, anime_video, music, toys_hobby, toys, hobby, goods_fashion, books, comics, doujin, pc_smartphone, electronics — or any numeric Suruga-ya category id (the `categories` action lists them; search answers the result's own category counts in meta.facets.categories).
- `card_type` (enum, optional) — Card listings only: single cards, sealed box_pack, box, pack, or single_set. [one of: single, box_pack, box, pack, single_set]
- `condition` (enum, optional) — Only items Suruga-ya carries as new (新品), used (中古) or pre-order (予約). It is the item's classification, not the copy on the shelf: a new-classified item whose new copy is sold out still matches and shows its used price. [one of: new, used, preorder]
- `include_sold_out` (boolean, optional, default false) — Also list items nobody has in stock (品切れ ON). Off by default, as on the site: the list then holds items Suruga-ya or a marketplace shop can sell now (a row whose own stock is out still shows the marketplace price). Measured: Weiß Schwarz 51,580 items by default, 81,005 with sold-out ones.
- `min_price` (integer, optional) — Lowest price in JPY (tax included), applied by the site to the item's listing price (see sort).
- `max_price` (integer, optional) — Highest price in JPY (tax included), applied by the site to the item's listing price (see sort).
- `rarity` (string, optional) — Card rarity, one of the values the site indexes for that game (meta.facets.rarity lists them; Pokémon: C, U, R, RR, RRR, SR, SSR, UR, HR, CHR, S, P, TR, ★, ☆ …). Newer rarities the site does not index (Pokémon SAR, AR) match nothing — put them in `query` instead (e.g. 'ピカチュウ SAR'), they are part of the card name.
- `series` (string, optional) — Series / set exactly as the site writes it; meta.facets.series lists them for the result.
- `maker` (string, optional) — Maker / brand exactly as the site writes it (任天堂, バンダイ, ポケモン …); meta.facets.brand lists them.
- `release_year_from` (integer, optional) — Released in or after this year.
- `release_year_to` (integer, optional) — Released in or before this year.
- `sort` (enum, optional, default "relevance") — Order of the rows. The site orders (and price-filters) by its own listing price for the item, which is not always the cheapest price on the row: it can be the regular price during a time sale, the marketplace price when Suruga-ya's own stock is out, or another condition's price (a PSA copy): on page 2 of One Piece ルフィ by price_desc, GN140180 sits at 16,800 (its PSA 10 copy) although its plain used copy is 2,870. [one of: relevance, price_asc, price_desc, updated_desc, release_desc, release_asc]
- `page` (integer, optional, default 1) — Page number, 24 rows a page; meta.last_page says how many there are.

**Returns:** rows[]: id (Suruga-ya's item id / 管理番号 — give it to `product`, `offers`, `buyback`), url, name (as the site writes it, Japanese kept), category_label (the site's line such as 'ポケモンカードゲーム/雷/MEGA 拡張パック 30th CELEBRATION': game / type / set for cards, platform for games), maker, release_date (ISO; release_date_raw as printed), price_jpy (lowest of Suruga-ya's own prices on the row), new_price_jpy, used_price_jpy, prices[]{condition (new/used/preorder/other), condition_label, price_jpy, price_max_jpy (when the row prints a range across conditions), regular_price_jpy + on_sale (time sale)}, list_price_jpy (定価), in_stock (Suruga-ya's own stock; false = 品切れ), time_sale{period, starts_at, ends_at}, other_conditions[] (the row's 'other conditions' tooltip, e.g. Bランク, 【PSA/GEM MT 10】), marketplace_min_price_jpy + marketplace_count + marketplace_kinds (the cheapest マケプレ shop offer and how many), badges[] (新入荷 …), listing_branch_number / listing_shop_id (when the row links to one copy), image, price_includes_tax (true), currency (JPY). meta: total (the site's own count), page, per_page (24), last_page, has_more, filters_applied, facets{categories[{id,label,count}], condition, card_type, series, rarity, brand, year_range, price, badge, discount_rate ([{value, label, count (the site's approximate count such as 約300)}] — value is what the matching parameter takes)}, warnings.

**Example request body:**
```json
{
  "query": "ピカチュウ",
  "game": "pokemon"
}
```

### POST https://api.reefapi.com/surugaya/v1/product — 2 credits
One Suruga-ya item in full: every sale variant (new / used / grade) with its price and stock count, the other conditions and PSA-graded copies with their prices, the cheapest marketplace offer, the buy price Suruga-ya publishes (買取価格), JAN barcode, model number, list price, maker, release date, category path, description and images.

**Parameters:**
- `product_id` (string, required) — A Suruga-ya item id (a search row's `id`, e.g. GU880048 or 112000012) or a suruga-ya.jp item URL.
- `branch_number` (string, optional) — Read one specific condition / graded copy of the item (an `other_conditions[].branch_number` from a previous call); its own stock count then appears in `variants`.

**Returns:** product{id, url, name, category_label, category_path[{id, name}], maker, release_date, release_date_raw, jan (JAN / EAN-13 barcode when the item has one; null for most single cards), model_number (型番), management_numbers[]{condition_label, number} (管理番号 per new / used stock line), list_price_jpy (定価), price_jpy (lowest in-stock own price), new_price_jpy, used_price_jpy, in_stock, stock_qty (Suruga-ya's own units, all variants), variants[]{condition, condition_label, branch_number, price_jpy, regular_price_jpy, on_sale, stock_qty, in_stock, tags[] (値下げ …), graded, grader, grade, grade_label}, other_conditions[]{branch_number, condition, condition_label (e.g. 中古 【PSA/GEM MT 10】, Bランク), price_jpy, url, graded, grader, grade, grade_label}, marketplace_count + marketplace_min_price_jpy (the page's 他のショップ line: other shops, Suruga-ya's own stock not counted), buy_price_jpy (what Suruga-ya pays, only when the page publishes it; null = not published / quoted by e-mail), buy_price_note, attributes{label: value} (the detail table: 声優, 作家, 機種 …), description, images[], image, schema_offers[], price_includes_tax, currency}

**Example request body:**
```json
{
  "product_id": "112000012"
}
```

### POST https://api.reefapi.com/surugaya/v1/offers — 2 credits
The marketplace (マケプレ) offers for one item: each Suruga-ya branch store and partner shop that lists it, with price, condition note, stock, shipping time, free shipping and the shop's rating.

**Parameters:**
- `product_id` (string, required) — A Suruga-ya item id (a search row's `id`, e.g. GU880048 or 112000012) or a suruga-ya.jp item URL.
- `condition` (enum, optional, default "all") — Which offers: all (default), new, used, preorder, premium, wakeari (flawed / as-is). [one of: all, new, used, preorder, premium, wakeari]
- `sort` (enum, optional, default "price_asc") — Order of the offers. [one of: price_asc, price_desc, rating]
- `page` (integer, optional, default 1) — Page number, 20 offers a page; meta.has_more says if there is another.

**Returns:** rows[]: shop_id, shop_name, is_surugaya (true = Suruga-ya's own web stock, listed among the shops; the product page's marketplace_min_price_jpy leaves this row out), shop_rating (0-5), shop_review_count, shop_address (the shop's published address; branch stores and business sellers), condition (new/used/preorder), condition_label (the shop's condition note), branch_number, price_jpy, regular_price_jpy, stock_qty, free_shipping, ships_in_days_min, ships_in_days_max, campaign{name, starts_at, ends_at}, on_time_sale, listed_at, updated_at (JST), images[] (the shop's own photos), url, graded, grader, grade, grade_label. meta: page, per_page (20), has_more, condition, sort.

**Example request body:**
```json
{
  "product_id": "109002738"
}
```

### POST https://api.reefapi.com/surugaya/v1/buyback_search — 2 credits
Suruga-ya's buy-back price list (買取): what Suruga-ya PAYS for an item, searched by name, JAN / ISBN barcode or model number. A BUY price — never the sale price.

**Parameters:**
- `query` (string, required) — What to look up: a name / keyword, a JAN / ISBN barcode or a model number (型番) — say which with search_by.
- `search_by` (enum, optional, default "keyword") — How to read `query`: keyword (default), jan (JAN / ISBN barcode) or model_number. [one of: keyword, jan, model_number]
- `game` (enum, optional) — Narrow to one card game (same values as search). [one of: pokemon, pokemon_old_back, yugioh, yugioh_rush_duel, onepiece, duel_masters, mtg, weiss_schwarz, vanguard, digimon, shadowverse_evolve, battle_spirits, wixoss, zx, dragon_ball_heroes, rebirth_for_you, buddyfight, force_of_will, all_cards, tcg]
- `category` (string, optional) — Narrow to a department alias or numeric category id (same values as search).
- `sort` (enum, optional, default "relevance") — Order of the rows. [one of: relevance, price_desc, price_asc, updated_desc, release_desc, release_asc]
- `page` (integer, optional, default 1) — Page number, 20 rows a page.

**Returns:** rows[]: id (same id as the sale side — give it to `product`), url, sale_url, name, category_label, flags[] (新規追加 …), release_date, model_number, jan, buy_price_jpy, buy_prices[]{grade_label, buy_price_jpy}, quote_by_email (true = Suruga-ya quotes this one by e-mail and prints no price), image, currency. meta: total, page, per_page (20), last_page, has_more, search_by, sort.

**Example request body:**
```json
{
  "query": "ゼルダ",
  "category": "tv_games"
}
```

### POST https://api.reefapi.com/surugaya/v1/buyback — 2 credits
One item's buy-back page: the buy price (買取価格), JAN, model number, list price, maker, release date and category.

**Parameters:**
- `product_id` (string, required) — A Suruga-ya item id (a search row's `id`, e.g. GU880048 or 112000012) or a suruga-ya.jp item URL.

**Returns:** buyback{id, url, sale_url, name, category_label, category_path[], buy_price_jpy, buy_prices[]{grade_label, buy_price_jpy}, quote_by_email, jan, model_number, maker, release_date, list_price_jpy, description, image, currency}

**Example request body:**
```json
{
  "product_id": "112000012"
}
```

### POST https://api.reefapi.com/surugaya/v1/categories — 2 credits
Suruga-ya's category ids: every trading-card game (TCG, arcade cards, collection cards, supplies — 150+) and the site's departments with their sub-categories. Give an id to search as `game` or `category`.

**Parameters:** none

**Returns:** card_games[]{id, name, group (the site's own section: TCG・ACG, その他TCG, その他アーケード …), alias (our short name when there is one)}, departments[]{id, name, children[]{id, name}}, aliases{games{alias: id}, departments{alias: id}}

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

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