# KOMEHYO Scraper – Japan Luxury & Brand Resale (コメ兵) (`tokyo-select-jp/komehyo-search-scraper`) Actor

Scrape KOMEHYO (komehyo.jp, コメ兵) — Japan's largest luxury & brand reuse store: bags, watches, jewelry, fashion, cameras. Search by keyword, brand, category, condition rank, price or new arrivals; get normalized size, condition, measurements and images. JP Data Works series.

- **URL**: https://apify.com/tokyo-select-jp/komehyo-search-scraper.md
- **Developed by:** [JP Data Works](https://apify.com/tokyo-select-jp) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## KOMEHYO Scraper – Japan Luxury & Brand Resale (コメ兵)

Scrape **[KOMEHYO](https://komehyo.jp/) (コメ兵)** — Japan's largest luxury and brand reuse chain (Nagoya-based, 100+ stores): **brand bags, watches, jewelry, diamonds, men's and women's fashion, wallets, cameras, guitars, kimono, pens** — by **keyword, brand, category, gender, condition rank, price range and sort order (including new arrivals)**, and get clean JSON / CSV with **normalized size, condition rank (6–2), reference retail price, store and images**. Optionally open each product page for **measurements in cm, model number, colour, material and the full gallery**. Part of the **JP Data Works** series of Japanese marketplace scrapers (Trefac, Mercari, Yahoo! Auctions …) that share one output shape so results can be merged.

**Keywords:** KOMEHYO scraper · コメ兵 スクレイピング · Japan luxury resale data · used Louis Vuitton / Hermès / Chanel / Rolex prices Japan · Japanese secondhand brand bags & watches · KAPITAL, visvim, Comme des Garçons used clothing · resale sourcing (eBay, Grailed, Chrono24, StockX) · price monitoring · new-arrival alerts.

### What you get

One row per listing:

- `itemId` (goodsNo), `productCode` (商品コード), `url`, `title`, `brand`, `brandKana`, `itemName`
- `priceJpy` (tax included), `referencePriceJpy` (参考上代 — reference retail price when shown)
- `sizeRaw` and `sizeNorm` / `size` (`W32`, `L`, `JP3`, `26.5cm`, `FREE`)
- `conditionRank` 6 (新品 / 未使用品) … 2 (中古品C) and `conditionLabel` (新品, 未使用品, 中古品S, 中古品A, 中古品B, 中古品C)
- `storeName` (在庫店舗 — the physical shop holding the item), `arrivalDate`, `labels` (新入荷 …), `isNewArrival`, `soldOut`
- `material`, `gender`, `categoryPath`, `imageUrl` / `imageUrls`, `fetchedAt`, `keyword`, `search`

With **Enrich with product pages** each item additionally has `modelNumber` (品番型式), `conditionNote` (e.g. 使用感のある中古品), `measurementsCm` (`shoulder` 肩幅, `chest` 身幅, `sleeve` 袖丈, `length` 着丈, `waist` ウエスト, `inseam` 股下, `rise` 股上, `thigh` わたり, `hem` 裾幅 …), `color`, `description`, `returnPolicy`, the breadcrumb `categoryPath` and the full-size gallery.

#### Example item (enriched)

```json
{
  "source": "komehyo",
  "itemId": "4147724",
  "productCode": "230-000-559-9492",
  "url": "https://komehyo.jp/product/230-000-559-9492/",
  "title": "キャピタル KAPITAL EK-962 ジャケット",
  "brand": "KAPITAL",
  "brandKana": "キャピタル",
  "itemName": "ジャケット",
  "modelNumber": "EK-962",
  "priceJpy": 18000,
  "referencePriceJpy": null,
  "sizeRaw": "3",
  "sizeNorm": { "kind": "numeric", "value": 3 },
  "size": "JP3",
  "conditionRank": 3,
  "conditionLabel": "中古品B",
  "conditionNote": "使用感のある中古品",
  "gender": "メンズ",
  "material": null,
  "color": "ネイビー系 グレー系 ピンク系",
  "storeName": "名古屋本店 本館",
  "arrivalDate": null,
  "labels": [],
  "isNewArrival": false,
  "soldOut": false,
  "categoryPath": "メンズファッション > アウター・ジャケット > ジャケット",
  "measurementsCm": { "length": 68, "shoulder": 47, "chest": 52, "sleeve": 63 },
  "description": "■ご注意ください■ ※付属情報について：表記または、写真に掲載のないものは付属しておりません。…",
  "returnPolicy": "B.返品可能 …",
  "imageUrl": "https://img.komehyo.jp/contents/images/goods/1f0/2300005599492_1_b.jpg",
  "imageUrls": ["…_1_b.jpg", "…_2_b.jpg", "…_3_b.jpg", "…_4_b.jpg"],
  "fetchedAt": "2026-11-02T01:32:57.000Z",
  "detailFetchedAt": "2026-11-02T01:33:00.423Z",
  "keyword": "brand:KAPITAL#1734 メンズファッション ¥–30000 newest",
  "search": { "label": "brand:KAPITAL#1734 メンズファッション ¥–30000 newest", "brandNo": "1734", "categoryCode": "009001009", "categoryNames": ["メンズファッション"], "sort": "newest", "priceMaxJpy": 30000, "url": "https://komehyo.jp/search/?dispNo=009001009&leftnavi_field999=1734&common_pr_range=-30000&sortKey=01" }
}
```

Without enrichment the detail fields are `null` / `{}` and `imageUrls` holds the listing thumbnail, so the dataset always has the same columns.

### Output modes — listings or a market summary

`outputMode` chooses what the dataset contains:

- **`items`** (default) — one row per listing, as above.
- **`summary`** — one **market-summary row per search** instead of the listings. The Actor still walks the search pages (up to `maxItemsPerSearch` listings, with `enrichDetail` if set), but stores only the aggregate — so a run that answers "what does X go for on KOMEHYO?" costs one `summary` event per search rather than hundreds of result events.
- **`both`** — the listings plus the summary row.

A summary row (`recordType: "summary"`) has the same shape in every JP Data Works Actor, so you can put several sites side by side:

```json
{
  "recordType": "summary",
  "source": "komehyo",
  "search": { "label": "…", "url": "…", "…": "the resolved search parameters" },
  "fetchedAt": "2026-11-02T03:00:00.000Z",
  "sampleSize": 180, "totalOnSite": 1243, "scanned": 190, "filteredOut": 10, "withDetail": 0,
  "status": { "on_sale": 180, "sold": 0, "unknown": 0 },
  "price": { "count": 180, "min": 3300, "p25": 9800, "median": 16500, "mean": 19840, "p75": 25300, "max": 128000, "stddev": 15210 },
  "priceOnSale": { "…": "same statistics for on-sale listings" }, "priceSold": { "…": "and for sold ones (sites that list them)" },
  "priceHistogram": { "bucketJpy": 10000, "buckets": [ { "fromJpy": 0, "toJpy": 10000, "count": 46 }, "…" ] },
  "conditionRank": { "6": 12, "5": 40, "4": 71, "3": 30, "unknown": 27 }, "conditionLabels": { "…": "the site's own labels" },
  "sizes": { "M": 48, "L": 41, "W32": 12, "…": 0 }, "sizeKinds": { "alpha": 120, "waist": 30, "numeric": 20, "unknown": 10 },
  "brands": { "KAPITAL": 180 }, "categories": { "メンズ > ジャケット/アウター": 95, "…": 0 }, "gender": { "mens": 170, "unknown": 10 },
  "listed": { "last24h": 9, "last7d": 41, "last30d": 120 }, "sold": null,
  "cheapest": [ { "itemId": "…", "title": "…", "url": "…", "priceJpy": 3300, "conditionRank": 4, "size": "M", "status": "on_sale" }, "…" ],
  "cheapestGoodCondition": [ "… cheapest with condition rank ≥ 4 …" ],
  "newest": [ "… most recently listed (sites that expose listing times) …" ]
}
```

KOMEHYO shows an arrival date on new listings, so `listed` and `newest` are filled when the site shows them; with `includeSoldOut: true` the summary separates `priceOnSale` from `priceSold`.

### Input

Two ways to describe what to search, which can be combined in one run:

- **`keywords`** — simple: one search per keyword (`KAPITAL`, `ルイヴィトン モノグラム`, `Rolex Datejust` …).
- **`searches`** — structured: objects with any of `keyword`, `brand` / `brandId`, `categoryPath` / `categoryCode`, `gender`, `priceMinJpy`, `priceMaxJpy`, `rankMin` / `rankIds`, `sort`, `includeSoldOut`, `storeName`, `excludeWords`.

Top-level `sort`, `gender`, `priceMinJpy`, `priceMaxJpy`, `rankMin`, `includeSoldOut`, `excludeWords` are defaults for every keyword and search; a value inside a search wins.

| Field | Type | Default | Notes |
|---|---|---|---|
| `keywords` | string\[] | — | One search per keyword. Optional when `searches` is given. |
| `outputMode` | `items` | `summary` | `both` | `items` | Listings, one market-summary row per search, or both (see "Output modes"). |
| `searches` | object\[] | — | Structured searches (table below). Each needs a keyword, brand or category. |
| `sort` | `recommended` | `newest` | `priceAsc` | `priceDesc` | `discountAsc` | `discountDesc` | `recommended` | `newest` = 新着順. |
| `gender` | `any` | `mens` | `ladies` | `any` | |
| `priceMinJpy` / `priceMaxJpy` | integer | none | Exact bounds. The site only filters by fixed buckets (≤30,000 / 30,001–100,000 / 100,001–250,000 / 250,001–500,000 / 500,001+), which the Actor uses when the range fits one; exact bounds are always enforced client-side and price-sorted searches stop early. |
| `rankMin` | 2–6 | none | 6 新品 / 未使用品, 5 中古品S, 4 中古品A, 3 中古品B, 2 中古品C. |
| `includeSoldOut` | boolean | false | Also return SOLD OUT listings. |
| `excludeWords` | string\[] | `[]` | Client-side title filter. |
| `maxItemsPerSearch` | integer | 100 | Per keyword / search. 50 cards per page. |
| `maxTotalItems` | integer | none | Hard cap per run. |
| `dedupeAcrossSearches` | boolean | true | |
| `enrichDetail` | boolean | false | One extra request + one `detail-page` event per item. |
| `maxDetailPages` | integer | 100 | Cap on product-page requests per run. |
| `requestDelayMs` | integer | 3000 | Minimum pause between requests. Please keep ≥ 3000. |
| `proxyConfiguration` | object | none | Optional. Not needed under normal use. |
| `outputFields` | string\[] | all | Keep only these fields (`itemId`, `url` always kept). |

Fields of one `searches` entry (all optional):

| Field | Example | How it is applied |
|---|---|---|
| `keyword` | `"モノグラム"` | Site keyword search (`q`). |
| `brand` | `"KAPITAL"`, `"キャピタル"`, `"LOUIS VUITTON"` | Looked up in the site's brand list (1,300+ brands, English or katakana, exact match) and sent as the brand id. Unknown names are searched as a keyword and filtered by brand name client-side. |
| `brandId` | `1734` | The site's brand id (`brandNo` on komehyo.jp/disp/brandlist/). 1734 = KAPITAL, 2132 = VISVIM, 1787 = LEVI'S. |
| `categoryPath` | `"mens"`, `"mens > bottoms > jeans"`, `"メンズファッション > トップス > Tシャツ"`, `"bags > トートバッグ"`, `"watches mens"`, `"camera > film-camera"` | Top category (`mens`, `ladies`, `bags`, `wallets`, `brand jewelry`, `jewelry`, `diamond`, `watches mens`, `watches ladies`, `camera`, `guitar`, `kimono`, `stationery`, or the Japanese name) optionally followed by `>` and sub-category names as shown on the site (Japanese, or English for the common ones: tops, outerwear, bottoms, shoes, suits, hats, jeans, t-shirts, shirts, knit, hoodies, dresses, skirts, coats, sneakers, boots …). Unknown paths are used as an extra keyword. |
| `categoryCode` | `"009001009003"` | The site's `dispNo` code directly (9 digits = top category, 12 = sub, 15 = sub-sub). |
| `gender` | `"mens"` | `mens`, `ladies`, `any`. |
| `priceMinJpy` / `priceMaxJpy` | `5000` / `30000` | Exact bounds (see above). |
| `rankMin` / `rankIds` | `4` / `[1, 2, 3, 4]` | Site condition filter. `rankIds` are the site's ids: 1 新品, 2 未使用品, 3 中古品S, 4 中古品A, 5 中古品B, 6 中古品C. |
| `sort` | `"newest"` | `recommended` おすすめ順, `newest` 新着順, `priceAsc` 価格が安い順, `priceDesc` 価格が高い順, `discountAsc` / `discountDesc` OFF率. |
| `includeSoldOut` | `true` | Include SOLD OUT listings (`soldOut: true`). |
| `storeName` | `"名古屋"` | **Client-side**: keep items held by a shop whose name contains the text. |
| `excludeWords` | `["ジャンク"]` | **Client-side**: drop items whose title contains any of these. |

#### Examples

New arrivals of one brand in men's fashion under ¥30,000 (run on a schedule and diff `itemId`):

```json
{
  "searches": [{ "brand": "KAPITAL", "categoryPath": "mens", "sort": "newest", "priceMaxJpy": 30000 }],
  "maxItemsPerSearch": 100
}
```

Used Louis Vuitton tote bags in A / S / unused condition, cheapest first, with details:

```json
{
  "searches": [{ "brand": "LOUIS VUITTON", "categoryPath": "bags > トートバッグ", "rankMin": 4, "sort": "priceAsc" }],
  "maxItemsPerSearch": 200,
  "enrichDetail": true,
  "maxDetailPages": 200
}
```

Men's jeans ¥10,000–20,000 (spans two site buckets → exact bounds applied client-side, early stop thanks to price sort):

```json
{ "searches": [{ "categoryPath": "mens > bottoms > jeans", "priceMinJpy": 10000, "priceMaxJpy": 20000, "sort": "priceAsc" }], "maxItemsPerSearch": 300 }
```

Requests are strictly sequential: 100 listings ≈ 2 search pages ≈ 10 seconds; with `enrichDetail` ≈ 102 requests ≈ 5 minutes at the default delay (+1 request when brand names need to be resolved).

#### Search URL parameters (how the filters map to komehyo.jp)

Discovered from the site's filter form, sort select and pager (2026-11-02):

```
https://komehyo.jp/search/?q=…&dispNo=009001009003&leftnavi_field999=1734&leftnavi_field9=1&leftnavi_field46=4&leftnavi_field46=5&common_pr_range=-30000&sortKey=01&stock=0&page=2
```

| Actor field | Site parameter | Values |
|---|---|---|
| `keyword` | `q` | free text (spaces as `%20`) |
| `categoryPath` / `categoryCode` | `dispNo` | hierarchical code: 009001009 メンズファッション, 009001008 レディースファッション, 009001004 ブランドバッグ, 009001005 ブランド財布・小物, 009001001 ブランドジュエリー, 009001002 ジュエリー, 009001003 鑑定書付ダイヤモンド, 009001006 時計メンズ, 009001007 時計レディース, 009001010 カメラ, 009001011 ギター, 009001012 きもの, 009001013 筆記具; + 3 digits per level (009001009003 ボトムス, 009001009003001 ジーンズ) |
| `brand` / `brandId` | `leftnavi_field999` | `brandNo` from /disp/brandlist/ |
| `gender` | `leftnavi_field9` | `1` メンズ, `2` レディース |
| `rankMin` / `rankIds` | `leftnavi_field46` (repeatable) | `1` 新品, `2` 未使用品, `3` 中古品S, `4` 中古品A, `5` 中古品B, `6` 中古品C |
| price | `common_pr_range` | only the fixed buckets `-30000`, `30001-100000`, `100001-250000`, `250001-500000`, `500001-` |
| `sort` | `sortKey` | `06` おすすめ順, `01` 新着順, `02` 価格が安い順, `03` 価格が高い順, `04` OFF率の低い順, `05` OFF率の高い順 |
| `includeSoldOut` | `stock=0` | present = include sold-out items (in-stock only when omitted) |
| (pagination) | `page` | 50 cards per page |
| `storeName` | — | the site has `leftnavi_field47=<shop id>`; the Actor filters by name client-side |

### FAQ

**What is KOMEHYO?**
KOMEHYO (コメ兵, Komehyo Holdings) is Japan's largest reuse retailer, founded in Nagoya in 1947, specialising in authenticated luxury goods: brand bags, watches, jewelry, fashion, cameras, instruments and kimono. Every item is graded 新品 / 未使用品 / 中古品S / A / B / C and listed with the physical store that holds it.

**Do I need a proxy?**
No. The site serves the search and product pages to Apify's datacenter IPs at the default 3-second delay. `proxyConfiguration` is there if you need it.

**How are sizes and conditions normalized?**
`sizeRaw` keeps the site text; `sizeNorm` interprets it (`waist` inches for `W32`, `alpha` for `S/M/L/LL→XL`, `numeric` for JP sizes such as `3`, `cm` for shoes, `free`). `conditionRank` uses 6 = best … 2 = worst — the same scale as our Trefac and Mercari scrapers, so results from several Actors can be merged; `conditionLabel` keeps KOMEHYO's own grade.

**Can I monitor new arrivals?**
Yes — use `"sort": "newest"` with a brand / category / price cap, schedule the Actor and diff `itemId` against the previous run. Listings also carry `arrivalDate` and the 新入荷 label.

**Can I get sold items?**
Set `includeSoldOut: true` — listings marked SOLD OUT are returned with `soldOut: true` and their last price. There is no sale date on the site.

**Is this legal?**
The Actor collects public product data only — no login, no cart, no personal data — obeys robots.txt (which allows the search and product pages) and throttles requests. How you use the data is your responsibility; respect the site's terms of use, keep runs small and scheduled, and do not republish its photos or texts as your own.

**How do I call it from code or from an AI agent?**
Any Apify client works. With the JavaScript client:

```js
import { ApifyClient } from "apify-client";
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor("tokyo-select-jp/komehyo-search-scraper").call({
  searches: [{ brand: "LOUIS VUITTON", categoryPath: "bags", rankMin: 4, sort: "priceAsc" }],
  maxItemsPerSearch: 100,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

or with plain HTTP (`run-sync-get-dataset-items` returns the results directly):

```
POST https://api.apify.com/v2/acts/tokyo-select-jp~komehyo-search-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN
Content-Type: application/json

{ "keywords": ["Rolex Datejust"], "maxItemsPerSearch": 50 }
```

The Actor is also exposed through Apify's MCP server (`https://mcp.apify.com`), so Claude, ChatGPT, Cursor and other MCP-capable assistants can search KOMEHYO by calling this Actor as a tool.

### Pricing (pay per event)

| Event | Charged when | Price |
|---|---|---|
| Result (`apify-default-dataset-item`, charged automatically by Apify) | one listing is saved to the dataset | $0.002 |
| Product page (`detail-page`) | that listing was enriched from its product page | $0.005 (in addition to the result) |
| Market summary (`summary`) | one summary row is saved (outputMode `summary` / `both`) | $0.03 per search |
| Actor start (`apify-actor-start`) | each run starts | $0.00005 |

Example: 100 listings with detail ≈ **$0.70**; without detail **$0.20**. A `summary`-only run over 3 searches ≈ 3 × $0.03 = **$0.09**, whatever the number of listings sampled.
Set **Max total charge** on the run to cap spending — the Actor stops cleanly at the limit and you keep everything collected so far.

### Roadmap — JP Data Works

Scrapers for Japanese secondhand and auction marketplaces with one normalized shape (`priceJpy`, `sizeNorm`, `conditionRank`, `imageUrls`):

- **Trefac (トレファク)** — [published](https://apify.com/tokyo-select-jp/trefac-search-scraper)
- **Mercari (メルカリ)** — [published](https://apify.com/tokyo-select-jp/mercari-search-scraper), incl. sold prices
- **KOMEHYO (コメ兵)** — this Actor
- **Yahoo! Auctions (ヤフオク!)**, **2nd STREET**, **RAGTAG** — coming
- A cross-site aggregator (one query → all stores)

Requests and bug reports: the Issues tab of this Actor.

***

### 日本語

**コメ兵（komehyo.jp、国内最大級のブランドリユース）をキーワード・ブランド・カテゴリ・性別・商品ランク・価格帯・並び順（新着順など）で検索し、構造化された商品データを返す Actor です。** ブランドバッグ・時計・ジュエリー・メンズ/レディースファッション・財布小物・カメラ・ギター・きもの・筆記具が対象。オプションで商品ページを開き、**実寸（cm）・品番・カラー・素材・全画像**を付加します。

用途: ブランド品・古着の仕入れリサーチ（eBay / Chrono24 / Grailed 転売）、ブランド別の相場・新着監視、国内リユース市場の調査。

#### 出力（1 商品 = 1 行）

- `itemId`（goodsNo）/ `productCode`（商品コード）/ `url` / `title` / `brand` / `brandKana` / `itemName`
- `priceJpy`（税込）/ `referencePriceJpy`（参考上代）
- `sizeRaw` と `sizeNorm` / `size`（`W32`、`L`、`JP3`、`26.5cm`、`FREE`）
- `conditionRank`（6 新品・未使用品 / 5 中古品S / 4 中古品A / 3 中古品B / 2 中古品C。他の JP Data Works Actor と同じ尺度）、`conditionLabel`（コメ兵の表記）
- `storeName`（在庫店舗）、`arrivalDate`（入荷日）、`labels`（新入荷 等）、`isNewArrival`、`soldOut`
- `material`、`gender`、`categoryPath`、`imageUrl` / `imageUrls`、`fetchedAt`、`keyword`、`search`

**「商品ページで補完」(enrichDetail) を ON にすると追加で:** `modelNumber`（品番型式）、`conditionNote`（例: 使用感のある中古品）、`measurementsCm`（肩幅 / 身幅 / 袖丈 / 着丈 / ウエスト / 股下 / 股上 / わたり / 裾幅 …）、`color`、`description`、`returnPolicy`、パンくずの `categoryPath`、フルサイズの全画像。

#### 入力

`keywords`（キーワードだけ）と `searches`（構造化検索）を併用できます。トップレベルの `sort` / `gender` / `priceMinJpy` / `priceMaxJpy` / `rankMin` / `includeSoldOut` / `excludeWords` は全検索の既定値で、各検索内の指定が優先されます。

| 項目 | 既定 | 説明 |
|---|---|---|
| `keywords` | — | 検索キーワード（1 行 1 件）。`searches` があれば省略可 |
| `searches` | — | 構造化検索の配列（下表）。各要素にキーワード・ブランド・カテゴリのいずれかが必要 |
| `sort` | `recommended` | `recommended` おすすめ順 / `newest` 新着順 / `priceAsc` / `priceDesc` / `discountAsc` / `discountDesc` OFF率 |
| `gender` | `any` | `mens` / `ladies` / `any` |
| `priceMinJpy` / `priceMaxJpy` | なし | 価格帯。サイト側は固定の価格帯（〜3 万 / 3〜10 万 / 10〜25 万 / 25〜50 万 / 50 万〜）しか絞れないので、収まる場合だけサーバー側で使い、正確な上下限は常にクライアント側で適用（価格順なら途中で打ち切り） |
| `rankMin` | なし | 商品ランク下限 2〜6（6 新品・未使用品 … 2 中古品C） |
| `includeSoldOut` | false | SOLD OUT も返す |
| `excludeWords` | `[]` | タイトルにこの語を含む商品を除外 |
| `maxItemsPerSearch` | 100 | 検索ごとの最大件数（1 ページ 50 件） |
| `maxTotalItems` | なし | 1 実行の上限 |
| `enrichDetail` | false | 商品ページを開いて補完（1 商品 +1 リクエスト） |
| `maxDetailPages` | 100 | 商品ページ取得の上限 |
| `requestDelayMs` | 3000 | リクエスト間隔（ms）。3000 以上を推奨 |
| `proxyConfiguration` | なし | 通常は不要 |

`searches` の各要素: `keyword` / `brand`（英語名・カナ名。サイトのブランド一覧で ID に変換）/ `brandId`（brandNo。1734 = KAPITAL）/ `categoryPath`（`mens`、`ladies`、`bags`、`watches mens`、`jewelry`、`camera`、`guitar`、`kimono`、`stationery`、または `mens > bottoms > jeans`、`メンズファッション > トップス > Tシャツ`、`bags > トートバッグ` のようなパス）/ `categoryCode`（dispNo。009001009003 = メンズ > ボトムス）/ `gender` / `priceMinJpy` / `priceMaxJpy` / `rankMin` または `rankIds`（サイトの 1 新品 / 2 未使用品 / 3 中古品S / 4 中古品A / 5 中古品B / 6 中古品C）/ `sort` / `includeSoldOut` / `storeName`（店舗名の部分一致、クライアント側）/ `excludeWords`。

##### 入力例

ブランドのメンズ新着 ¥30,000 以下（スケジュール実行して `itemId` の差分を取る用途）:

```json
{
  "searches": [{ "brand": "KAPITAL", "categoryPath": "mens", "sort": "newest", "priceMaxJpy": 30000 }],
  "maxItemsPerSearch": 100
}
```

ルイ・ヴィトンのトートバッグ、中古品A 以上、安い順、詳細付き:

```json
{
  "searches": [{ "brand": "LOUIS VUITTON", "categoryPath": "bags > トートバッグ", "rankMin": 4, "sort": "priceAsc" }],
  "maxItemsPerSearch": 200,
  "enrichDetail": true,
  "maxDetailPages": 200
}
```

サイトの URL パラメータとの対応は英語セクション「Search URL parameters」を参照してください。

#### 料金（Pay per event）

| イベント | 課金タイミング | 価格 |
|---|---|---|
| 結果（`apify-default-dataset-item`、Apify が自動課金） | 商品 1 件をデータセットに保存したとき | $0.002 |
| 商品ページ（`detail-page`） | その商品を商品ページで補完したとき（結果に加算） | $0.005 |
| Actor 起動（`apify-actor-start`） | 実行ごと | $0.00005 |

例: 100 件を詳細付きで取得 ≈ $0.70、詳細なし ≈ $0.20。「Max total charge」で上限を設定すると安全に停止し、それまでの結果は残ります。

#### 利用上の注意

- komehyo.jp の robots.txt は全ページのクロールを許可しています（Disallow なし）。本 Actor は 1 リクエストずつ、既定 3 秒間隔でアクセスし、ログイン・カート・購入操作は一切行いません。
- データの利用はご自身の責任で、サイトの利用規約を守り、過度なアクセスや画像・文章の無断転載はお控えください。

# Changelog

This Actor's version history is a separate document: https://apify.com/tokyo-select-jp/komehyo-search-scraper/changelog.md

# Actor input Schema

## `keywords` (type: `array`):

Simple keyword searches, one per line — brand names, item types, model numbers, Japanese or English (e.g. `KAPITAL`, `ルイヴィトン モノグラム`, `Rolex Datejust`). Each keyword is one search and inherits the defaults below. Optional when `searches` is set.

## `searches` (type: `array`):

Advanced searches as JSON objects. Every field is optional, but each search needs at least one of `keyword`, `brand`, `brandId`, `categoryPath`, `categoryCode`.

- `keyword` — free text.
- `brand` — brand name as listed on komehyo.jp (English or katakana, e.g. `KAPITAL`, `キャピタル`, `LOUIS VUITTON`); resolved to the site's brand id. `brandId` — that id directly (e.g. 1734 = KAPITAL).
- `categoryPath` — `mens`, `ladies`, `bags`, `watches mens`, `jewelry`, `camera`, `guitar`, `kimono`, `stationery`, or a path such as `mens > bottoms > jeans`, `メンズファッション > トップス > Tシャツ`, `bags > トートバッグ`; `categoryCode` — the site's dispNo code (009001009003 = メンズファッション > ボトムス).
- `gender` — `mens`, `ladies`, `any`.
- `priceMinJpy` / `priceMaxJpy` — exact bounds (applied client-side; the site only has fixed buckets, which are used when the range fits one).
- `rankMin` — minimum condition rank 2–6 (6 = 新品 / 未使用品, 5 = 中古品S, 4 = 中古品A, 3 = 中古品B, 2 = 中古品C), or `rankIds` — the site's rank ids 1 新品, 2 未使用品, 3 中古品S, 4 中古品A, 5 中古品B, 6 中古品C.
- `sort` — `recommended` (default), `newest`, `priceAsc`, `priceDesc`, `discountAsc`, `discountDesc`.
- `includeSoldOut` — also return SOLD OUT items (default false).
- `storeName` — keep only items held by a shop whose name contains this text (client-side).
- `excludeWords` — drop items whose title contains any of these (client-side).

Values set here override the defaults below.

## `outputMode` (type: `string`):

`items` (default): one dataset row per listing. `summary`: one market-summary row per search instead of the listings — sample size, price min / p25 / median / mean / p75 / max, price histogram, status / condition-rank / size / brand / category breakdowns, cheapest listings — billed once per search as the `summary` event (the sampled listings are not billed). `both`: listings plus the summary row.

## `sort` (type: `string`):

Applied to every keyword / search without its own `sort`.

## `gender` (type: `string`):

Applied to every search without its own `gender`.

## `priceMinJpy` (type: `integer`):

Lower price bound for every search without its own `priceMinJpy`.

## `priceMaxJpy` (type: `integer`):

Upper price bound for every search without its own `priceMaxJpy`.

## `rankMin` (type: `integer`):

Only listings with this condition rank or better: 6 新品 / 未使用品, 5 中古品S (close to unused), 4 中古品A (little sign of use), 3 中古品B (visible use), 2 中古品C (heavy use). Leave empty for all.

## `includeSoldOut` (type: `boolean`):

Also return listings marked SOLD OUT (useful for price history).

## `excludeWords` (type: `array`):

Drop items whose title contains any of these words (case-insensitive).

## `maxItemsPerSearch` (type: `integer`):

Stop after this many listings for each keyword / search. The site shows 50 listings per page.

## `maxTotalItems` (type: `integer`):

Hard cap on listings saved in this run across all searches. Leave empty for no cap (Max total charge still applies).

## `dedupeAcrossSearches` (type: `boolean`):

Save a listing only once when several searches return it.

## `enrichDetail` (type: `boolean`):

Open each product page for model number, condition note, gender, measurements in cm, material, colour, category path, description, return policy and the full-size gallery. One extra request and one `detail-page` event per item.

## `maxDetailPages` (type: `integer`):

Cap on product-page requests per run. Items beyond the cap are returned without detail fields.

## `requestDelayMs` (type: `integer`):

Minimum pause between requests. Please keep ≥ 3000.

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

Optional Apify Proxy or your own proxies. Not needed under normal use.

## `outputFields` (type: `array`):

Keep only these top-level fields in the output (`itemId` and `url` are always kept). Leave empty for all fields.

## Actor input object example

```json
{
  "keywords": [
    "KAPITAL"
  ],
  "searches": [
    {
      "brand": "KAPITAL",
      "categoryPath": "mens",
      "priceMaxJpy": 30000,
      "sort": "newest"
    }
  ],
  "outputMode": "items",
  "sort": "recommended",
  "gender": "any",
  "includeSoldOut": false,
  "excludeWords": [],
  "maxItemsPerSearch": 100,
  "dedupeAcrossSearches": true,
  "enrichDetail": false,
  "maxDetailPages": 100,
  "requestDelayMs": 3000,
  "proxyConfiguration": {
    "useApifyProxy": false
  },
  "outputFields": []
}
```

# Actor output Schema

## `listings` (type: `string`):

All scraped items (default dataset)

# 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 = {
    "keywords": [
        "KAPITAL"
    ],
    "searches": [
        {
            "brand": "KAPITAL",
            "categoryPath": "mens",
            "priceMaxJpy": 30000,
            "sort": "newest"
        }
    ],
    "sort": "recommended",
    "maxItemsPerSearch": 100,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("tokyo-select-jp/komehyo-search-scraper").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 = {
    "keywords": ["KAPITAL"],
    "searches": [{
            "brand": "KAPITAL",
            "categoryPath": "mens",
            "priceMaxJpy": 30000,
            "sort": "newest",
        }],
    "sort": "recommended",
    "maxItemsPerSearch": 100,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("tokyo-select-jp/komehyo-search-scraper").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 '{
  "keywords": [
    "KAPITAL"
  ],
  "searches": [
    {
      "brand": "KAPITAL",
      "categoryPath": "mens",
      "priceMaxJpy": 30000,
      "sort": "newest"
    }
  ],
  "sort": "recommended",
  "maxItemsPerSearch": 100,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call tokyo-select-jp/komehyo-search-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,tokyo-select-jp/komehyo-search-scraper"
        }
    }
}
```

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/M5gVQM7IGeXo0KzGt/builds/Ky6eXvc7gEbVaOmR4/openapi.json