# Mercari Japan Scraper – Listings & Item Details (`datalab-jp/mercari-japan-listings-scraper`) Actor

Scrape Mercari Japan listings, sold prices and item details. Search many keywords or paste Mercari URLs; filter by brand, category, condition and shipping; exclude keywords; pick individual sellers or Mercari Shops; enrich with descriptions, photos, seller ratings and shipping. Read-only, MCP-ready.

- **URL**: https://apify.com/datalab-jp/mercari-japan-listings-scraper.md
- **Developed by:** [Task Data](https://apify.com/datalab-jp) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 listing results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## Mercari Japan Scraper – Listings & Item Details

Extract **listings, sold prices, and full item details** from [Mercari Japan](https://jp.mercari.com/) (メルカリ), Japan's largest consumer-to-consumer marketplace — **titles, prices, condition grades, seller type (individual or Mercari Shops), seller ratings, shipping method and origin, photos, descriptions, and timestamps**. Search by **several keywords at once or by Mercari URLs**, narrow results with Mercari's own **brand, category, condition, and shipping filters**, drop noise with **exclude keywords**, and switch on **item-detail enrichment** when you need the full picture. Built for international resellers, proxy-buying (代購) services, price researchers, and AI agents. No coding required.

### What data can you extract?

Every row is one listing. Listing-level fields come from Mercari's search results; detail fields are filled when `fetchItemDetails` is on or when you pass an item URL.

| Field | Description |
|-------|-------------|
| `itemId`, `url`, `title` | Mercari item ID (`m…` for individual listings, alphanumeric for Shops), link, title (Japanese) |
| `price`, `currency` | Listed price in JPY (`null` when the seller set no price) |
| `status` | `selling`, `trading` (sale in progress) or `sold` |
| `sellerType`, `saleFormat` | `individual` or `shop` (Mercari Shops storefront); `fixed` or `auction` |
| `condition`, `conditionId` | Mercari condition grade 1 (新品、未使用) – 6 (全体的に状態が悪い) |
| `categoryId`, `categoryPath` | Category ID; full path such as `ゲーム・おもちゃ・グッズ > トレーディングカード > ポケモンカードゲーム` (detail) |
| `brandId`, `brandName` | Brand when the listing has one |
| `sellerId`, `shopId`, `shopName` | Seller (user) ID for individuals; shop ID and name for Shops |
| `shippingPayer`, `shippingIncluded` | Who pays **domestic** shipping (`seller` = 送料込み) and the derived boolean |
| `shippingMethodId`, `shippingMethod`, `shippingFromArea`, `shippingDuration` | Shipping method, prefecture it ships from, stated dispatch time (detail) |
| `sellerName`, `sellerRatingScore`, `sellerRatingsGood` / `Normal` / `Bad`, `sellerNumRatings` | Seller display name and rating breakdown; shop name, score and review count for Shops (detail) |
| `numLikes`, `numComments`, `description` | Engagement and the full description (detail) |
| `imageUrl`, `imageUrls` | Thumbnail and all photo URLs (original size after detail) |
| `auction` | Mercari auction data when the listing is an auction, else `null` |
| `createdAt`, `updatedAt` | ISO 8601 timestamps |
| `keyword`, `keywordUsed`, `keywordMapped`, `sourceUrl` | What you asked for, what was actually searched, whether a Japanese alias was applied, and the URL a row came from |
| `marketplace`, `detailFetched`, `scrapedAt` | Always `mercari`; whether the row was enriched; collection time |

Rows are unique per `itemId` within a run — if two keywords return the same listing you get it once.

### Why scrape Mercari Japan?

- **Sold-price research (comps)** — set `status` to `["sold_out"]` to get real transaction prices, not asking prices, for any keyword or brand.
- **Sourcing for resale and 代購 (proxy buying)** — filter to individual sellers, exclude bulk lots (`まとめ売り`) and junk, and see immediately whether the price includes domestic shipping.
- **Brand and category sweeps** — pass Mercari `brandId` / `categoryId` values (or simply a Mercari search URL with the filters you set on the website) instead of guessing product names.
- **Due diligence before buying** — pull the seller's rating breakdown, shipping origin, dispatch time and full description with `fetchItemDetails`, or paste item URLs to check specific listings.
- **New-listing monitoring** — `sortBy: "created"` on a schedule surfaces fresh listings; see *Scheduling & automation* below.
- **AI agents / RAG** — structured Japanese marketplace data for LLM workflows. This Actor is discoverable and callable through the [Apify MCP server](https://mcp.apify.com/).

### How to use it (no coding)

1. Click **Start** (or **Try for free**).
2. Enter one or more **Search keywords** — Japanese terms match best, e.g. `ポケモンカード`, `ガンプラ`, `iPhone 15`.
3. Pick the **Listing status** you want (on sale, sold, trading) and set **Max items** per keyword.
4. Open **Advanced** to paste Mercari URLs, add exclude keywords, restrict seller type, brand, category, condition or price, and tick **Fetch item details** if you need descriptions, photos and seller ratings.
5. Click **Start** and download JSON, CSV or Excel — or read the results through the API (below). A per-keyword summary is saved to the key-value store as `SEARCH_REPORT`.

### Input example

```json
{
  "keywords": ["ポケモンカード", "遊戯王"],
  "status": ["sold_out"],
  "excludeKeywords": ["まとめ売り", "ジャンク"],
  "sellerType": "individual",
  "itemConditionId": [1, 2],
  "priceMin": 1000,
  "sortBy": "created",
  "maxItems": 200,
  "fetchItemDetails": false
}
```

Or by URL:

```json
{
  "startUrls": [
    { "url": "https://jp.mercari.com/search?keyword=ガンプラ&status=on_sale&item_condition_id=1,2&price_min=3000&sort=created_time&order=desc" },
    { "url": "https://jp.mercari.com/item/m92095892715" },
    { "url": "https://jp.mercari.com/shops/product/2JUuVF27YiZ7f4cohiJWfr" }
  ],
  "maxItems": 100
}
```

All fields are optional. Running with no input performs a health-check search for `ポケモンカード` (on sale, 100 items).

### Output example

A sold listing with details fetched:

```json
{
  "marketplace": "mercari",
  "itemId": "m68528641575",
  "title": "MGSD デスティニーガンダム",
  "price": 7900,
  "currency": "JPY",
  "status": "sold",
  "sellerType": "individual",
  "saleFormat": "fixed",
  "condition": "新品、未使用",
  "conditionId": 1,
  "categoryId": "1016",
  "categoryPath": "ホビー・楽器・アート > 模型・プラモデル > ロボット",
  "brandId": null,
  "brandName": null,
  "sellerId": "512340987",
  "sellerName": "ぐり",
  "sellerRatingScore": 5,
  "sellerRatingsGood": 312,
  "sellerRatingsNormal": 1,
  "sellerRatingsBad": 0,
  "sellerNumRatings": 313,
  "shopId": null,
  "shopName": null,
  "shippingPayer": "seller",
  "shippingIncluded": true,
  "shippingMethodId": 14,
  "shippingMethod": "らくらくメルカリ便",
  "shippingFromArea": "長崎県",
  "shippingDuration": "1~2日で発送",
  "numLikes": 4,
  "numComments": 0,
  "description": "MGSD デスティニーガンダム 新品未開封です。…",
  "imageUrl": "https://static.mercdn.net/thumb/item/webp/m68528641575_1.jpg",
  "imageUrls": ["https://static.mercdn.net/item/detail/orig/photos/m68528641575_1.jpg"],
  "url": "https://jp.mercari.com/item/m68528641575",
  "auction": null,
  "createdAt": "2026-09-07T10:12:44.000Z",
  "updatedAt": "2026-09-08T02:41:09.000Z",
  "keyword": "ガンプラ",
  "keywordUsed": "ガンプラ",
  "keywordMapped": false,
  "sourceUrl": null,
  "detailFetched": true,
  "scrapedAt": "2026-09-09T06:12:03.418Z"
}
```

Without `fetchItemDetails`, the detail-only fields (`description`, `sellerName`, ratings, `shippingMethod`, `shippingFromArea`, `shippingDuration`, `numLikes`, `numComments`, `categoryPath`) are `null` and `imageUrls` holds the search-result photo URLs.

#### SEARCH\_REPORT (key-value store)

Every run also writes a `SEARCH_REPORT` record with, per keyword or URL: `numFound` (Mercari's match count, capped at 15,000), `listingsReturned`, `duplicatesSkipped`, `detailFailed`, and a `status` of `ok`, `partial`, `not_found`, `mapped_and_retried`, `detail_failed`, `skipped_limit`, `blocked_suspected`, `unexpected_response` or `request_failed`, plus a plain-language `hint` telling you what to try next. Zero results are never silent.

### Data guarantees

- **One row per listing, unique by `itemId` within a run.** Use `itemId` as your idempotency key when merging runs.
- **Zero results cost nothing.** There is no start fee; you pay only for listings actually returned (and for detail pages actually fetched).
- **Detail is billed only on success.** If an item page cannot be fetched, the row keeps its listing-level fields and no `item-detail` event is charged; item URLs that cannot be fetched produce no row and are explained in `SEARCH_REPORT`.
- **Hard cost caps.** `maxItems` limits each keyword/URL, `maxTotalItems` (default 1,000) limits the whole run.
- **Zero-result keywords are explained.** A short verified alias table retries a handful of Chinese franchise names (e.g. `宝可梦` → `ポケモン`) in Japanese and marks the row with `keywordMapped: true`; everything else gets a `hint`.
- **Japanese labels throughout.** Condition grades, shipping methods and prefectures are returned in Japanese, exactly as Mercari shows them.

### Scheduling & automation

- **New-listing monitor**: run on a schedule with `sortBy: "created"` and a modest `maxItems`. Mercari orders "newest" by **`updatedAt`**, not `createdAt` — sellers bump old listings back to the top — so keep the highest `updatedAt` you have processed and treat anything newer as new. Keying on `createdAt` will skip bumped listings.
- **Webhooks and integrations**: connect a run-finished webhook to Slack, Discord, Zapier or Make, or push the dataset to Google Sheets, from the Actor's *Integrations* tab.
- **Public Tasks**: the *Examples* tab contains ready-made tasks (brand sweep, sold comps, item-URL details) you can copy and schedule.

### Performance

Search pages are fetched sequentially (120 listings per page); detail pages are fetched four at a time. Measured on the Apify platform (direct connection, 2026-09-09): 450 listings across three keywords in 12.6 seconds; 3 listings with full details in about 7 seconds including start-up. Mercari exposes at most 15,000 matches per search.

### How much does it cost?

Pay-per-event, no start fee:

| Event | What it is | Price |
|---|---|---|
| Listing result (`apify-default-dataset-item`) | Each listing row returned | $0.004 (FREE plan) · $0.003 (BRONZE) · $0.002 (SILVER and above) |
| Item detail (`item-detail`) | Each row successfully enriched from its item page | $0.008 |

A run that returns 100 listings without details costs about $0.40 on the FREE plan; the same 100 listings **with** details cost about $1.20 (100 × $0.004 + 100 × $0.008). Item and Shops URLs always fetch details, so each is one listing result plus one item detail. Use `maxItems` and `maxTotalItems` to cap spend.

### Integrations: API, MCP, and AI agents

This Actor is **read-only**: it reads publicly available listing data through the same API the Mercari website uses, performs no login, purchase, or write actions, and is safe for autonomous agents to call.

#### API (curl)

```bash
curl -X POST "https://api.apify.com/v2/acts/datalab-jp~mercari-japan-listings-scraper/run-sync-get-dataset-items?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"keywords": ["ポケモンカード"], "status": ["sold_out"], "maxItems": 50}'
```

> Synchronous runs time out after 300 seconds. For large scrapes, use the standard [run endpoint](https://docs.apify.com/api/v2/act-runs-post) and fetch the dataset afterwards.

#### Python (apify-client)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("datalab-jp/mercari-japan-listings-scraper").call(run_input={
    "keywords": ["ポケモンカード"],
    "status": ["sold_out"],
    "maxItems": 50,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
report = client.key_value_store(run["defaultKeyValueStoreId"]).get_record("SEARCH_REPORT")["value"]
```

#### JavaScript (apify-client)

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

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });
const run = await client.actor('datalab-jp/mercari-japan-listings-scraper').call({
    keywords: ['ポケモンカード'],
    status: ['sold_out'],
    maxItems: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
```

#### Use with AI agents (MCP)

This Actor is available through the [Apify MCP server](https://mcp.apify.com/) and eligible for agentic payments. Claude, ChatGPT-based agents and any MCP client can discover it with `search-actors` ("Mercari Japan listings"), read its inputs with `fetch-actor-details`, and run it with `call-actor`. Practical tips for agents: pass the user's Japanese product name in `keywords`, pass `status: ["sold_out"]` when asked "what does X sell for", pass item URLs in `startUrls` when the user already has a link, and read `SEARCH_REPORT` when a keyword returns nothing.

### Trust & maintenance

- The Actor is exercised by an automated weekly health check (real search, non-zero results) in addition to Apify's daily Store test.
- Mercari changes its API from time to time. Breakages reported on the **Issues** tab are answered within two business days, and fixes ship as new builds without changing the input contract.
- The Actor never returns a fabricated empty result: when Mercari answers with an error or an unexpected body, the run reports `blocked_suspected` or `unexpected_response` in `SEARCH_REPORT` instead of a silent zero.

### Related Actors

Part of a family of Japanese second-hand and resale market scrapers with a consistent row shape, so results can be merged for cross-marketplace comps:

- **Mercari Japan Scraper – Listings & Sold Comps** — the lighter, keyword-only predecessor of this Actor
- **Yahoo! Auctions Sold Scraper** — sold-price history from Japan's largest auction site
- **Japan Flea Market Scraper** — Rakuma & Yahoo! Flea Market listings
- **Suruga-ya Scraper** — used hobby goods, figures, and collectibles
- **CardRush TCG Price Scraper** — trading card prices across 9 card games
- **Melonbooks Scraper** — doujin goods and otaku merchandise
- **Diskunion Scraper** — vinyl, CDs, and City Pop with condition grades

### FAQ

**Which listing states can I combine?**
Any subset of `on_sale`, `sold_out` and `trading`. `sold_out` means completed sales; `trading` means bought but not yet finished. For every state, pass all three.

**How do I find `brandId` or `categoryId`?**
Set the filter on jp.mercari.com and copy the `brand_id` / `category_id` value from the resulting URL — or simply paste that search URL into `startUrls`; the Actor reads the filters for you. Category IDs also appear in the `categoryId` column of any run.

**Can I check one specific listing?**
Yes. Put its URL (`https://jp.mercari.com/item/m…` or `https://jp.mercari.com/shops/product/…`) in `startUrls`. You get that listing with full details, including its current `status`.

**Why did my keyword return nothing?**
Mercari matches Japanese titles. English brand names (e.g. `Supreme`, `iPhone`) work; generic English or Chinese words often do not. Check `SEARCH_REPORT` for the `hint`; a few Chinese franchise names are retried in Japanese automatically.

**Does `shippingIncluded` cover international shipping?**
No. It reflects Japanese domestic shipping only (`seller` pays = 送料込み). International forwarding, proxy fees and customs are outside this data.

**Is scraping Mercari legal?**
This Actor collects only **publicly available** listing data through Mercari's own search and item APIs, without logging in or bypassing any access control, at low request rates. Data returned about sellers is limited to what Mercari displays publicly on the listing page (display name, rating counts, prefecture). You are responsible for using the data in accordance with applicable laws and Mercari's terms of service.

**Can AI agents use this Actor?**
Yes — see *Use with AI agents* above. It is read-only and safe to call autonomously.

**Do I need a proxy?**
No. The Actor connects directly by default — measured on 2026-09-09, 450 listings across three keywords came back in 12.6 seconds with zero errors, at about a quarter of the cost of a residential-proxy run. If Mercari ever blocks direct access, enable Apify Proxy in the input; with no group chosen the Actor falls back to Japan-based residential IPs.

### Compliance & ethics

Read-only; public listing data only; no login, purchase, message or write action; request volume is limited (sequential search pages, four parallel detail fetches, retries with back-off). Seller information is limited to the public display name and rating counts shown on the listing. Use responsibly and in accordance with applicable laws and Mercari's terms.

# Actor input Schema

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

One or more search terms for Mercari Japan, each run as its own search, e.g. \['ポケモンカード'] or \['ガンプラ', 'Nintendo Switch']. Japanese terms match the most listings because titles are Japanese; English brand/model names usually work, and a few known Chinese terms are retried in Japanese when they return nothing. If omitted with no `startUrls`, a health-check search for 'ポケモンカード' runs. Each keyword is capped by `maxItems`, the run by `maxTotalItems`; duplicates across keywords are returned once.

## `status` (type: `array`):

Which listing states to include; pick one or more of 'on\_sale' (currently for sale — sourcing and stock checks), 'sold\_out' (completed sales, i.e. real transaction prices for comps research) and 'trading' (bought, transaction not yet finished). Defaults to \['on\_sale'] when omitted. An empty list is rejected. To get every state, pass all three values; 'sold\_out' does not silently include 'trading'.

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

Maximum listings returned for each keyword or search URL, e.g. 100 for a quick look or 2000 for a full sweep. Each returned listing is one billable result, so together with `maxTotalItems` this is your main cost control. Defaults to 100 when omitted; accepts 1–5000 (Mercari never exposes more than 15,000 matches per search). Pagination stops as soon as the cap or the end of results is reached.

## `startUrls` (type: `array`):

Mercari Japan URLs, mixed freely: a search URL like 'https://jp.mercari.com/search?keyword=ガンプラ\&status=on\_sale' (its filters apply), an item URL 'https://jp.mercari.com/item/m12345678901' (that listing with full details), or a Shops URL 'https://jp.mercari.com/shops/product/…'. Only jp.mercari.com / www.mercari.com are accepted; others are skipped and listed in SEARCH\_REPORT. Leave empty to use `keywords` only. Item and Shops URLs always fetch details (billed as item-detail).

## `excludeKeywords` (type: `array`):

Words that must NOT appear in the listing title, e.g. \['まとめ売り', 'ジャンク'] to drop bulk lots and junk items, or \['ケース'] to drop accessories. Applied by Mercari's own search engine, so the excluded listings never count toward `maxItems`. Leave empty to exclude nothing. Multiple words are combined: a listing is removed if it contains any of them.

## `sellerType` (type: `string`):

Restrict results to individual sellers or Mercari Shops (business storefronts), e.g. 'individual' to source second-hand goods from private sellers or 'shop' to see only professional shop stock. Defaults to 'all' when omitted. The output column `sellerType` tells you which kind each row is; Shops rows link to /shops/product/ URLs and are enriched through the Shops API when details are requested.

## `categoryId` (type: `array`):

Mercari numeric category IDs to restrict the search, e.g. \[1289] for ポケモンカードゲーム or \[82] for all トレーディングカード. Find the ID in the `category_id` parameter of a Mercari search URL after choosing a category on the website, or in the `categoryId` column of a previous run. Leave empty to search all categories. Multiple IDs are OR-ed.

## `brandId` (type: `array`):

Mercari numeric brand IDs, e.g. the `brand_id` value from a Mercari search URL after picking a brand filter on the website. Useful for sourcing one brand across many product names. Leave empty for no brand filter. Multiple IDs are OR-ed; the matched brand is returned in `brandId` / `brandName`.

## `itemConditionId` (type: `array`):

Condition grades to include, using Mercari's scale 1–6: 1 = 新品、未使用 (new, unused), 2 = 未使用に近い (like new), 3 = 目立った傷や汚れなし (no noticeable damage), 4 = やや傷や汚れあり (some wear), 5 = 傷や汚れあり (worn), 6 = 全体的に状態が悪い (poor). Example: \[1, 2] for near-new stock only. Leave empty to include every condition. The grade of each row is returned in `condition` / `conditionId`.

## `shippingPayerId` (type: `array`):

Who pays domestic shipping: 2 = seller (送料込み, price is all-in within Japan) or 1 = buyer (着払い). Example: \[2] to compare only all-in prices. Leave empty to include both. The result is also exposed per row as `shippingPayer` and `shippingIncluded`; note this covers Japanese domestic shipping only, not international forwarding.

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

Lower price bound in Japanese yen, e.g. 1000 to skip cheap accessories or 30000 for high-value items only. Whole yen, no currency symbol. Leave empty for no minimum. Works together with `priceMax`; the pair must satisfy priceMin ≤ priceMax.

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

Upper price bound in Japanese yen, e.g. 5000 for budget items or 100000 to exclude outliers. Whole yen, no currency symbol. Leave empty for no maximum. Works together with `priceMin`.

## `sortBy` (type: `string`):

Result order, mirroring the Mercari website: 'score' (Mercari relevance, default), 'created' (most recently listed first — use this for new-listing monitors), 'priceHigh', 'priceLow', or 'likes' (most liked first). Defaults to 'score' when omitted. Note that 'created' is ordered by `updatedAt`, because sellers can bump an old listing back to the top; a scheduled monitor should track the highest `updatedAt` it has seen.

## `fetchItemDetails` (type: `boolean`):

When true, every listing is enriched from its item page: full description, original-size photos, seller name and rating breakdown, shipping method, origin and lead time, likes, comments and full category path. Defaults to false (listing-level fields only) — faster and cheaper. Each successfully enriched row is billed as one item-detail event on top of the listing result; rows whose detail page cannot be fetched keep listing-level fields and are not billed. Item/Shops URLs are always enriched.

## `autoRetryKeywordMapping` (type: `boolean`):

When true (default), a keyword that returns zero listings and appears in a small, verified alias table (e.g. 宝可梦 → ポケモン, 高达 → ガンダム, 海贼王 → ONE PIECE) is retried once with its Japanese equivalent; the term actually used is returned in `keywordUsed` and `keywordMapped` is set to true. The original keyword is always tried first, and the alias is used only when the original returned nothing. Set to false to disable the retry and get the plain zero result with a hint in SEARCH\_REPORT.

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

Hard cap on listings returned by the entire run, across all keywords and URLs, e.g. 500 for a bounded scheduled job or 10000 for a bulk export. Protects against runaway cost when many keywords are supplied. Defaults to 1000 when omitted; accepts 1–50000. When the cap is hit the run stops paginating and notes `totalLimitReached: true` in SEARCH\_REPORT.

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

Apify Proxy settings. By default the Actor connects directly (no proxy): measured on 2026-09-09, Mercari's APIs answered 450 listings in 12.6 s with zero errors this way, at about a quarter of the cost of a residential proxy. If direct access is ever blocked, enable Apify Proxy here; with no group chosen the Actor uses Japan-based residential IPs (RESIDENTIAL, country JP), the configuration known to work. Residential traffic is billed per GB by Apify.

## Actor input object example

```json
{
  "keywords": [
    "ポケモンカード"
  ],
  "status": [
    "on_sale"
  ],
  "maxItems": 100,
  "startUrls": [],
  "excludeKeywords": [],
  "sellerType": "all",
  "categoryId": [],
  "brandId": [],
  "itemConditionId": [],
  "shippingPayerId": [],
  "sortBy": "score",
  "fetchItemDetails": false,
  "autoRetryKeywordMapping": true,
  "maxTotalItems": 1000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

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

All scraped listings as dataset items: title, price, status, seller type, condition, shipping, seller ratings, photos, description and more (see dataset schema).

## `searchReport` (type: `string`):

Per-keyword / per-URL summary: match count, listings returned, duplicates skipped, detail failures, a status code (ok, partial, not\_found, mapped\_and\_retried, detail\_failed, skipped\_limit, blocked\_suspected, unexpected\_response, request\_failed) and a plain-language hint.

# 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": [
        "ポケモンカード"
    ],
    "status": [
        "on_sale"
    ],
    "maxItems": 100,
    "startUrls": [],
    "excludeKeywords": [],
    "sellerType": "all",
    "categoryId": [],
    "brandId": [],
    "itemConditionId": [],
    "shippingPayerId": [],
    "sortBy": "score",
    "fetchItemDetails": false,
    "autoRetryKeywordMapping": true,
    "maxTotalItems": 1000,
    "proxyConfiguration": {
        "useApifyProxy": false
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("datalab-jp/mercari-japan-listings-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": ["ポケモンカード"],
    "status": ["on_sale"],
    "maxItems": 100,
    "startUrls": [],
    "excludeKeywords": [],
    "sellerType": "all",
    "categoryId": [],
    "brandId": [],
    "itemConditionId": [],
    "shippingPayerId": [],
    "sortBy": "score",
    "fetchItemDetails": False,
    "autoRetryKeywordMapping": True,
    "maxTotalItems": 1000,
    "proxyConfiguration": { "useApifyProxy": False },
}

# Run the Actor and wait for it to finish
run = client.actor("datalab-jp/mercari-japan-listings-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": [
    "ポケモンカード"
  ],
  "status": [
    "on_sale"
  ],
  "maxItems": 100,
  "startUrls": [],
  "excludeKeywords": [],
  "sellerType": "all",
  "categoryId": [],
  "brandId": [],
  "itemConditionId": [],
  "shippingPayerId": [],
  "sortBy": "score",
  "fetchItemDetails": false,
  "autoRetryKeywordMapping": true,
  "maxTotalItems": 1000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}' |
apify call datalab-jp/mercari-japan-listings-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,datalab-jp/mercari-japan-listings-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/aKgm7saic6cfOGWG7/builds/MvuyOIPGl4CZ8nykm/openapi.json