# Mercari US Scraper (`axlymxp/mercari-scraper`) Actor

Scrape Mercari US listings by keyword: price, condition, brand, likes, seller and shipping as clean JSON. Pull active listings or sold-price comps for resale research. Filter by status, price, condition and sort. Handles Cloudflare for you. Pay only for results.

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

## Pricing

from $4.00 / 1,000 dataset items

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?

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 US Scraper

Turn any **Mercari US** (mercari.com) search into clean, structured JSON — one row
per listing, with price, condition, brand, likes, seller and shipping. Pull
**active listings** for monitoring, or **sold-price comps** for resale research.
No browser, no Cloudflare headaches — the actor passes the site's bot protection
for you and returns export-ready data.

### Who it's for

- **Resellers & sourcers** — see what actually sold and for how much (sold comps),
  plus the live competition for any item.
- **Pricing & e-commerce analysts** — price distribution, discounts, brand and
  category trends across a query.
- **Data & SaaS developers** — a reliable Mercari US feed without maintaining
  anti-bot infrastructure.
- **Market researchers** — brand demand (likes) and category velocity.

### What you get (output fields)

| Field                                   | Description                                        |
| --------------------------------------- | -------------------------------------------------- |
| `id`, `url`                             | Listing id and canonical Mercari URL               |
| `name`                                  | Listing title                                      |
| `price_usd`, `original_price_usd`       | Current and original price (USD)                   |
| `price_dropped`                         | Whether the price was reduced                      |
| `status`                                | `on_sale`, `trading`, or `sold_out`                |
| `num_likes`                             | Number of likes (demand signal)                    |
| `condition`, `condition_id`             | New / Like new / Good / Fair / Poor                |
| `brand`, `brand_id`                     | Brand name and Mercari brand id                    |
| `category`, `category_id`, `category_path` | Leaf category and full category breadcrumb      |
| `item_size`                             | Size (apparel), when present                       |
| `seller_id`                             | Seller account id                                  |
| `created`, `updated`                    | Listing timestamps (Unix)                          |
| `photos`, `thumbnail`                   | Image URLs                                          |
| `shipping_fee_usd`, `shipping_payer`    | Shipping cost and who pays (needs **item details**)|
| `description`                           | Listing description (needs **item details**)       |
| `source`, `scraped_at`                  | Query provenance and capture time (ISO 8601)       |

Mercari's search feed is lightweight: **`description`, `shipping_fee_usd` and
`shipping_payer` are only returned with `includeDetails` on.** With **Enrich with
item details** enabled, each row also gets `shipping_from_area`, `shipping_carrier`,
`shipping_eta`, `item_type` and `checksum`. With **Enrich with seller profile** on,
you also get `seller_name`, `seller_num_sales`, `seller_num_ratings`,
`seller_rating` and `seller_is_pro`.

### High-value use cases

- **Sold-price comps (resellers):** set **Listing status = Sold out** and **Sort =
  Newest** to pull recently-sold items with their final prices — know what to list
  and at what price before you buy.
- **Active competition:** status **On sale**, sort **Price: low to high** to see
  what you're up against for an item.
- **Brand/category intelligence:** filter by `brandIds` or `categoryIds` and read
  `num_likes` + price spread to gauge demand.
- **Deal & price-drop tracking:** schedule a daily run and watch `price_dropped`.

### Input parameters

| Param                | Type    | Default        | Description                                                    |
| -------------------- | ------- | -------------- | -------------------------------------------------------------- |
| `searchQueries`      | array   | —              | Keywords to search (required), e.g. `["nintendo switch"]`      |
| `itemStatus`         | enum    | `on_sale`      | `on_sale` · `sold_out` (comps) · `trading` · `all`             |
| `sortBy`             | enum    | `relevance`    | `relevance` · `newest` · `price_asc` · `price_desc`            |
| `condition`          | enum    | `all`          | `all` · `new` · `like_new` · `good` · `fair` · `poor`          |
| `priceMin`/`priceMax`| integer | —              | Price bounds in whole USD                                      |
| `brandIds`           | array   | —              | Numeric Mercari brand IDs (e.g. `5074` = Pokemon)             |
| `categoryIds`        | array   | —              | Numeric Mercari category IDs                                   |
| `includeDetails`     | boolean | `false`        | Add description + full shipping per listing                    |
| `includeSeller`      | boolean | `false`        | Add seller profile per unique seller                           |
| `maxItems`           | integer | `200`          | Global cap across all queries                                  |
| `proxyConfiguration` | object  | US Residential | Cloudflare needs a clean residential exit                      |

#### Example input

```json
{
  "searchQueries": ["pokemon card"],
  "itemStatus": "sold_out",
  "sortBy": "newest",
  "condition": "all",
  "maxItems": 200,
  "includeSeller": true,
  "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "US" }
}
```

#### Example output row

```json
{
  "id": "m55314834703",
  "name": "Pikachu Galarian Gallery Crown Zenith Pokemon Card NM",
  "url": "https://www.mercari.com/us/item/m55314834703/",
  "price_usd": 46.0,
  "original_price_usd": 46.0,
  "price_dropped": false,
  "status": "sold_out",
  "num_likes": 28,
  "condition": "Like new",
  "brand": "Pokemon",
  "category_path": "Toys & Collectibles > Trading Cards > Single Cards",
  "seller_id": 154195300,
  "shipping_fee_usd": 4.91,
  "shipping_payer": "Buyer",
  "scraped_at": "2026-09-26T04:00:00Z"
}
```

### Scheduling & webhooks

Use Apify **Schedules** to run daily/hourly and build a price-history or
new-listings feed. Add a **webhook** on run success to push new rows straight into
your database, Google Sheet, or Slack.

### Use with AI assistants (MCP)

The dataset is plain JSON, so you can wire this actor into any LLM/agent workflow
via the Apify **Model Context Protocol (MCP)** server — have your assistant pull
Mercari sold comps or active listings on demand and reason over the results.

### FAQ

**Which Mercari does this cover?** Mercari **US** (`www.mercari.com`). It does not
cover Mercari Japan.

**Can I get sold prices?** Yes — set `itemStatus` to `sold_out`. Mercari exposes
recently-sold listings with their final price; sort by `newest` for the freshest
comps.

**Why a residential proxy?** Mercari sits behind a Cloudflare challenge that blocks
most datacenter IPs. A US residential proxy (the default) passes it reliably. You
can supply your own proxy too.

**How fresh is the data?** Every row is fetched live at run time (`scraped_at`
records the moment). Schedule the actor for continuous freshness.

**How many results per query?** Mercari caps a single search at roughly 10,000
results. Narrow with price, condition, brand or category filters to go deeper into
a niche.

**Is scraping this legal?** The actor collects only publicly available listing
data. You are responsible for using the output in line with Mercari's terms and
applicable law.

**Do I get the item description?** The title, price, condition, brand, category,
likes and photos come from the search feed. **Description and shipping cost are
detail-only** — turn on **Enrich with item details** to include them (one extra
request per listing).

# Actor input Schema

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

Keywords to search on Mercari US, e.g. "nintendo switch", "pokemon card". One row per matching listing.

## `itemStatus` (type: `string`):

Which listings to return. Use "Sold out" + sort "Newest" to pull recent SOLD-price comps for resale research.

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

Result ordering.

## `condition` (type: `string`):

Filter by item condition.

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

Only return listings at or above this price, in whole US dollars.

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

Only return listings at or below this price, in whole US dollars.

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

Optional numeric Mercari brand IDs to filter by (e.g. 5074 = Pokemon). Find IDs in the brand sitemap URLs.

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

Optional numeric Mercari category IDs to filter by. Find IDs in the category sitemap URLs.

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

Fetch each listing's full detail (description, ships-from area, carrier, ETA). Adds one request per listing — slower and costs more.

## `includeSeller` (type: `boolean`):

Add the seller's profile (name, total sales, ratings). Adds one request per unique seller.

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

Stop after this many rows in total across all queries. Mercari caps any single search at ~10,000 results.

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

Mercari is behind a Cloudflare challenge; a US residential proxy is used by default to pass it reliably. Datacenter IPs are frequently blocked.

## Actor input object example

```json
{
  "searchQueries": [
    "nintendo switch",
    "pokemon card"
  ],
  "itemStatus": "on_sale",
  "sortBy": "relevance",
  "condition": "all",
  "includeDetails": false,
  "includeSeller": false,
  "maxItems": 200,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `dataset` (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"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("axlymxp/mercari-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"],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("axlymxp/mercari-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"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call axlymxp/mercari-scraper --silent --output-dataset

```

## MCP server setup

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