# Mercari Japan Scraper (`axiomworks/mercari-japan-scraper`) Actor

Scrapes Mercari Japan search results and returns structured listing records with titles, condition, sale status, seller ratings, categories, shipping details and photo links. Supports private-seller listings and Mercari Shops, with optional per-listing details.

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

## Pricing

from $2.23 / 1,000 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?

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

## Mercari Japan Scraper

**Returns:** one row per Mercari Japan listing with title, price, status, condition, sellerName, sellerStarRating, sourceUrl.
**Input:** `{"searchQueries": ["nintendo switch"], "status": "on_sale", "maxItems": 50}`
**Best for:** resale price research, sourcing under a price limit, sold-price history.

This Mercari Japan scraper provides structured public listing data for Mercari Japan API workflows.

```json
{
  "id": "m44713430834",
  "sourceUrl": "https://jp.mercari.com/item/m44713430834",
  "title": "Nintendo Switch バイオハザード オリジンズコレクション",
  "price": 3200,
  "currency": "JPY",
  "status": "on_sale",
  "condition": "No noticeable scratches or stains",
  "sellerName": "Ko_tr15"
}
```

### What does Mercari Japan Scraper do?

Mercari Japan Scraper collects listings from the Mercari Japan marketplace and returns them as clean, structured records. You give it search keywords, a Mercari search URL, a seller profile URL, single listing URLs or item IDs, and it returns one record per listing with the price in yen, the condition, the sold status, the seller's star rating, the category, shipping details and photo links.

It is built for three common jobs:

- **Price research.** Search for a product, filter to sold listings and read the final prices to see what an item really sells for.
- **Sourcing and resale.** Find new listings under a price limit, in a chosen condition, and check how reliable the seller is before you buy.
- **Market monitoring.** Track how many listings exist for a keyword, how fast they sell and how prices move, by running the Actor on a schedule.

The Actor reads public listing data without a login or browser. Both private sellers and Mercari Shops are supported; `listingType` identifies each record.

### What data can you get?

Each record describes one listing. Fields that Mercari does not provide for a listing are returned as `null`.

| Field | Type | Description |
|---|---|---|
| `id` / `itemId` | string | Mercari listing ID (starts with `m` for private sellers, alphanumeric for Mercari Shops) |
| `sourceUrl` | string | Link to the listing on jp.mercari.com |
| `title` | string | Listing title, in Japanese as written by the seller |
| `price` | integer | Price in Japanese yen |
| `currency` | string | Always `JPY` |
| `status` | string | `on_sale`, `trading` or `sold_out` |
| `isSold` | boolean | True when the status is `trading` or `sold_out` |
| `conditionId` | integer | Condition code from 1 (new) to 6 (poor) |
| `condition` | string | English condition label, such as "Like new" |
| `conditionJa` | string | Condition label in Japanese |
| `listingType` | string | `c2c` for private sellers, `shops` for Mercari Shops |
| `imageUrls` | array | Full-size photo URLs |
| `thumbnailUrl` | string | Thumbnail image URL |
| `categoryId` | string | Mercari category ID |
| `categoryName` | string | Leaf category name |
| `categoryPath` | string | Category path from root to leaf |
| `brandName` | string | Brand, when the listing has one |
| `sellerId` | string | Seller ID (shop ID for Mercari Shops) |
| `sellerName` | string | Seller display name |
| `sellerStarRating` | number | Seller star rating from 0 to 5, including fractional scores; null when the seller has no ratings |
| `sellerRatingCount` | integer | Number of ratings the seller has received |
| `sellerRatingGood` / `sellerRatingNormal` / `sellerRatingBad` | integer | Rating breakdown (private sellers) |
| `sellerListingsCount` | integer | Number of items the seller has listed (private sellers) |
| `description` | string | Full listing description |
| `shippingPayer` | string | `seller` when shipping is included, otherwise `buyer` |
| `shippingMethod` | string | Shipping method name |
| `shippingFromArea` | string | Prefecture the item ships from |
| `shippingDuration` | string | Estimated time to ship |
| `likesCount` | integer | Number of likes |
| `commentsCount` | integer | Number of comments (private sellers) |
| `createdAt` | string | When the listing was created, ISO 8601 |
| `updatedAt` | string | Last update time, ISO 8601; for sold items this is roughly the sale time |
| `searchQuery` | string | The keyword or URL that produced the record |

The fields from `sellerName` onward, plus `categoryName`, `categoryPath`, `description` and the shipping fields, come from the per-listing detail data. Turn off `includeDetails` to skip them and get a faster, search-only run.

### How to use Mercari Japan Scraper

1. Open the Actor in Apify Console and go to the Input tab.
2. Add one or more search keywords, or paste Mercari URLs. Keywords can be Japanese or English. Japanese keywords usually find more listings.
3. Optionally set filters: status (all, on sale, sold), price range, condition, category, sort order and excluded words.
4. Set `maxItems` to the number of listings you want per keyword or URL.
5. Click Start. When the run finishes, open the Output tab to view the table or download the dataset as JSON, CSV, Excel or XML.

Tips:

- To research sold prices, set status to `sold_out` and sort by `newest`. Sold items keep their final price.
- To copy a search from the website, apply your filters on jp.mercari.com, copy the address bar URL and paste it into Mercari URLs. Keyword, status, sort, price range, condition, category and brand are read from the URL.
- To list everything a seller has on offer, paste their profile URL, for example `https://jp.mercari.com/user/profile/105354275`.

#### Refresh known item IDs

Use `itemIds` when your catalog already stores Mercari listing identifiers. For example, `{"itemIds":["m25970169864"],"maxItems":1}` loads the same public detail data as its listing URL. An ID beginning with `m` followed by digits selects the private-seller endpoint; other alphanumeric IDs select Mercari Shops. You can mix IDs with keyword searches and URLs. A listing found earlier in the run is not saved again. Single-item inputs always fetch details, even with `includeDetails: false`, because there is no search record to copy.

An unavailable ID produces no dataset row. A blocked lookup is retried, then skipped with a clear status message, allowing later targets to continue. Search-only runs still save the available search fields if an optional detail request fails. No error or placeholder rows are returned.

#### Supported URLs

| URL pattern | What happens |
|---|---|
| `jp.mercari.com/search?...` | Runs that search with the filters from the URL |
| `jp.mercari.com/user/profile/{sellerId}` | Returns the seller's listings, newest first |
| `jp.mercari.com/item/{id}` | Returns that single private-seller listing |
| `jp.mercari.com/shops/product/{id}` | Returns that single Mercari Shops listing |

Any other URL is skipped with a warning in the log. The `/en/` language prefix is accepted.

### Input

| Field | Type | Description |
|---|---|---|
| `searchQueries` | array of strings | Keywords to search, for example `["nintendo switch"]`. Each runs separately. |
| `startUrls` | array | Mercari search, profile or listing URLs; strings or objects with a `url` property |
| `itemIds` | array | Private-seller IDs such as `m25970169864`, or alphanumeric Mercari Shops product IDs; default empty |
| `maxItems` | integer | Listings per keyword or URL, 1 to 5000, default 50 |
| `includeDetails` | boolean | Fetch seller rating, description, category and shipping, default true |
| `status` | string | `all`, `on_sale` or `sold_out`, default `all` |
| `sort` | string | `relevance`, `newest`, `price` or `likes`, default `relevance` |
| `sortOrder` | string | `desc` or `asc`, default `desc` |
| `priceMin` / `priceMax` | integer | Price range in yen |
| `conditions` | array | Any of `new_unused`, `like_new`, `no_noticeable_damage`, `some_damage`, `damaged`, `poor` |
| `categoryIds` | array | Mercari category IDs |
| `excludeKeyword` | string | Words that listings must not contain |
| `brandIds` | array | Mercari brand IDs (the `brand_id` value in a search URL) |
| `sellerIds` | array | Only listings from these seller IDs; combine with keywords |
| `freeShippingOnly` | boolean | Only listings where the seller pays shipping (default false) |
| `proxyConfiguration` | object | Optional Apify Proxy settings |

The `sold_out` status returns both sold items and items in the middle of a transaction, which matches the "Sold" filter on the Mercari website.

When you use `startUrls` with a search URL, the filters in that URL take priority over the matching input fields.

#### Example input

```json
{
  "searchQueries": ["nintendo switch"],
  "status": "sold_out",
  "sort": "newest",
  "priceMin": 1000,
  "priceMax": 30000,
  "conditions": ["new_unused", "like_new"],
  "maxItems": 30,
  "includeDetails": true
}
```

### Output

Every record is pushed to the default dataset. Here is a shortened example for a private-seller listing:

```json
{
  "id": "m42279407418",
  "itemId": "m42279407418",
  "sourceUrl": "https://jp.mercari.com/item/m42279407418",
  "title": "ペーパーマリオ オリガミキング Nintendo Switch",
  "price": 1999,
  "currency": "JPY",
  "status": "trading",
  "isSold": true,
  "conditionId": 3,
  "condition": "No noticeable scratches or stains",
  "conditionJa": "目立った傷や汚れなし",
  "listingType": "c2c",
  "categoryId": "702",
  "categoryName": "Nintendo Switch",
  "categoryPath": "ゲーム・おもちゃ・グッズ > テレビゲーム > Nintendo Switch",
  "brandName": null,
  "sellerId": "935662983",
  "sellerName": "yuyu",
  "sellerStarRating": 5,
  "sellerRatingCount": 399,
  "sellerRatingGood": 399,
  "sellerRatingNormal": 0,
  "sellerRatingBad": 0,
  "sellerListingsCount": 335,
  "shippingPayer": "seller",
  "shippingMethod": "ゆうゆうメルカリ便",
  "shippingFromArea": "未定",
  "shippingDuration": "1~2日で発送",
  "likesCount": 0,
  "commentsCount": 0,
  "searchQuery": "nintendo switch"
}
```

Mercari Shops listings have the same structure. The rating breakdown, seller listing count and comment count are `null` for them, because Mercari does not publish those values for shops. Their `sellerStarRating` and `sellerRatingCount` come from the shop's review score.

A `RUN_SUMMARY` record in the key-value store lists, for each keyword or URL, how many results Mercari reported, how many pages were read, how many items were saved and how many detail lookups failed.

Text such as titles, descriptions, condition names and shipping methods is Japanese, exactly as listed. Field names, status values and the English condition label are in English. No machine translation is applied.

### How much does it cost?

The Actor is charged per result: you pay for each listing saved to the dataset. The exact rate is shown on the Pricing tab of the Actor page,. Use `maxItems` to limit each search and Apify's maximum cost per run to cap spending across all targets. When that spending limit is reached, the Actor stops successfully and says so in its final status. Detail requests are limited to the number of results the remaining budget allows. Setting `includeDetails` to false makes runs finish sooner and use less compute.

Empty searches cost nothing in results, because nothing is saved when a keyword has no matches.

### Use with AI agents (MCP)

You can call this Actor from any MCP-compatible AI assistant through the Apify MCP server. Add this to your MCP client configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=axiomworks/mercari-japan-scraper"
    }
  }
}
```

Example prompts:

- "Find the 20 most recent sold listings for 'nintendo switch' on Mercari Japan and tell me the median price in yen."
- "Search Mercari Japan for ポケモンカード in new or like-new condition, sorted by lowest price, and list the cheapest 10 with their seller ratings."
- "Show me everything seller 105354275 currently has listed on Mercari Japan."

Use `maxItems` to keep agent responses short.

### Integrations and API

You can run the Actor from code with the Apify API clients, and connect it to other tools through Apify integrations, webhooks and schedules.

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("axiomworks/mercari-japan-scraper").call(run_input={
    "searchQueries": ["nintendo switch"],
    "status": "sold_out",
    "sort": "newest",
    "maxItems": 30,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["title"], item["price"], item["status"])
```

#### JavaScript

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

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });
const run = await client.actor('axiomworks/mercari-japan-scraper').call({
    searchQueries: ['nintendo switch'],
    status: 'sold_out',
    sort: 'newest',
    maxItems: 30,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((i) => process.stdout.write(`${i.title} ${i.price}\n`));
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/axiomworks~mercari-japan-scraper/run-sync-get-dataset-items" \
  -H "Authorization: Bearer $APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchQueries": ["nintendo switch"], "status": "sold_out", "maxItems": 30}'
```

Schedule the Actor to run daily and compare datasets over time to follow price changes for a keyword.

### FAQ

**Do I need a Mercari account or cookies?**
No. The Actor only reads public listing data that anyone can see without logging in.

**How many listings can I get per search?**
Up to 5000 per keyword or URL with `maxItems`. Mercari reports at most 15000 matches per search and deep pages can end early, so very broad searches may return fewer than requested. Narrow the search with filters or split it into several searches.

**Does `maxItems` apply to all keywords together?**
No. It applies to each keyword or URL separately. Two keywords with `maxItems` 15 can return up to 30 listings in total. A listing that already appeared for an earlier keyword is not saved twice in the same run.

**Why are some seller fields empty?**
Seller details, description, category and shipping come from the detail data, so they are empty when `includeDetails` is false. Private-seller-only fields, such as the good, normal and bad rating counts, are empty for Mercari Shops listings. A seller with no ratings yet has no star rating.

**What does the sold status mean?**
`on_sale` means the item can still be bought. `trading` means a buyer has already purchased it and the deal is in progress. `sold_out` means the sale is complete. `isSold` is true for the last two.

**Can I find out when an item sold?**
Mercari does not publish an exact sale time. For sold items, `updatedAt` is a close approximation.

**What happens if my keyword finds nothing?**
The run succeeds with zero items and a status message that names the keyword. Nothing is added to the dataset.

**What happens on errors or blocks?**
Blocked or unresolved targets finish successfully with zero rows and a message explaining what to change. Requests start at most twice per second. Direct access is the default; a 403 or 429 response triggers retries through Apify Proxy when available. The HTTP client tries a failed request up to three times with increasing waits. If a detail lookup still fails, the listing is saved with its search fields and the failure is counted in the run summary. You can also enable the proxy option from the start.

**Are prices in yen?**
Yes. All prices are Japanese yen as integers, with `currency` set to `JPY`.

**Is the data in English?**
Titles and descriptions are in the language the seller used, usually Japanese. Status values, field names and the English condition label are in English.

### Is it legal to scrape Mercari?

The Actor collects public Mercari listing information and seller ratings without logging in. Consider applicable privacy rules and the rights attached to listing photos and descriptions before using or republishing the output. Mercari's terms and robots.txt may restrict automated access. Keep request volumes modest and review the requirements that apply to your project.

Mercari Japan Scraper is not affiliated with, endorsed by or sponsored by Mercari. This section is general information, not legal advice.

### Feedback

If a field is missing, a filter does not behave as you expect or a run fails, open an issue from the Actor page in Apify Console with the run link and input. Suggestions for new fields or filters are welcome.

# Actor input Schema

## `searchQueries` (type: `array`):

Keywords to search on Mercari Japan, Japanese or English, e.g. \['nintendo switch', 'ポケモンカード']. Each keyword runs as a separate search. Leave empty if you use startUrls. Missing or blocked targets return no rows; other targets continue.

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

Mercari Japan URLs, e.g. \["https://jp.mercari.com/search?keyword=zelda"] or \[{"url":"https://jp.mercari.com/user/profile/123456789"}]. Accepts /search?keyword=..., /en/ variants, /user/profile/{sellerId}, /item/{id}, /shops/product/{id}. URL filters override the filter fields. Optional alternative to searchQueries/itemIds; dead or blocked URLs return no rows, other targets continue.

## `itemIds` (type: `array`):

Mercari listing IDs to refresh directly, e.g. m13418530363. IDs starting with m followed by digits use private-seller details; other alphanumeric IDs use Mercari Shops. Optional alternative to searchQueries/startUrls. Missing or blocked items return no rows.

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

Maximum listings returned per search query or URL (not shared across targets), 1-5000, default 50. Use 1-5 for a quick test. Item IDs are always one row each.

## `includeDetails` (type: `boolean`):

Fetch each listing detail page data: seller rating, description, category, shipping and likes. Slower; set false for fast search-only fields. Default true.

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

Which listings to return: 'all' (default), 'on_sale' (still available) or 'sold_out' (already sold, includes in-transaction items; useful for sold price history).

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

Sort order: 'relevance' (default), 'newest', 'price' or 'likes'. Direction comes from sortOrder, e.g. sort 'price' with sortOrder 'asc' gives cheapest first.

## `sortOrder` (type: `string`):

'desc' (default, highest or newest first) or 'asc'.

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

Only listings priced at least this many yen, e.g. 1000. Leave empty for no minimum.

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

Only listings priced at most this many yen, e.g. 5000. Leave empty for no maximum.

## `conditions` (type: `array`):

Restrict to these conditions. Allowed: new_unused, like_new, no_noticeable_damage, some_damage, damaged, poor. Empty means all conditions.

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

Mercari category IDs to restrict to, as numbers (the category_id value in a jp.mercari.com search URL), e.g. \[7002]. Empty means all categories.

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

Space-separated words that listings must not contain, e.g. 'junk case'. Optional.

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

Mercari brand IDs to restrict to, as numbers (the brand_id value in a jp.mercari.com search URL), e.g. \[1019]. Empty means all brands.

## `sellerIds` (type: `array`):

Only listings from these seller IDs (the number in /user/profile/{id}), e.g. \['123456789']. Combine with keywords to search within a seller. Empty means all sellers.

## `freeShippingOnly` (type: `boolean`):

If true, only listings where the seller pays shipping (shipping included in the price). Default false.

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

Apify Proxy settings. Direct requests are used by default; HTTP 403/429 responses trigger proxy fallback and retries on fresh sessions.

## Actor input object example

```json
{
  "searchQueries": [
    "nintendo switch"
  ],
  "itemIds": [],
  "maxItems": 20,
  "includeDetails": true,
  "status": "all",
  "sort": "relevance",
  "sortOrder": "desc",
  "freeShippingOnly": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `overview` (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 = {
    "searchQueries": [
        "nintendo switch"
    ],
    "maxItems": 20,
    "includeDetails": true,
    "status": "all"
};

// Run the Actor and wait for it to finish
const run = await client.actor("axiomworks/mercari-japan-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 = {
    "searchQueries": ["nintendo switch"],
    "maxItems": 20,
    "includeDetails": True,
    "status": "all",
}

# Run the Actor and wait for it to finish
run = client.actor("axiomworks/mercari-japan-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 '{
  "searchQueries": [
    "nintendo switch"
  ],
  "maxItems": 20,
  "includeDetails": true,
  "status": "all"
}' |
apify call axiomworks/mercari-japan-scraper --silent --output-dataset

```

## MCP server setup

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