# Japan MTG Card Prices (晴れる屋 Hareruya) (`jpopendata/japan-tcg-hareruya`) Actor

Magic: the Gathering single-card prices from Hareruya (hareruyamtg.com): price JPY, condition grade (NM/EX/MP/HP), stock, foil, set code, printing language, image and product URL, in an English schema. Product facts only. Unofficial; not affiliated with Hareruya Inc.

- **URL**: https://apify.com/jpopendata/japan-tcg-hareruya.md
- **Developed by:** [JP Open Data](https://apify.com/jpopendata) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Japan MTG Card Prices (晴れる屋 Hareruya)

**Live Magic: the Gathering single-card prices from Hareruya (hareruyamtg.com) — one of the world's largest MTG stores: price (JPY), condition grade, stock, foil, set code, printing language, image and product URL, in a clean English schema.**

This Actor searches the public product listings on hareruyamtg.com by card name (and optional set) and returns each listing as English-schema JSON: card name, English listing title, set code, best-effort rarity, price (JPY), condition grade (NM / EX / MP / HP / DAMAGE) with the raw source code, in-stock flag and stock count, foil flag, on-sale flag, the copy's printing language (JP / EN / …), image URL and product URL. Optional in-stock and price-range filters are applied client-side.

Hareruya is a primary price reference for Magic: the Gathering singles — especially reserved-list, old-border and Japanese-language printings that international tooling rarely covers — but its store is Japanese-first and hard to query programmatically. This Actor is the bridge for price research, sourcing and arbitrage.

> **Unofficial tool.** Not affiliated with or endorsed by Hareruya Inc. (株式会社Hareruya / 晴れる屋) or Wizards of the Coast. It collects **publicly available data only** (no login, no paywall), politely (strictly serial requests, a single search request per run on the fleet-wide ≥ 1.2 s floor, hard per-run budget, no block evasion), fetches **only URLs the site's robots.txt leaves open to general bots** (never the disallowed `page=` / `sort=` / `order=` search parameters and never CSV), and extracts **product facts only** — **no seller/shop names, no user comments or reviews, no personal data** (relevant e.g. under GDPR: no personal data is collected or processed). Users are responsible for ensuring their own use of the data complies with the source site's terms and applicable law.

***

### Quick start — verified input

Copy, paste, run. This exact input is verified on the platform (SUCCEEDED, items > 0):

```json
{
  "cardName": "Black Lotus",
  "language": "en",
  "maxItems": 10
}
```

Running with **no input at all** also works (same defaults). Add `"setName": "Beta"` to narrow to one printing, `"inStockOnly": true` for stocked copies only.

### Who is this for?

- **Overseas players, collectors & proxy-buying services** — know the fair Japanese market price and condition spread for a card before buying or quoting; Hareruya prices are a domestic benchmark that Buyee/ZenMarket-style flows check by hand today.
- **Resellers & arbitrage** — price by condition grade and foil, stock status, and set code for margin math against TCGplayer / Cardmarket.
- **Price-tracking & market tools** — a stable English schema over a Japanese-first source; re-run on a schedule for time series.
- **Deck & collection tools** — resolve a card name to its concrete Hareruya listings, prices and printing languages.

### Sample output (dataset item)

```json
{
  "cardName": "Black Lotus",
  "cardNameEn": "《Black Lotus》[2ED]",
  "productName": "《Black Lotus》[2ED] 茶R",
  "setCode": "2ED",
  "setName": null,
  "rarity": "R",
  "priceJpy": 3750000,
  "condition": "EX",
  "conditionCode": "2",
  "printingLanguage": "EN",
  "stock": 1,
  "inStock": true,
  "foil": false,
  "onSale": false,
  "imageUrl": "https://files.hareruyamtg.com/product/6a7e8f8e76491695.jpeg",
  "productUrl": "https://www.hareruyamtg.com/en/products/detail/1282?lang=EN&class=1291630",
  "source": "Hareruya (hareruyamtg.com card listings)",
  "sourceUrl": "https://www.hareruyamtg.com/",
  "license": "Publicly available data — unofficial tool; users are responsible for compliance with the source site's terms",
  "retrievedAt": "2026-08-26T00:00:00.000Z"
}
```

`condition` is Hareruya's grade label (**NM** > **EX** > **MP** > **HP** > **DAMAGE**), and `conditionCode` is the raw numeric grade straight from the source (kept so nothing is lost if the grade set changes). `printingLanguage` is the language of the physical copy (JP, EN, CS, CT, FR, DE, IT, KO, PT, RU, ES, AG). `setCode` is parsed from the listing title; `setName` (the full set name) is not present in the source list data, so only the code is emitted. `rarity` is best-effort from the title. `foil` is `true` / `false`, or `null` when the source omits the flag.

### Input example

```json
{
  "cardName": "Black Lotus",
  "setName": "Beta",
  "language": "en",
  "inStockOnly": true,
  "priceMin": 100000,
  "priceMax": 5000000,
  "maxItems": 50
}
```

`cardName` and/or `setName` is required (English card names match best; `setName` accepts a set name or code like `Beta` / `2ED` and is added to the search). `language` selects the site locale (`en` or `ja`) for names and URLs — each record still reports its own printing language separately. The in-stock and price filters are applied **client-side after fetching** — the equivalent sort/pagination URL parameters are disallowed by the site's robots.txt, and this Actor strictly requests only robots-permitted URLs.

#### Common input mistakes

| Mistake | Correct |
|---------|---------|
| `"cardName": "ブラック・ロータス"` with `"language": "en"` | either `"cardName": "Black Lotus"` on the `en` site, or keep the Japanese name and set `"language": "ja"` |
| `"language": "fr"` / `"english"` | `"en"` or `"ja"` (`English`, `Japanese`, `jp` are accepted aliases) |
| `"priceMin": "1000 yen"` | a whole number of yen: `1000` (`"1,000"` is tolerated) |
| `"priceMin": 5000, "priceMax": 1000` (reversed) | `"priceMin": 1000, "priceMax": 5000` |
| `"maxItems": 5000` | 1–1000 (one search page holds at most 250 listings — narrow the query instead) |
| `"inStockOnly": "yes"` | `true` / `false` (`"yes"`/`"no"` strings are tolerated) |

#### Empty results?

A run that finds nothing completes with 0 items and a warning in the log (not a failure). Typical causes: a misspelled or non-English card name on the `en` site (try the exact Scryfall spelling, or switch to `"language": "ja"` for a Japanese name), a `setName` code Hareruya does not use, or a price/in-stock filter that discards every listing (`inStockOnly: true` on a card Hareruya is sold out of). Drop the filters and retry.

### Pricing

Pay per result — see the pricing tab.

### FAQ

**Where does the data come from?**
Live from the public, login-free product-search results on hareruyamtg.com at run time (the same JSON search endpoint the site's own search box uses). Every record embeds the source, source URL, a license note, and the retrieval timestamp.

**Is this an official Hareruya service?**
No. **Unofficial**, independently built and maintained, and **not affiliated with or endorsed by Hareruya Inc. (株式会社Hareruya / 晴れる屋)** or Wizards of the Coast. It reads only publicly available pages.

**Is seller or user information included?**
No — deliberately. The search payload contains only product facts (card, set, price, condition grade, stock, foil, printing language, image). There are no seller/shop names, and no user comments or reviews are read or emitted. The test suite asserts that no person- or seller-related field can appear in the output.

**Does it respect robots.txt?**
Yes, strictly. The product-search results are open to general bots; the site disallows the HTML search's `page=`, `sort=` and `order=` parameters and CSV downloads, so this Actor **never sends any of those** and **never requests CSV**. Each run makes a single search request in the site's default relevance order and returns one page (up to 250 listings) — deliberately not paginating, because pagination is what robots.txt asks bots not to do here.

**How many results can one run return?**
Up to ~250 listings for one query (a single page). Most single-card searches fit in one page; for a card with more printings/conditions than that, narrow the query with `setName` or a more specific card name. `RUN_SUMMARY` reports the total the site matched (`numFound`) so you can see when a query was truncated.

**Why is there no full set name or collector number?**
The search list data carries the set **code** (e.g. `2ED`, `DMU`) but not the full set name or the card's collector number. This Actor emits the code and does not guess the rest. Every other field above is available directly from the source.

**Do I need a proxy?**
Maybe. hareruyamtg.com is served through a CDN. From clean IPs the search endpoint answers ordinary polite requests; if a run fails immediately with HTTP 403, set `proxyConfiguration` to Apify **RESIDENTIAL** proxies with country **JP** (or your own Japanese residential proxy). The Actor itself never rotates identities or evades blocks — it makes the same polite, serial requests through whichever single egress you give it, and fails visibly when blocked.

**Who is responsible for how the data is used?**
You are. The Actor collects publicly available factual data politely, but the legality of your specific use (redistribution, database rights, the source site's terms) is your responsibility as the user.

**How fresh are the results?**
Prices and stock are what the site's search returns at retrieval time. Treat each run as a snapshot and re-run for fresh data.

**What about server load?**
A single serial search request per run (≥ 1.2 s floor), a hard request budget, exponential backoff, no CAPTCHA/login/block evasion. If the site changes its API format, the Actor stops with a clear error instead of silently mis-parsing; if it blocks persistently, the run fails visibly.

### Search terms this Actor answers

hareruya scraper · mtg singles japan price · japanese magic cards data · mtg card prices japan · hareruya price data · magic the gathering japan prices · japanese mtg singles · mtg reserved list japan price · 晴れる屋 相場 データ · japan tcg price research · mtg card sourcing japan · foil mtg prices japan

### More Japan data Actors by the same developer

- **Japan Hobby & Collectibles Prices (駿河屋 Suruga-ya)** — figures, retro games, trading cards and anime goods: new/used prices, stock and marketplace low price; the natural companion for cross-checking collectible prices.
- **Yahoo Auctions Japan Sold Prices (ヤフオク落札相場)** — actual sold-item comps from auctions.yahoo.co.jp; what items *sold* for vs a store's asking prices.
- **Japan Hotels & Ryokan Prices (jalan.net)** — hotel/ryokan prices, plans and ratings by prefecture and area.
- **Japan Luxury Hotels & Ryokan (ikyu.com)** — the high-end accommodation roster with advertised prices.
- **Japan Government Tenders & Awards** — tender notices and award results from the kkj.go.jp portal.
- **Japan Medical Facilities** — every registered hospital, clinic, dental clinic, and pharmacy (MHLW open data).
- **Japan Care Facilities** — long-term care providers across 35 service types (MHLW open data, CC BY).
- **Japan Government Subsidies & Grants** — open subsidy calls from the official jGrants API.
- **Japan Renewable Energy FIT/FIP Facilities** — METI-certified renewable installations, privacy-safe schema.
- **Japan Financial Licenses & Registrations** — FSA-licensed banks, securities firms, crypto exchanges and more.
- **Japan Construction & Real-Estate Licenses** — licensed contractors and brokers from MLIT's official register.
- **Japan Trade Statistics** — monthly import/export flows by HS code and partner country, from Japan Customs.

***

*Unofficial tool; not affiliated with Hareruya Inc. (株式会社Hareruya / 晴れる屋) or Wizards of the Coast. Publicly available data only; users are responsible for compliance with the source site's terms and applicable law. No personal data and no seller data are collected.*

# Actor input Schema

## `cardName` (type: `string`):

Magic: the Gathering card name to search, e.g. "Black Lotus", "Ragavan, Nimble Pilferer", "Sheoldred, the Apocalypse". English names match best (Japanese names work on the ja site). Required unless setName is given; an empty input searches "Black Lotus".

## `setName` (type: `string`):

Optional set name or set code to narrow the search, e.g. "Beta", "2ED", "The Brothers' War", "MH3". Added to the search keyword. Leave empty to search all sets.

## `language` (type: `string`):

Which Hareruya site locale to query — "en" (English names/URLs, default) or "ja" (Japanese). Aliases such as "English"/"Japanese"/"jp" are accepted. This is the site UI locale; each card record still reports its own printing language separately.

## `inStockOnly` (type: `boolean`):

Keep only listings Hareruya itself currently has in stock (stock > 0). Applied client-side after fetching.

## `priceMin` (type: `integer`):

Optional lower bound on priceJpy (yen, whole number, e.g. 1000). Applied client-side after fetching.

## `priceMax` (type: `integer`):

Optional upper bound on priceJpy (yen, whole number, e.g. 500000). Applied client-side after fetching.

## `maxItems` (type: `integer`):

Stop after this many dataset records (1-1000, default 10). One run fetches a single search page (up to 250 listings, no pagination — a deliberate robots.txt-compliance choice). Narrow the query for larger result sets.

## `proxyConfiguration` (type: `object`):

Apify proxy settings. Default: no proxy. If a run fails with HTTP 403, use RESIDENTIAL proxies with country JP. Never used for rotation/evasion — one client identity per run.

## Actor input object example

```json
{
  "cardName": "Black Lotus",
  "setName": "Beta",
  "language": "en",
  "inStockOnly": false,
  "priceMin": 1000,
  "priceMax": 500000,
  "maxItems": 10
}
```

# Actor output Schema

## `records` (type: `string`):

Structured Hareruya MTG card price records with source attribution (source, sourceUrl, license, retrievedAt) on every item.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "cardName": "Black Lotus",
    "language": "en",
    "maxItems": 10
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpopendata/japan-tcg-hareruya").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "cardName": "Black Lotus",
    "language": "en",
    "maxItems": 10,
}

# Run the Actor and wait for it to finish
run = client.actor("jpopendata/japan-tcg-hareruya").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "cardName": "Black Lotus",
  "language": "en",
  "maxItems": 10
}' |
apify call jpopendata/japan-tcg-hareruya --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpopendata/japan-tcg-hareruya"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/cJyugwAt9I7N380Cj/builds/BZV5x1qK4BzQs1nbj/openapi.json