# Mercari Japan Item Search (`superslowsloth/mercari-japan`) Actor

Search Mercari Japan and get one flat row per item: id, name, price in JPY, condition, sold flag, shipping payer, seller id, thumbnail, item URL and timestamps.

- **URL**: https://apify.com/superslowsloth/mercari-japan.md
- **Developed by:** [Superslow Sloth](https://apify.com/superslowsloth) (community)
- **Categories:** E-commerce, AI, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.40 / 1,000 item scrapeds

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

## Mercari Japan Item Search

Search [Mercari Japan](https://jp.mercari.com) and get one flat row per item.
Keywords work in Japanese or English, and every filter the site's own sidebar
offers is here: category, brand, condition, price band, sale status and sort
order.

### What one row contains

| Field | Notes |
|---|---|
| `item_id`, `url` | Member listings live under `/item/`, Mercari Shops listings under `/shops/product/`. The URL is built from the item type, so both are correct. |
| `name` | The listing title, as the seller wrote it. |
| `price_jpy` | Integer yen. Mercari Japan quotes nothing but JPY, so there is no currency column to join on by mistake. |
| `item_condition_id`, `item_condition` | Mercari's grade 1-6 and its Japanese label. |
| `status`, `sold` | `sold` is true only for `ITEM_STATUS_SOLD_OUT`. An item mid-transaction is `ITEM_STATUS_TRADING` and has **not** sold yet. |
| `shipping_payer`, `shipping_payer_id` | `seller` (送料込み) or `buyer` (着払い). Null on shop listings, which report payer id `0` - the question does not apply to them. |
| `seller_id` | The numeric member seller id. Null on Mercari Shops listings, which report seller id `0` - there is no member seller behind them. |
| `seller_rating` | **Always null.** See below. |
| `shop_name` | Set for Mercari Shops listings, null for member listings. |
| `thumbnail_url` | First thumbnail; full-size photos are on the item page. |
| `category_id`, `brand_id`, `brand_name` | Mercari's own ids, reusable as input to a later run. |
| `created_at`, `updated_at` | Unix seconds, plus `created_at_iso` / `updated_at_iso` in UTC. |

#### Why `seller_rating` is null and not zero

Mercari's search endpoint returns a seller id and nothing else about the
seller. Ratings live behind a separate per-seller call that would cost one
extra request for every row returned. Rather than triple the price of a run or
invent a number, this actor reports the absence honestly: `null` means "Mercari
did not say". A `0.0` would read as a seller with terrible feedback, which is a
different claim entirely.

### Sold prices

Set **Sale status** to *Sold out* to research what things actually sell for
rather than what sellers are asking. Mercari keeps sold listings searchable,
and the rows carry the price the item sold at.

### How it fetches

Mercari's web client talks to `api.mercari.jp/v2/entities:search`, signing each
call with a DPoP proof (RFC 9449) - a short ES256 JWT carrying a public key the
client generated itself. No account and no registration are involved, so this
actor generates an ephemeral key per run and signs its own requests. Measured
2026-08-25: that returns HTTP 200 and real rows cold, which is why this ships
against the JSON API rather than scraping the search page's embedded state.

Residential proxy is the default. No proxy country is pinned - narrowing the
exit pool causes more refusals than it prevents - and Mercari answered
non-Japanese exit addresses in testing. If you do start seeing refusals, pin
`JP` in the proxy configuration.

### Billing

Pay per event: a small fee when a run starts (charged only after your input
parses, so a run that fails on bad input costs nothing) and one event per item
row written.

# Actor input Schema

## `keyword` (type: `string`):

What you would type into Mercari's search box. Japanese and English both work - Mercari indexes the listing titles, which are mostly Japanese, so a Japanese keyword usually returns more. Leave empty only if you are searching by category or brand id instead.

## `excludeKeyword` (type: `string`):

Drop listings whose title contains this. Same field Mercari's own "除外キーワード" box sends.

## `categoryIds` (type: `array`):

Mercari numeric category ids to search inside, taken from the category\_id parameter of a Mercari search URL. Leave empty to search every category.

## `brandIds` (type: `array`):

Mercari numeric brand ids, taken from the brand\_id parameter of a Mercari search URL. Leave empty for any brand.

## `itemConditionIds` (type: `array`):

Mercari's six condition grades, by id: 1 new/unused, 2 nearly unused, 3 no noticeable damage, 4 slight damage, 5 damaged, 6 poor overall. Pick any number of them; leave empty for any condition.

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

Lowest price to return, in yen. 0 means no lower bound.

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

Highest price to return, in yen. 0 means no upper bound.

## `status` (type: `string`):

Whether to return items still on sale, items that have already sold, or both. Sold items are what price research is usually after: they are what someone actually paid, not what a seller is asking.

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

How Mercari should order the results before this actor pages through them.

## `maxResults` (type: `integer`):

Stop after this many items. Mercari serves up to 120 per request, so anything up to 120 costs a single call and each further 120 is one more.

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

Residential is the default and is what this actor was measured on. No country is pinned: pinning one narrows the exit pool enough to cause refusals, and Mercari's search API answered addresses outside Japan in testing on 2026-08-25. Pin JP here only if you start seeing refusals.

## Actor input object example

```json
{
  "keyword": "ポケモンカード",
  "priceMin": 0,
  "priceMax": 0,
  "status": "any",
  "sort": "relevance",
  "maxResults": 100,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `items` (type: `string`):

No description

# 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 = {
    "keyword": "ポケモンカード",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("superslowsloth/mercari-japan").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 = {
    "keyword": "ポケモンカード",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("superslowsloth/mercari-japan").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 '{
  "keyword": "ポケモンカード",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call superslowsloth/mercari-japan --silent --output-dataset

```

## MCP server setup

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

```

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/pKGE8ZKtjAbegHglX/builds/WyHCUcAUDLg0vksHW/openapi.json