Mercari APIjp.mercari.com ↗
Access Mercari Japan listings, item details, seller profiles, and category data via 6 structured endpoints. Filter by price, category, status, and keyword in JPY.
What is the Mercari API?
The Mercari Japan API covers 6 endpoints for searching, browsing, and inspecting listings on jp.mercari.com — Japan's largest C2C marketplace. Use search_items to query across millions of active and sold listings with keyword, price range, category, and sort controls, or call get_item_detail to retrieve full item data including description, seller ratings, condition, image URLs, and listing timestamps.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/d5d7823e-dc11-42c8-ad69-386a5c248f29/get_all_categories' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace jp-mercari-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: Mercari Japan SDK — search, browse categories, price analysis, item details."""
from parse_apis.mercari_japan_api import Mercari, SearchSort, Sort, ItemStatus, ItemNotFound
mercari = Mercari()
# Search for items with price and sort filters
for item in mercari.itemsummaries.search(keyword="Nintendo Switch", sort=SearchSort.PRICE, order=Sort.ASC, status=ItemStatus.ON_SALE, limit=5):
print(item.title, item.price_jpy, item.status)
# Drill into one item's full details
item_summary = mercari.itemsummaries.search(keyword="iPhone", limit=1).first()
if item_summary:
detail = item_summary.details()
print(detail.title, detail.price_jpy, detail.description[:80])
print(detail.seller.name, detail.seller.rating)
# Get price statistics for a keyword
summary = mercari.searchsummaries.get(keyword="AirPods")
print(summary.average_price_jpy, summary.min_price_jpy, summary.max_price_jpy, summary.sample_size)
# Browse items in a category by constructing a CategoryTree
category = mercari.categorytree(id="3088")
for cat_item in category.browse_items(sort=SearchSort.CREATED_TIME, order=Sort.DESC, limit=3):
print(cat_item.title, cat_item.price_jpy, cat_item.item_url)
# Typed error handling for a missing item
try:
missing = mercari.items.get(item_id="m00000000000")
print(missing.title)
except ItemNotFound as exc:
print(f"Item not found: {exc.item_id}")
print("exercised: search / details / searchsummaries.get / categorytree.browse_items / items.get")
Fetch the complete hierarchical category tree for Mercari Japan. Returns all product categories with parent-child relationships, display ordering, image URLs, and short labels. Use category IDs from this tree to filter search results or browse items by category.
No input parameters required.
{
"type": "object",
"fields": {
"categories": "array of nested category objects with id, name, displayOrder, children, imageUrls, and shortLabel"
},
"sample": {
"data": {
"categories": [
{
"id": "3088",
"name": "ファッション",
"children": [
{
"id": "1",
"name": "レディース",
"level": "1",
"children": [],
"hasChild": true,
"displayOrder": "1",
"parentCategoryId": "3088"
}
],
"hasChild": true,
"imageUrls": {
"CATEGORY_RICH_ICON": "https://static.mercdn.net/images/category/rich_icon/3088_fashion.png"
},
"shortLabel": "ファッション",
"displayOrder": "10"
}
]
},
"status": "success"
}
}About the Mercari API
Search and Filter Listings
The search_items endpoint accepts up to eight parameters: keyword, category_id, price_min, price_max, status (on_sale, sold_out, or all), sort (price or created_time), order (asc or desc), and page_token for cursor-based pagination. Each page returns up to 120 item objects containing item_id, title, price_jpy, thumbnail_url, item_url, status, category_id, and item_brand, along with total_count and a next_page_token for fetching the next page.
Item Details, Seller Profiles, and Price Statistics
get_item_detail takes a single item_id (e.g. m77009256155) and returns the full listing: description, image_urls array, likes_count, listing_date as a Unix timestamp, the category object with parent category info, and a seller object with id, name, rating, review_count, and is_verified. get_seller_profile accepts a numeric user_id and returns all of that seller's listings — on sale, sold, or in-progress — in the same item shape. For market research, get_search_summary computes min_price_jpy, max_price_jpy, average_price_jpy, and median_price_jpy over up to 120 matching items for a given keyword.
Category Browsing
get_all_categories returns the complete Mercari Japan category tree as nested objects, each with id, name, displayOrder, shortLabel, imageUrls, and children. Pass any id from that tree into get_category_items to browse listings scoped to that category, applying the same price, status, and sort filters available in search_items. This is useful when you want to enumerate an entire category rather than target a keyword.
The Mercari API is a managed, monitored endpoint for jp.mercari.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when jp.mercari.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official jp.mercari.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track resale price trends for a specific product using
get_search_summarymedian and average fields - Build a sold-listing price reference tool by filtering
search_itemswithstatus: sold_out - Monitor a seller's inventory changes over time using
get_seller_profilewith their numeric user ID - Populate a category browser UI using the nested tree from
get_all_categoriesandget_category_items - Alert buyers to new listings under a price threshold using
search_itemssorted bycreated_timedescending - Aggregate seller trust signals (
rating,review_count,is_verified) fromget_item_detailfor a vetting tool - Compare
likes_countacross listings in a category to identify demand signals for resellers
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Mercari Japan have an official public developer API?+
What does `get_item_detail` return that `search_items` does not?+
search_items returns a summary object per listing: item_id, title, price_jpy, thumbnail_url, item_url, status, category_id, and item_brand. get_item_detail adds the full description text, an image_urls array (multiple images), likes_count, a listing_date Unix timestamp, detailed category object with parent info, and a seller object with rating, review_count, and is_verified.How does pagination work in `search_items`?+
next_page_token string. Pass that value as the page_token parameter in your next request to retrieve the following page. When there are no more results, next_page_token is null. Each page contains up to 120 items.Does the API return shipping cost or item condition data?+
Is `get_search_summary` accurate for the full result set?+
get_search_summary — min, max, average, and median — are calculated from a sample of up to 120 items, not the entire total_count. For high-volume keywords where total_count far exceeds 120, the statistics reflect that sample only, not the full distribution.