# Hareruya API — Magic: The Gathering prices from Hareruya (晴れる屋, hareruyamtg.com), Japan's largest MTG shop: sale price in JPY per language and condition (NM/SP/MP/HP) with live stock and weekly sales, the shop's buylist (買取) price, full card data and the set list. No login, no key.

> Search Hareruya's MTG shop. Each row is one printing in one language and condition, with the live price and stock, plus the other conditions of the same printing. Give `query`, `card_name` or `set_id` (any combination); the other filters narrow it.
> ReefAPI engine `hareruya` · 4 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/hareruya/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). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/hareruya/v1/search — 3 credits
Search Hareruya's MTG shop. Each row is one printing in one language and condition, with the live price and stock, plus the other conditions of the same printing. Give `query`, `card_name` or `set_id` (any combination); the other filters narrow it.

**Parameters:**
- `query` (string, optional) — Card or product name, English or Japanese ('Lightning Bolt', '稲妻', 'Ragavan'). A Japanese word can match more products than the English name (稲妻 980 vs Lightning Bolt 141 measured) because it also matches card text and other names.
- `card_name` (string, optional) — Exact English card name, every printing of that card ('Lightning Bolt' → 117 products). Case-sensitive and exact: 'lightning bolt' or '稲妻' answer 0. Rows carry `card_name`, so a search row's value always works.
- `set_id` (string, optional) — Set id from the `sets` action (e.g. 10 = Fourth Edition). With no query this lists the whole set.
- `language` (enum, optional) — Copies in this language: jp, en, or other (every other language). [one of: jp, en, other]
- `foil` (enum, optional) — normal (non-foil) or foil. [one of: normal, foil]
- `rarity` (enum, optional) — common, uncommon, rare, mythic, basic_land, special or token. [one of: common, uncommon, rare, mythic, basic_land, special, token]
- `format` (enum, optional) — Only cards legal in this format: standard, pioneer, modern, legacy, vintage, commander, pauper. [one of: standard, pioneer, modern, legacy, vintage, commander, pauper]
- `category` (enum, optional) — single (single cards) or supply (sleeves, boxes, sealed product). [one of: single, supply]
- `min_price` (integer, optional) — Lowest price in JPY (inclusive).
- `max_price` (integer, optional) — Highest price in JPY (inclusive).
- `in_stock_only` (boolean, optional, default false) — Only rows with stock now. The shop's own in-stock filter runs on its search index, which lags; the engine also drops rows that the live list shows with no stock in any condition and counts them in meta.dropped_out_of_stock.
- `sort` (enum, optional, default "relevance") — relevance (default), price_desc, price_asc, release_date. [one of: relevance, price_desc, price_asc, release_date]
- `per_page` (integer, optional, default 60) — Rows per page, 1-100 (default 60, the shop's own).
- `page` (integer, optional, default 1) — Page number. The shop's search reaches the first 4,000 rows of any result; meta.last_page says where that stops.

**Returns:** rows[]: product_id (give it to `card`), product_class_id (this printing x language x condition), card_id (give it to `buylist`), name (the shop's Japanese title), name_en, card_name (English), set_code, language (JP, EN, FR, DE, IT, KO, PT, RU, ES, CS, CT), language_id, foil (null on supplies), condition (NM, SP, MP, HP; graded or single copies carry their own label such as BGS8.5), price_jpy, stock (live web-shop stock), in_stock, weekly_sales (the shop's own count), on_sale, single_copy (an individual high-value copy with its own photo), copy_code, other_conditions[] {condition, price_jpy, stock, in_stock, product_class_id}, image, url, currency (JPY), price_index_jpy (the search index's price), price_mismatch. meta: total (the shop's own count), total_capped (the shop pages through 4,000 at most), reachable, page, per_page, last_page, has_more, past_last_page, sort, filters_applied, dropped_out_of_stock, currency, warnings.

**Example request body:**
```json
{
  "query": "Lightning Bolt",
  "per_page": 20
}
```

### POST https://api.reefapi.com/hareruya/v1/card — 2 credits
One printing in full: every language and condition the shop sells it in (price, live stock, individual graded copies), weekly sales per language, and the card's data (type, cost, text, rarity, set, illustrator, legal formats).

**Parameters:**
- `product_id` (string, required) — A search row's `product_id` (one printing; every language and condition of it is on one page) or a hareruyamtg.com product URL.
- `locale` (enum, optional, default "ja") — Page text language: ja (default) or en. Prices are JPY either way. [one of: ja, en]

**Returns:** card{product_id, name, set_code, set_name, set_id, languages[], offers[]{language, condition, price_jpy, stock, in_stock, product_class_id, single_copy, copy_code}, weekly_sales{language: n}, card_name_local, color, mana_cost, card_type, subtype, rarity, text, flavor_text, power_toughness, loyalty, illustrator, illustrator_id, legal_formats[], sku, image, url, currency, price_mismatch (the page's table vs its own ld+json offer)}

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

### POST https://api.reefapi.com/hareruya/v1/buylist — 3 credits
Hareruya's buylist (買取): what the shop PAYS for a card in NM condition, in JPY. This is a buy price, never the sale price. Give `query`, `card_id` or `set_id`.

**Parameters:**
- `query` (string, optional) — Card or product name, English or Japanese ('Lightning Bolt', '稲妻', 'Ragavan'). A Japanese word can match more products than the English name (稲妻 980 vs Lightning Bolt 141 measured) because it also matches card text and other names.
- `card_id` (string, optional) — Every printing of one card: a search or buylist row's `card_id`.
- `set_id` (string, optional) — Set id from the `sets` action (e.g. 10 = Fourth Edition). With no query this lists the whole set.
- `language` (enum, optional) — Copies in this language: jp, en, or other (every other language). [one of: jp, en, other]
- `foil` (enum, optional) — normal (non-foil) or foil. [one of: normal, foil]
- `rarity` (enum, optional) — common, uncommon, rare, mythic, basic_land, special or token. [one of: common, uncommon, rare, mythic, basic_land, special, token]
- `sort` (enum, optional, default "default") — default (the shop's order), price_desc, price_asc. [one of: default, price_desc, price_asc]
- `page` (integer, optional, default 1) — Page number (60 rows a page).

**Returns:** rows[]: product_id (also a `card` product_id), product_class_id, card_id, name, set_code, language, foil, condition (NM: the list quotes NM), buy_price_jpy, accepting (the shop shows a sell-to-us quantity box), max_buy_qty, image, url, currency. meta: total, page, per_page (60), last_page, has_more, past_last_page, filters_applied, warnings. Japanese page text only (the shop has no English buylist search).

**Example request body:**
```json
{
  "query": "Lightning Bolt"
}
```

### POST https://api.reefapi.com/hareruya/v1/sets — 2 credits
Every MTG set the shop files cards under, newest first: set_id (for `search` / `buylist`) and name.

**Parameters:**
- `locale` (enum, optional, default "ja") — Page text language: ja (default) or en. Prices are JPY either way. [one of: ja, en]

**Returns:** rows[]: set_id, name. meta: total, locale.

**Example request body:**
```json
{
  "locale": "en"
}
```

## 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=hareruya
- Human docs page: https://reefapi.com/docs/hareruya
- Overview page: https://reefapi.com/hareruya-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt