Mercari Japan API & Scraper
The Mercari Japan API returns Japan's largest consumer-to-consumer resale marketplace as clean JSON, in two actions: search and product/detail.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
It is the cheapest surface in the whole ReefAPI fleet by bytes per record - a 20-item search is 13,803 bytes, about 3.7 KB an item, at a median 1.29 s - because nothing is scraped from HTML; jp.mercari.com's own search page is 540 KB of client-rendered shell containing zero item ids and zero prices, so the engine talks to Mercari's JSON surface directly, with no account, no cookie, no browser and no captcha. Every search row carries the item id and URL, the title, the price as a number in yen, the listing status, the condition grade, the category id, the seller id and profile URL, the images and the listing timestamp - filled 20 of 20 on every one of ten measured category searches. search filters on category, brand, seller, price range, condition, listing status, colour, shipping payer, shipping prefecture and listing type, and three of those work with no keyword at all, which makes them a category feed, a brand feed and a seller-inventory feed. product/detail adds the description, the named root-to-leaf category path, the brand, the colours, the hashtags, the full photo gallery, the shipping method and prefecture, and the seller's reputation - a numeric star rating, the number of ratings behind it and the good/normal/bad breakdown. Prices are JPY. One ReefAPI key, one shared credit pool, the standard { ok, data, meta, error } envelope.
What one search call actually costs and fills - ten categories, 200 items, measured by value
Ten keywords across ten Mercari categories were pulled on 2026-09-06 and every field was counted by VALUE, not by key presence. Item id, title, URL, price, currency, status, condition, category id, seller id, seller URL, image and listing timestamp came back 20 of 20 on every single one of the ten searches.
| Category searched | Items | Bytes | Latency | Price range in the page returned |
|---|---|---|---|---|
| Smartphones | 20 | 13,803 | 1,511 ms | 300 - 1,666 JPY |
| Sneakers | 20 | 14,321 | 1,527 ms | 1,400 - 7,500 JPY |
| Trading cards | 20 | 14,455 | 2,382 ms | 300 - 12,000 JPY |
| Luxury bags | 20 | 14,645 | 1,348 ms | 1,300 - 175,000 JPY |
| Cosmetics | 20 | 14,239 | 1,907 ms | 400 - 3,800 JPY |
| Baby clothes | 20 | 14,159 | 1,491 ms | 300 - 3,200 JPY |
| Watches | 20 | 14,239 | 1,419 ms | 1,100 - 57,000 JPY |
| Musical instruments | 20 | 14,334 | 1,328 ms | 300 - 20,000 JPY |
| Golf | 20 | 14,361 | 1,435 ms | 4,000 - 35,000 JPY |
| Bicycles | 20 | 14,301 | 1,591 ms | 900 - 62,000 JPY |
Over 40 consecutive live calls on the same day - 27 searches and 13 product/detail - success was 40 of 40, with a minimum of 722 ms, a median of 1,288 ms, a p90 of 1,804 ms and a worst case of 2,651 ms. product/detail on one item from each of those ten searches returned a real price, a full root-to-leaf category path and a seller with a rating on 10 of 10; the only nulls in the whole grid were brand name on 2 of 10, where the seller had not tagged a brand.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/mercari/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "ポケモンカード"
}
}{
"ok": true,
"meta": {
"api": "mercari",
"endpoint": "search",
"mode": "live",
"latency_ms": 1984.8,
"record_count": 20,
"bytes": 14282,
"cache_hit": false,
"next_page_token": "[redacted-secret]"
},
"data": {
"items": [
{
"item_id": "m[redacted-phone]",
"title": "ポケモンカード ニンフィア 1枚 モンスターボールミラー",
"url": "https://jp.mercari.com/item/m[redacted-phone]",
"price": 888,
"price_display": null,
"currency": "JPY",
"status": "on_sale",
"condition": "fair",
"condition_id": 4,
"listing_type": "c2c",
"category_id": 1289,
"category": null,
"brand": null,
"size": null,
"seller": {
"id": "[redacted-phone]",
"name": null,
"url": "https://jp.mercari.com/user/profile/[redacted-phone]",
"rating": null,
"rating_count": null,
"rating_scale": null
},
"shop": null,
"shipping_payer": "seller",
"rating": null,
"review_count": null,
"rating_scale": null,
"image": "https://static.mercdn.net/item/detail/webp/photos/m[redacted-phone]_1.jpg?[redacted-phone]",
"thumbnail": "https://static.mercdn.net/thumb/item/webp/m[redacted-phone]_1.jpg?[redacted-phone]",
"listed_at": "[redacted-phone]T13:03:54Z",
"updated_at": "[redacted-phone]T14:42:05Z"
},
{
"item_id": "m[redacted-phone]",
"title": "ポケモンカード S イッカネズミ 1枚 色違い sv4a",
"url": "https://jp.mercari.com/item/m[redacted-phone]",
"price": 1333,
"price_display": null,
"currency": "JPY",
"status": "on_sale",
"condition": "new",
"condition_id": 1,
"listing_type": "c2c",
"category_id": 1289,
"category": null,
"brand": null,
"size": null,
"seller": {
"id": "[redacted-phone]",
"name": null,
"url": "https://jp.mercari.com/user/profile/[redacted-phone]",
"rating": null,
"rating_count": null,
"rating_scale": null
},
"shop": null,
"shipping_payer": "seller",
"rating": null,
"review_count": null,
"rating_scale": null,
"image": "https://static.mercdn.net/item/detail/webp/photos/m[redacted-phone]_1.jpg?[redacted-phone]",
"thumbnail": "https://static.mercdn.net/thumb/item/webp/m[redacted-phone]_1.jpg?[redacted-phone]",
"listed_at": "[redacted-phone]T11:18:15Z",
"updated_at": "[redacted-phone]T15:08:12Z"
},
{
"item_id": "m[redacted-phone]",
"title": "ポケモンカード ピカチュウ 124/S-P プロモ Pikachu 151",
"url": "https://jp.mercari.com/item/m[redacted-phone]",
"price": 6700,
"price_display": null,
"currency": "JPY",
"status": "on_sale",
"condition": "good",
"condition_id": 3,
"listing_type": "c2c",
"category_id": 1289,
"category": null,
"brand": null,
"size": null,
"seller": {
"id": "[redacted-phone]",
"name": null,
"url": "https://jp.mercari.com/user/profile/[redacted-phone]",
"rating": null,
"rating_count": null,
"rating_scale": null
},
"shop": null,
"shipping_payer": "seller",
"rating": null,
"review_count": null,
"rating_scale": null,
"image": "https://static.mercdn.net/item/detail/webp/photos/m[redacted-phone]_1.jpg?[redacted-phone]",
"thumbnail": "https://static.mercdn.net/thumb/item/webp/m[redacted-phone]_1.jpg?[redacted-phone]",
"listed_at": "[redacted-phone]T16:48:29Z",
"updated_at": "[redacted-phone]T16:48:29Z"
}
],
"count": 20,
"next_page_token": "[redacted-secret]",
"total_results": 15000,
"total_results_is_estimate": true,
"total_results_capped_at": 15000,
"filters": {
"query": "ポケモンカード",
"sort": "relevance",
"page_size": 20
}
}
}What the Mercari Japan API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Search Mercari Japan by keyword and by any combination of category, brand, seller, price range, condition, colour, shipping terms and shipping prefecture, paginated. Every row carries the item id and url, the title, the price as a number in JPY, whether it is still on sale or already sold, the condition grade, the category id, the seller's id and profile url, the image, and when it was listed and last touched. Filter on `status: sold_out` to get the prices items actually sold at - the comparables a resale valuation is built from. Paginate by passing back the `next_page_token` from the previous response. | Pricing teams call search to search Mercari Japan by keyword and by any combination of category, brand, seller, price rang…. | query, exclude, category_id, brand_id, seller_id, ... |
| product/detail | One Mercari Japan listing in full, by id or url: title, description, the price as a number in JPY, sale status, the condition grade with Mercari's own wording for it, the named category path, brand, colours, hashtags, the full photo gallery, the shipping terms (who pays, the method, the prefecture it ships from and the seller's stated handling days), the like and comment counts, and the SELLER - name, profile url, how many items they have listed, and their rating with the good/normal/bad breakdown behind it. Mercari Shops products are accepted too and return the smaller set of fields Mercari publishes for them, with everything else null. | Marketplace operators call product/detail to get one Mercari Japan listing in full, by id or url. | item_id, max_rotations |
Call search from your stack
curl -X POST https://api.reefapi.com/mercari/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"ポケモンカード"}'import requests
r = requests.post(
"https://api.reefapi.com/mercari/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "ポケモンカード"
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/mercari/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "ポケモンカード"
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.mercari.search with {"query":"ポケモンカード"}.Who uses this API and why
- Resale pricing tools search with status=sold_out to build comparables from what items ACTUALLY sold for, not from what sellers are asking.
- Sourcing and arbitrage teams sweep a category or brand id with no keyword at all and page through with the cursor, at about 3.7 KB an item.
- Brand-protection teams watch a brand id for counterfeit or grey-market listings and pull the seller's reputation with product/detail.
- Proxy-buying and cross-border storefronts call product/detail for the full listing - description, condition grade in Mercari's own wording, photo gallery, shipping method and prefecture, and the seller's rating breakdown.
Questions developers ask before integrating
Can I see what an item actually SOLD for, not just what it is listed at?
Yes - that is the most useful thing this API does for resale pricing. Set status to sold_out and every row you get back is a completed sale carrying the price it sold at, which is what a resale comparable actually is; a live listing only tells you what somebody hopes to get. Measured live on 2026-09-06: a Japanese trading-card keyword with status sold_out returned rows that were 20 of 20 sold_out, and with a price_desc sort the same query came back in 10.5 KB and 1.63 s. Combine it with a category id or a brand id to build a comparables set for one exact kind of item.
How many results are there really? total_results says 15000 on everything.
Because 15,000 is Mercari's cap, not a count. Mercari returns exactly that number for any keyword with real supply, and it only moves when the result set is genuinely small - a 10,000 to 12,000 yen price band brought it down to 12,901, and a junk keyword returns 0. The response never hides this: total_results comes with total_results_is_estimate set to true on every call, and total_results_capped_at set to 15000 whenever it is sitting on the cap. To actually walk a result set, use next_page_token instead.
Does paging give me new items or the same page again?
New items. It was checked by comparing id sets rather than by trusting the token: pages 1 through 4 returned 20 new ids each with 0 repeats, and 100 rows over five pages gave 97 distinct ids. The small overlap that appears deeper in the stream is Mercari's live index re-ordering under the cursor - new listings pushing rows across a page boundary - not the engine repeating a page; the first two pages never overlap at all. With page_size 120 it pages cleanly to at least 960 rows. The token is Mercari's own opaque cursor and must be passed back as given, not constructed. page_size itself is a hint, not a promise - a 20-row request came back with 14 on one live sold-listing call - so read count.
Are there product reviews or a rating on a listing?
No, and there cannot be - every Mercari listing is a unique second-hand object, so there is nothing to review. rating, review_count and rating_scale on the item are all null rather than invented. The reputation that DOES exist is on the seller, and product/detail returns it: a numeric star rating that is a real average (measured 0 with no ratings, 4.5 over 13 ratings, 5 over 2,505), the number of ratings behind it, and a good/normal/bad breakdown - which is the part that actually discriminates, because Mercari feedback is overwhelmingly good. Like count and comment count are published under their own names and are deliberately not dressed up as reviews.
Why do some ids look completely different from the others?
Because Mercari runs two id spaces and both are served. A private C2C listing is the letter m followed by 11 digits and lives at jp.mercari.com/item/<id>; a Mercari Shops product, sold by a business, is 22 base62 characters and lives at jp.mercari.com/shops/product/<id> behind a different endpoint entirely. Feeding a Shops id to the private-listing endpoint is a hard 400, so anyone iterating their own search results would hit it: a default search returned 0 to 3 Shops rows in every 60 measured. product/detail reads the id shape and routes accordingly, and both kinds come back with the same key set so nothing downstream has to branch - the fields Mercari does not publish for Shops products come back as explicit nulls. Set listing_type to c2c or shops if you want only one kind.
Do the filters actually filter, or are they accepted and ignored?
Every published filter was proved to bite, and the ones that could not be proved were not published. Verified: condition new returned 20 of 20 new; a 50,000 to 60,000 yen band returned 20 of 20 in range; a leaf category id returned 20 of 20 in that category; sold_out returned 20 of 20 sold; price_asc and price_desc were strictly monotone across 20 rows; newest cut the median listing age from 289,545 seconds to 11,084. Filters left out include a coupon flag that returned 9 of the same 10 rows as the control, a size filter with nothing to verify against, and a shipping-method filter whose id space is not the one items report back. This matters because Mercari SILENTLY IGNORES an out-of-range value rather than erroring - an invalid condition id came back with a normal-looking mixed page - so every enum here is rejected up front and re-checked in the response.
Is shipping_payer=buyer a clean filter?
Not on its own, and the API says so in the parameter's own description. Buyer-pays is rare on Mercari, and when the filter runs short of rows Mercari backfills the page with Mercari Shops listings, which carry no shipping-payer value at all and were never filtered - measured at 9 matching plus 11 unfiltered in a page of 20. Adding listing_type=c2c makes it 20 of 20. It is the same class of problem as the ignored enum above: a plausible answer to a question you did not ask.
What does Mercari NOT publish?
A formatted price string - only a bare integer of yen, so price_display is null and currency is the documented constant JPY. No rating scale: a scan of the whole payload finds no maximum-rating key anywhere, so rating_scale is null rather than an assumed 5. No stock quantity and no competing-offer table, because a C2C listing is one object from one seller - there is nothing to compare. No seller name and no category name on a search ROW, only the ids; product/detail names both. No size - the size field was null on every row measured, in every category tried. And no category directory: there is no endpoint that lists Mercari's categories, so ids are discovered from search rows and from product/detail, which returns the full named path.
What is the Mercari Japan API?
Mercari Japan API is a ReefAPI endpoint group for japan's c2c resale marketplace: live and sold listings, prices in yen, seller reputation. It returns live JSON through POST requests under /mercari/v1.
Is the Mercari Japan API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. Mercari Japan calls use the same shared credit balance as every other ReefAPI engine.
Do I need a Mercari Japan login or account?
No login to Mercari Japan is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the Mercari Japan data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the Mercari Japan API use?
Mercari Japan actions currently cost 1 credit per successful call. Failed or blocked calls are free, and all APIs draw from one credit pool.
Can I call Mercari Japan from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call mercari actions with the same key, credit pool and JSON envelope used by normal REST requests.