# Mercari Listings Scraper (`w3crawler/mercari-listings-scraper`) Actor

Extract public Mercari Japan marketplace listings for resale research and price tracking.

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

## Pricing

from $2.99 / 1,000 listings

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

## Mercari Listings Scraper

Collect bounded **public Mercari Japan listings** through the anonymous public search API used by the Mercari Japan web page. Saved rows include item identity, JPY price, sale status, brand and category labels, seller, condition and shipping identifiers, images, canonical item URLs, and source provenance when Mercari publishes them.

### Get started

1. Open the [Actor Store page](https://apify.com/w3crawler/mercari-listings-scraper) and select **Try for free** or open the **Input** tab.
2. Set `query` to the keyword you need, or supply one or more public `startUrls`. URLs take precedence over the query.
3. Lower `maxItems` for a first test and keep `maxPages` at 1 while checking result quality.
4. Start the Actor, open the dataset, and export the saved records as JSON, CSV, or Excel. Open **Run summary** (`OUTPUT`) to check the outcome and counts.

### Input

All fields are optional; the defaults below are ready to use. Unsupported field names and out-of-range values are rejected before requests start.

| Field | Type | Required? | Default | Meaning |
| --- | --- | --- | --- | --- |
| `query` | string | Optional | `iphone` | Keyword used to build a public search URL when `startUrls` is absent, up to 300 characters. |
| `startUrls` | object array | Optional | Not supplied | Public `jp.mercari.com` URLs to inspect; these take precedence over `query`. 1–20 entries. |
| `maxItems` | integer | Optional | `50` | Maximum listing records to emit across all sources, 1–500. |
| `maxPages` | integer | Optional | `1` | Maximum public search API pages per source, 1–20. |
| `timeoutMs` | integer | Optional | `30000` | Maximum wait for each public request, 5,000–120,000 ms. |
| `maxBytes` | integer | Optional | `5000000` | Maximum response size accepted for parsing, 1,000–15,000,000 bytes. |
| `proxyConfiguration` | object | Optional | `{"useApifyProxy":false}` | Optional standard Apify Proxy routing. It does not bypass access challenges. |

Example input matching the saved `iphone` run:

```json
{
  "query": "iphone",
  "maxItems": 3,
  "maxPages": 1,
  "timeoutMs": 30000,
  "maxBytes": 5000000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

The Actor reads the public Mercari Japan search API. It does not log in, use an account token, call a private endpoint, impersonate a browser, or bypass CAPTCHA and anti-automation controls.

### Output

The dataset contains one row per saved listing. Optional values are omitted when Mercari does not publish them; they are not inferred. No diagnostic or placeholder rows are written.

| Field | Type | Availability | Meaning |
| --- | --- | --- | --- |
| `recordType` | string enum | Always | Record type; always `listing`. |
| `recordId` | string | Always | Stable anonymized row identifier. |
| `itemId` | string | Always | Mercari item identifier. |
| `title` | string | Always | Public listing title. |
| `price` | number | Always | Public listing price in JPY. |
| `currency` | string | Always | Currency published by Mercari Japan. |
| `status` | string | Always | Public listing status, such as `ITEM_STATUS_ON_SALE`. |
| `brand` | string | When published | Brand label when exposed. |
| `category` | string | Always | Public category label or identifier. |
| `conditionId` | string | Always | Published condition identifier. |
| `shippingPayerId` | string | Always | Published shipping-payer identifier. |
| `shippingMethodId` | string | Always | Published shipping-method identifier. |
| `sellerName` | string | When published | Seller or shop name when exposed. |
| `sellerId` | string | Always | Public seller identifier. |
| `likes` | integer | Always | Public like count as reported for the row. |
| `imageUrls` | string array | Always | Bounded public item image URLs. |
| `itemUrl` | string | Always | Canonical public Mercari item URL. |
| `sourceUrl` | string | Always | Public search URL that produced the row. |
| `finalUrl` | string | Always | Final public request URL. |
| `httpStatus` | integer | Always | HTTP status observed for the response. |
| `sourceTransport` | string enum | Always | `official_public_api`, `apify_proxy`, or `fixture`. |
| `proxyConfigured` | boolean | Always | Whether standard Apify Proxy routing was configured. |
| `fingerprintApplied` | boolean | Always | Whether a browser fingerprint was applied; this Actor does not apply one. |
| `accessStatus` | string | Always | Normalized access outcome. |
| `success` | boolean | Always | Whether the row is a successful listing extraction. |
| `dataAvailable` | boolean | Always | Whether usable listing data is present. |
| `resultStatus` | string | Always | Listing result status. |
| `position` | integer | Always | One-based position after deduplication. |
| `extractionMethod` | string | Always | Parser representation used for extraction. |
| `inventoryRank` | integer | Always | Catalog inventory rank recorded for provenance. |
| `actorName` | string | Always | Display name of this Actor. |
| `actorSlug` | string | Always | Store slug of this Actor. |
| `actorStoreUrl` | string | Always | Store URL recorded for provenance. |
| `targetHint` | string | Always | Public target scope recorded for provenance. |
| `accessPolicy` | string | Always | Public-access and no-bypass policy recorded for the row. |
| `observedAt` | string | Always | UTC observation timestamp. |
| `scrapedAt` | string | Always | UTC extraction timestamp. |
| `generatedBy` | string | Always | Generator metadata. |
| `fieldCoverage` | string array | Always | Top-level fields populated before sanitization. |
| `dataQuality` | object | Always | Bounded non-empty field quality metadata. |

`dataQuality` contains `recordStatus`, `targetSpecificFieldsClaimed`, `nonEmptyTopLevelFields`, `emptyTopLevelFields`, and `nullTopLevelFields`.

The example below is a real saved row from the 2026-10-25 run. `actorStoreUrl`, `targetHint`, `accessPolicy`, and `fieldCoverage` are omitted for length; every value shown is unchanged.

```json
{
  "recordType": "listing",
  "recordId": "listing:f84ccb2354c0a71ece188835",
  "itemId": "m90523833212",
  "title": "【ジャンク品】 Apple iPhone15 本体",
  "price": 400,
  "currency": "JPY",
  "status": "ITEM_STATUS_ON_SALE",
  "brand": "Apple",
  "category": "859",
  "conditionId": "4",
  "shippingPayerId": "2",
  "shippingMethodId": "14",
  "sellerId": "813968375",
  "likes": 0,
  "imageUrls": [
    "https://static.mercdn.net/item/detail/webp/photos/m90523833212_1.jpg?1792939349",
    "https://static.mercdn.net/thumb/item/webp/m90523833212_1.jpg?1792939349"
  ],
  "itemUrl": "https://jp.mercari.com/item/m90523833212",
  "sourceUrl": "https://jp.mercari.com/search/?keyword=iphone",
  "finalUrl": "https://jp.mercari.com/search/?keyword=iphone",
  "httpStatus": 200,
  "sourceTransport": "official_public_api",
  "proxyConfigured": false,
  "fingerprintApplied": false,
  "accessStatus": "success",
  "success": true,
  "dataAvailable": true,
  "resultStatus": "success",
  "position": 1,
  "extractionMethod": "public-structured-data",
  "inventoryRank": 231,
  "actorName": "Mercari Listings Scraper",
  "actorSlug": "mercari-listings-scraper",
  "observedAt": "2026-10-25T20:48:23.308Z",
  "scrapedAt": "2026-10-25T20:48:23.308Z",
  "generatedBy": "Codex with GPT-5.6 Luna",
  "dataQuality": {
    "recordStatus": "non_empty",
    "targetSpecificFieldsClaimed": true,
    "nonEmptyTopLevelFields": 38,
    "emptyTopLevelFields": 0,
    "nullTopLevelFields": 0
  }
}
```

### Run summary

**Run summary** is stored separately from the dataset in the run's key-value store under `OUTPUT`.

| Field | Meaning |
| --- | --- |
| `status` | Run outcome: `SUCCEEDED` or `FAILED`. |
| `runStatus` | Canonical run status; matches `status`. |
| `dataStatus` | Dataset completeness: `COMPLETE`, `PARTIAL`, `NO_RESULTS`, or `FAILED`. |
| `actorName` | Actor display name. |
| `actorSlug` | Actor store slug. |
| `inventoryRank` | Catalog inventory rank recorded for provenance. |
| `recordCount` | Listing rows saved to the dataset. |
| `listingCount` | Alias of `recordCount`. |
| `diagnosticCount` | Request or extraction issues recorded outside the dataset. |
| `diagnosticCodes` | Diagnostic codes collected during the run. |
| `uniqueRecordCount` | Distinct listing keys after deduplication. |
| `duplicateCount` | Rows discarded as duplicate listing keys. |
| `requestedMaxItems` | Configured global listing cap. |
| `requestedMaxPages` | Configured API page cap per source. |
| `sourceCount` | Unique public source URLs processed. |
| `requestCount` | Public requests attempted. |
| `successfulRequests` | Successful public responses. |
| `pagesFetched` | Successful public pages fetched. |
| `sourceTransport` | Transport used for the run. |
| `proxyConfigured` | Whether standard Apify Proxy routing was configured. |
| `fixtureMode` | Whether a repository-local fixture was used. |
| `fingerprintApplied` | Whether a browser fingerprint was applied; always `false` here. |
| `apiEndpoint` | Anonymous public API endpoint used for live requests. |
| `sourceUrls` | Unique public source URLs processed. |
| `generatedBy` | Generator metadata. |
| `generatedAt` | UTC summary creation time. |

| Status | Data status | Meaning |
| --- | --- | --- |
| `SUCCEEDED` | `COMPLETE` | Listings were saved without an extraction problem. |
| `SUCCEEDED` | `PARTIAL` | Listings were saved, but a later problem prevented a complete run. Saved rows remain available. |
| `SUCCEEDED` | `NO_RESULTS` | The source completed cleanly and returned no matching listings. |
| `FAILED` | `FAILED` | A fatal error occurred before any usable listing was saved. |

Example `OUTPUT` from the 2026-10-25 run:

```json
{
  "status": "SUCCEEDED",
  "runStatus": "SUCCEEDED",
  "dataStatus": "COMPLETE",
  "actorName": "Mercari Listings Scraper",
  "actorSlug": "mercari-listings-scraper",
  "inventoryRank": 231,
  "recordCount": 3,
  "listingCount": 3,
  "diagnosticCount": 0,
  "diagnosticCodes": [],
  "uniqueRecordCount": 3,
  "duplicateCount": 0,
  "requestedMaxItems": 3,
  "requestedMaxPages": 1,
  "sourceCount": 1,
  "requestCount": 1,
  "successfulRequests": 1,
  "pagesFetched": 1,
  "sourceTransport": "official_public_api",
  "proxyConfigured": false,
  "fixtureMode": false,
  "fingerprintApplied": false,
  "apiEndpoint": "https://api.mercari.jp/v2/entities:search",
  "sourceUrls": [
    "https://jp.mercari.com/search/?keyword=iphone"
  ],
  "generatedBy": "Codex with GPT-5.6 Luna",
  "generatedAt": "2026-10-25T20:48:23.486Z"
}
```

### Coverage and limitations

The Actor reads public Mercari Japan search results through the official public API used by the web page. It does not log in, use account credentials, call private endpoints, impersonate a browser, or bypass CAPTCHA and anti-automation controls. `proxyConfiguration.useApifyProxy` enables ordinary Apify Proxy routing; groups and country are optional, and Proxy does not bypass challenges. Prices and statuses are point-in-time values. Optional fields are omitted when the source does not publish them, and blocked, empty, or partial responses are reported in the run summary rather than written as data rows.

### Usage and support

Apify charges standard Actor compute, network, and storage usage. Start with a small `maxItems` and one query, inspect the dataset and `OUTPUT`, then scale pages and sources gradually. See the Actor's Pricing tab for current account rates. Use the [Actor Issues page](https://apify.com/w3crawler/mercari-listings-scraper/issues) to report a problem. Include the run ID, the input used, and the run summary; do not include tokens, cookies, or private data. This Actor is not affiliated with or endorsed by Mercari. Use it only for public data and in accordance with Mercari's terms, robots guidance, and applicable law.

# Actor input Schema

## `query` (type: `string`):

Keyword used to build a public search URL when startUrls is absent.

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

Public jp.mercari.com URLs to inspect; these take precedence over query.

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

Maximum listing records to emit across all sources.

## `maxPages` (type: `integer`):

Maximum public search API pages per source.

## `timeoutMs` (type: `integer`):

Maximum wait for each public request.

## `maxBytes` (type: `integer`):

Maximum response size accepted for parsing.

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

Optional standard Apify Proxy routing; it does not bypass access challenges.

## Actor input object example

```json
{
  "query": "iphone",
  "maxItems": 50,
  "maxPages": 1,
  "timeoutMs": 30000,
  "maxBytes": 5000000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

## `summary` (type: `string`):

No description

## `runSummary` (type: `string`):

Run status and counters stored by the Actor.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("w3crawler/mercari-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 = {}

# Run the Actor and wait for it to finish
run = client.actor("w3crawler/mercari-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 '{}' |
apify call w3crawler/mercari-listings-scraper --silent --output-dataset

```

## MCP server setup

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