# \[$0.5/1k] Mercari Japan Search, Sellers, Reviews, Price Watch (`cocoa_kit/mercari-jp-scraper`) Actor
Search public Mercari Japan listings, fetch item details, collect seller profiles and reviews, and track price changes with webhook alerts.
- **URL**: https://apify.com/cocoa_kit/mercari-jp-scraper.md
- **Developed by:** [Cocoa Kit](https://apify.com/cocoa_kit) (community)
- **Stats:** 2 total users, 1 monthly users, 72.2% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet
## Pricing
Pay per usage
This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.
Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage
## 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
### Find products, compare prices, and track Mercari Japan
Turn public **Mercari Japan listings into data you can use**. Search for products, check seller inventory and reviews, or track price changes across repeat runs. Start with a keyword or Mercari URL. No code or Mercari account is needed.
- **Find items within your budget.** Filter by price, brand, category, condition, and availability.
- **Compare products in one place.** Collect prices, images, item links, and available product details.
- **Research sellers.** Collect public inventory, profiles, and reviews.
- **Watch for changes.** Track new listings, price changes, and items that reappear. Send alerts to your workflow through a webhook.
- **Use the results your way.** [Export to Excel, CSV, or JSON](https://docs.apify.com/storage/dataset), or retrieve data through the Apify API.
Built for resellers who compare stock, collectors who watch specific products, and researchers who study Japan's resale market.
### Start in three steps
1. Enter a **search keyword**, such as `ソニー カメラ`, or paste a Mercari search or item URL.
2. Set **Maximum results**. Start with 50 items. Add price or availability filters if needed.
3. Click **Start**, then open the results when the run finishes. Export the data in your preferred format.
For a keyword search, this example finds up to 50 Sony camera listings priced at ¥20,000 or less:
```json
{
"keyword": "ソニー カメラ",
"status": "on_sale",
"maxPrice": 20000,
"maxItems": 50
}
```
Use Japanese or English keywords. If you paste a search URL, set the filters on Mercari before you copy it. The Actor keeps the URL's filters.
### What data do you get?
| Choose | Data you can collect | Useful for |
| ----------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------------- |
| Product search | Titles, JPY prices, availability, images, brands, item links, likes, and available auction data | Product sourcing and price comparisons |
| Item details | Descriptions, available images, condition, shipping details, and available comments | Closer product checks |
| Seller inventory and profiles | Public listings, seller names, bios, ratings, and available follower counts | Seller research |
| Seller reviews | Review messages, ratings, dates, and whether the review concerns buying or selling | Feedback analysis |
| Price watch | Change type, previous price, changed fields, and recorded price history | Repeat market checks and alerts |
Search returns basic listing data by default. Turn on `fetchDetails` for more product information. A direct item URL always returns details. Full seller profiles are optional and appear as separate rows.
Here is an illustrative listing, shortened to show the main fields:
```json
{
"kind": "listing",
"id": "m12345678901",
"title": "ソニー デジタルカメラ",
"price": 18000,
"currency": "JPY",
"status": "on_sale",
"url": "https://jp.mercari.com/item/m12345678901",
"detailFetched": false
}
```
Prices are in Japanese yen. An undecided price is `null`, with `isPriceUndecided: true`. Optional data can be unavailable. Current auction bids are not final sale prices.
### Track prices and get alerts
Save a search as a watch to compare listings across runs. See new items, changed prices, and listings that reappear. Price history starts when your watch first observes an item.
```json
{
"keyword": "ソニー カメラ",
"status": "on_sale",
"maxItems": 1000,
"incrementalMode": true,
"stateKey": "sony-cameras",
"notifyOn": ["NEW", "UPDATED", "REAPPEARED"],
"alertBelowPrice": 20000
}
```
Run the same input again to compare results. To check automatically, create an [Apify Schedule](https://docs.apify.com/actors/running/schedules) for the Actor or a saved task. Leave enough time for each run to finish before the next starts.
Add `webhookUrl` to send matching changes to a public HTTPS endpoint. The example selects new, updated, or reappeared listings at **¥20,000 or less**. The Actor also saves selected changes in an `ALERTS` record. A notification service or workflow must receive the webhook to send messages to you.
Unchanged listings are hidden from the main results by default. **Each listing check still counts as work**, even when nothing changes.
### Pricing
Check the Actor's **Pricing** section for current prices before you run it. Start with a small sample and request full details only when you need them.
If pay-per-event pricing is enabled, the Actor counts these units:
| Work | Unit |
| -------------------------------- | ------------------------------------------------- |
| Basic search or seller inventory | One basic listing returned |
| Full item details | One detailed listing or detailed watch check |
| Public seller profile | One separate profile row |
| Reviews | One review returned |
| Basic price watch | One listing checked, including unchanged listings |
A detailed listing replaces the basic listing or check event. A separately requested seller profile is an additional event. An empty change report can still include chargeable checks. Proxy and external notification services can add costs.
### More search options
#### Search several keywords
Use `keywords` for up to 20 search phrases. Duplicate listings appear once per run. All searches share `maxItems`, so a broad first search can use the full limit. Each search keeps its own order.
#### Collect a seller's inventory or reviews
Find the seller ID in a profile URL: `https://jp.mercari.com/user/profile/804436896`.
To collect inventory and a public profile:
```json
{
"mode": "seller",
"sellerIds": ["804436896"],
"includeSellerProfiles": true,
"maxItemsPerSeller": 100,
"maxItems": 100
}
```
Set `maxItemsPerSeller` to `0` for profiles only. Inventory includes public on-sale, trading, and sold listings by default. Use `status` to restrict it.
To collect reviews received as a seller:
```json
{
"mode": "reviews",
"sellerIds": ["804436896"],
"reviewSubject": "seller",
"maxItems": 100
}
```
Use `reviewRatings` to select `good`, `normal`, or `bad` reviews.
All input settings and defaults
| Field | Default | Use |
| ---------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `mode` | `search` | `search`, `seller`, or `reviews`. |
| `keyword` | None | One search phrase, up to 500 characters. |
| `keywords` | `[]` | Up to 20 separate search phrases. |
| `startUrls` | `[]` | Up to 20 `{ "url": "..." }` entries. |
| `sellerIds` | `[]` | Up to 100 numeric seller ID strings. |
| `maxItems` | `50` | 1 to 15,000 unique listings or reviews per run. Extra seller profile rows do not consume this limit. |
| `minPrice`, `maxPrice` | `0` | Keyword price limits in JPY; zero means unbounded. |
| `status` | `all` | `all`, `on_sale`, `sold_out`, `trading`. Mercari search can include trading items in sold searches. |
| `sort` | `relevance` | `relevance`, `newest`, `oldest`, `price_asc`, `price_desc`, `likes`. |
| `categoryIds`, `brandIds` | `[]` | Numeric ID strings for keyword filters. |
| `conditionIds`, `shippingPayerIds` | `[]` | Numeric ID strings for keyword filters. |
| `excludeKeyword` | None | Excluded keyword text. |
| `fetchDetails` | `false` | Fetch an item page for each standard listing. |
| `includeSellerProfiles` | `false` | Return full public profiles as separate rows. |
| `maxItemsPerSeller` | `100` | Inventory limit per seller; 0 for profiles only. |
| `reviewSubject` | `all` | `all`, `seller`, `buyer`. |
| `reviewRatings` | `[]` | Empty means all; otherwise `good`, `normal`, `bad`. |
| `incrementalMode` | `false` | Compare listing observations between runs. |
| `stateKey` | Derived from search | Watch name, 1 to 60 letters, digits, hyphens, or underscores. |
| `emitUnchanged`, `emitExpired` | `false` | Include these change classes in output. |
| `historyLimit` | `30` | Retain 1 to 1,000 change observations per listing. |
| `resumeFromRunId` | None | Skip IDs from a prior run with a saved resume checkpoint. Cannot be combined with monitoring. New output contains only additional rows. For older runs without checkpoints, use resumeDatasetId. |
| `resumeDatasetId` | None | Read IDs from an explicitly selected dataset. Requires read access only. Cannot be combined with resumeFromRunId or monitoring. |
| `webhookUrl` | None | Public HTTPS alert receiver. Requires monitoring. |
| `notifyOn` | NEW, UPDATED, REAPPEARED | Alert change classes. |
| `alertBelowPrice` | None | Optional maximum JPY price for alerts. |
| `proxyConfiguration` | Direct access | Optional Apify or custom proxy. Proxy costs can apply. |
Price watch and webhook details
- Changes are `NEW`, `UPDATED`, `UNCHANGED`, `REAPPEARED`, or `EXPIRED`. The watch compares price, availability, title, condition ID, auction flag, and undecided-price flag.
- Set `emitUnchanged` to include unchanged listings. All checks remain in a separate dataset linked from `SUMMARY`.
- Set `emitExpired` to report listings absent from a fully scanned search. Absence does not prove a sale or deletion. Failed or incomplete scans do not expire missing listings.
- Reuse one `stateKey` for one search. Use a new key for a different search. Do not run the same watch concurrently. Its saved state is in a named key-value store linked from `SUMMARY`.
- Webhooks send batches of up to 50 listings after a successful scan. Failed deliveries are saved and retried on the next run. Use `deliveryId` to reject duplicate deliveries.
- Webhook endpoints must use public HTTPS. Redirects and private network endpoints are rejected. No message is sent when no selected change meets the price threshold.
### FAQ and support
#### Which Mercari pages are supported?
Public HTTPS URLs on `jp.mercari.com`: search pages, standard item pages, seller profiles, and seller review pages. Mercari Shops results can appear in search, but Shops item details are not supported. Item comments include only those returned with the item details.
#### How many results can I collect?
Set `maxItems` from 1 to 15,000 unique listings or reviews per run. The default is 50. Actual results depend on available matches and run limits. Extra seller profile rows do not use this limit.
#### Can I continue a previous collection?
Yes. Use `resumeFromRunId` for a run with a saved checkpoint, or `resumeDatasetId` for an accessible dataset. The new run skips known IDs and returns additional rows. Resume cannot be combined with price monitoring.
#### Can I use the data in my application?
Yes. Run the Actor and retrieve its dataset through the [Apify API](https://docs.apify.com/api/v2). Use JSON for nested data such as images, comments, and price history.
#### What if a run is slow or incomplete?
Full details take longer than basic search. Use smaller batches or allow more run time. Choose 2 to 4 GB of memory. Open `SUMMARY` in the run's storage for counts, failed URLs, limits, and skipped Shops details. Partial results remain available after a failed run.
#### Need help?
Open an issue on the Actor's **Issues** tab. Include the run URL, your search or page type, and the result you expected. Remove tokens and webhook secrets before sharing input.
# Actor input Schema
## `keyword` (type: `string`):
Japanese or English search text. Provide keyword or startUrls.
## `startUrls` (type: `array`):
Public Mercari search, item, seller profile, or seller review URLs. URL search filters are kept.
## `maxItems` (type: `integer`):
Maximum unique listings across the entire run.
## `minPrice` (type: `integer`):
Minimum price for keyword search. Zero means no lower limit.
## `maxPrice` (type: `integer`):
Maximum price for keyword search. Zero means no upper limit.
## `status` (type: `string`):
Availability filter for keyword search.
## `sort` (type: `string`):
Sort order for keyword search. Each supplied search URL keeps its own order.
## `proxyConfiguration` (type: `object`):
Optional proxy for website access. Direct access is the default. Apify proxy use can incur charges.
## `mode` (type: `string`):
Choose search, seller inventory, or seller reviews.
## `keywords` (type: `array`):
Up to 20 search phrases. Each phrase is a separate search.
## `sellerIds` (type: `array`):
Public seller IDs. Up to 100 numeric ID strings.
## `categoryIds` (type: `array`):
Category IDs for keyword searches.
## `brandIds` (type: `array`):
Brand IDs for keyword searches.
## `conditionIds` (type: `array`):
Condition IDs for keyword searches.
## `shippingPayerIds` (type: `array`):
Shipping payer IDs for keyword searches.
## `excludeKeyword` (type: `string`):
Words to exclude from keyword searches.
## `fetchDetails` (type: `boolean`):
Fetch a detail page for each standard Mercari listing. Shops results stay basic.
## `includeSellerProfiles` (type: `boolean`):
Return public seller profiles as separate rows.
## `incrementalMode` (type: `boolean`):
Save listing observations and compare repeat runs. All checked listings count as work, including unchanged listings.
## `emitUnchanged` (type: `boolean`):
Include unchanged listings in the default output.
## `emitExpired` (type: `boolean`):
Return missing listings only after a complete successful scan. Expired means absent from this search, not necessarily deleted.
## `maxItemsPerSeller` (type: `integer`):
Maximum matching listings per seller. Zero returns the profile only.
## `reviewSubject` (type: `string`):
Return reviews received as seller, buyer, or both.
## `reviewRatings` (type: `array`):
Optional review ratings: good, normal, bad.
## `stateKey` (type: `string`):
Optional watch name. Reuse it for the same search. Only one run can update a watch at a time.
## `historyLimit` (type: `integer`):
Maximum saved price/status observations per listing.
## `resumeFromRunId` (type: `string`):
Previous run with a saved resume checkpoint. Older runs can use resumeDatasetId. Cannot be combined with incrementalMode.
## `webhookUrl` (type: `string`):
Optional public HTTPS webhook. Send a JSON alert batch after a successful watch run.
## `notifyOn` (type: `array`):
Changes to notify: NEW, UPDATED, REAPPEARED, EXPIRED.
## `alertBelowPrice` (type: `integer`):
Optional alert threshold in JPY. Only notify when a listing price is at or below this value.
## `resumeDatasetId` (type: `string`):
Read IDs from a previous dataset and skip them. Use this for runs from older versions. Cannot be combined with resumeFromRunId or incrementalMode.
## Actor input object example
```json
{
"keyword": "ソニー カメラ",
"startUrls": [],
"maxItems": 50,
"minPrice": 0,
"maxPrice": 0,
"status": "all",
"sort": "relevance",
"proxyConfiguration": {
"useApifyProxy": false
},
"mode": "search",
"keywords": [],
"sellerIds": [],
"categoryIds": [],
"brandIds": [],
"conditionIds": [],
"shippingPayerIds": [],
"fetchDetails": false,
"includeSellerProfiles": false,
"incrementalMode": false,
"emitUnchanged": false,
"emitExpired": false,
"maxItemsPerSeller": 100,
"reviewSubject": "all",
"reviewRatings": [],
"historyLimit": 30,
"notifyOn": [
"NEW",
"UPDATED",
"REAPPEARED"
]
}
```
# Actor output Schema
## `results` (type: `string`):
No description
## `summary` (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 '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"keyword": "ソニー カメラ",
"startUrls": []
};
// Run the Actor and wait for it to finish
const run = await client.actor("cocoa_kit/mercari-jp-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 '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"keyword": "ソニー カメラ",
"startUrls": [],
}
# Run the Actor and wait for it to finish
run = client.actor("cocoa_kit/mercari-jp-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 '{
"keyword": "ソニー カメラ",
"startUrls": []
}' |
apify call cocoa_kit/mercari-jp-scraper --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"type": "http",
"url": "https://mcp.apify.com/?tools=fetch-actor-details,cocoa_kit/mercari-jp-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 ` 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/lYfYAPek9heiSYPP8/builds/YJBndiSS4fodp6HVT/openapi.json