Mercari APImercari.com ↗
Search Mercari's secondhand marketplace via API. Returns item price, condition, brand, seller, category, and images with filtering and pagination.
What is the Mercari API?
The Mercari API exposes one endpoint — search — that returns up to 120 listings per request from Mercari's US secondhand marketplace, covering 14 response fields per item including price, condition, brand, seller, category, and image URLs. You can filter results by keyword, price range, item condition, and listing status, then paginate through up to 20,000 matching results using the next_offset value returned in each response.
curl -X GET 'https://api.parse.bot/scraper/affc7073-2b1c-42b2-8f89-f67489e32f69/search?query=headphones&sort_by=best_match' \ -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 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 SDK — search listings with filters, bounded iteration."""
from parse_apis.mercari_com_api import Mercari, SortBy, ItemStatus, InputFormatInvalid
client = Mercari()
# Search for headphones sorted by lowest price, capped at 5 results.
try:
for listing in client.listings.search(query="headphones", sort_by=SortBy.LOWEST_PRICE, limit=5):
print(listing.name, f"${listing.price:.2f}", listing.condition)
except InputFormatInvalid as e:
print("Invalid search input:", e.message)
# Drill into one listing to inspect its category hierarchy.
listing = client.listings.search(
query="nike shoes",
status=ItemStatus.ON_SALE,
max_price=80,
limit=1,
).first()
if listing is not None:
print(listing.name, f"${listing.price:.2f} (was ${listing.original_price:.2f})")
if listing.brand_name is not None:
print("Brand:", listing.brand_name)
for cat in listing.category_hierarchy:
print(f" L{cat.level}: {cat.name}")
print("exercised: listings.search")
Search Mercari listings by keyword. Returns paginated results with item details including price, condition, brand, category, and images. Supports filtering by price range, item condition, item status (on sale vs sold), and sorting. Prices are in US dollars. Use offset for pagination; each response includes next_offset and has_more to drive continuation. The upstream caps total_count at 20000 even when more exist.
| Param | Type | Description |
|---|---|---|
| limit | integer | Number of results per page, between 1 and 120. |
| queryrequired | string | Search keyword (e.g. 'headphones', 'nike shoes'). |
| offset | integer | Pagination offset. Use the next_offset value from a previous response to get the next page. |
| status | string | Item status filter. Omitted returns all items. |
| sort_by | string | Sort order for results. |
| condition | string | Comma-separated item condition filters (e.g. 'new,like_new'). Values: new, like_new, good, fair, poor. |
| max_price | number | Maximum price filter in US dollars (e.g. 100 for $100.00). |
| min_price | number | Minimum price filter in US dollars (e.g. 10 for $10.00). |
| category_id | string | Mercari category ID to filter results (e.g. '789' for Headphones). Category IDs are returned in each item's category_hierarchy. |
{
"type": "object",
"fields": {
"items": "array of item objects with id, name, price, original_price, status, condition, brand, seller, category, and image URLs",
"limit": "integer limit used in the request",
"offset": "integer current offset used in the request",
"has_more": "boolean indicating if more results are available",
"next_offset": "integer offset to use for the next page",
"total_count": "integer total number of matching results (capped at 20000)"
},
"sample": {
"data": {
"items": [
{
"id": "m84658596892",
"name": "Phillips over ear 8000 series head phones,new",
"price": 56.2,
"status": "on_sale",
"brand_id": 4989,
"item_url": "https://www.mercari.com/us/item/m84658596892/",
"condition": "New",
"image_url": "https://u-mercari-images.mercdn.net/photos/m84658596892_1.jpg?1781725080",
"seller_id": 426050851,
"brand_name": "Phillips",
"category_id": 1594,
"category_name": "Bluetooth Headphones",
"thumbnail_url": "https://u-mercari-images.mercdn.net/photos/m84658596892_1.jpg?1781725080&width=200&height=200",
"original_price": 69,
"category_hierarchy": [
{
"id": 7,
"name": "Electronics",
"level": 0
},
{
"id": 1593,
"name": "Headphones & MP3 Players",
"level": 1
},
{
"id": 1594,
"name": "Bluetooth Headphones",
"level": 2
}
]
}
],
"limit": 3,
"offset": 0,
"has_more": true,
"next_offset": 2,
"total_count": 20000
},
"status": "success"
}
}About the Mercari API
What the search endpoint returns
The search endpoint accepts a required query string and returns an array of item objects from Mercari's US marketplace. Each item includes id, name, price, original_price, status, condition, brand, seller, category, and one or more image URLs. The total_count field reports how many listings matched your query, capped at 20,000. The has_more boolean and next_offset integer make it straightforward to walk through paginated result sets.
Filtering and sorting
The condition parameter accepts a comma-separated list of values — new, like_new, good, fair, poor — letting you narrow results to specific quality tiers. Use min_price and max_price to bound results to a dollar range. The status parameter filters between active listings and sold items, which is useful for sold-price research. The sort_by parameter controls result ordering, and limit controls page size from 1 to 120 items.
Scope and coverage
All prices are in US dollars, reflecting Mercari's US platform. The API covers publicly visible listing data — the fields a buyer would see on a search results page. Seller profile detail, shipping cost breakdowns, and listing descriptions are not included in the search response fields.
The Mercari API is a managed, monitored endpoint for mercari.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when 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 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 sold prices for a specific brand or product category to estimate resale value
- Monitor active inventory for a keyword and alert when new listings appear below a target price
- Compare condition-to-price ratios across
new,like_new, andgoodlistings for a given item - Build a cross-platform price comparison tool using
priceandbranddata alongside other marketplace sources - Aggregate category-level supply data by counting listings returned for different search terms
- Filter sold listings by condition to research realistic sell-through prices for secondhand goods
- Populate a deal-finder app that surfaces listings matching user-defined keyword and max price criteria
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Mercari have an official developer API?+
How does pagination work, and is there a ceiling on how many results I can retrieve?+
has_more, next_offset, and total_count. Pass the next_offset value as the offset parameter in your next request to fetch the following page. The total_count field is capped at 20,000 regardless of how many actual listings exist for a query, so pagination stops at that ceiling.Can I retrieve full listing details — description, shipping cost, seller ratings — for a specific item?+
search endpoint returns summary-level fields: id, name, price, original_price, status, condition, brand, seller, category, and images. Listing descriptions, shipping breakdowns, and seller feedback scores are not part of the response. You can fork this API on Parse and revise it to add a detail endpoint that fetches those fields for a given item ID.Can I filter results by category rather than by keyword?+
search endpoint requires a query string and does not accept a category ID or slug as a standalone filter. You can combine a broad keyword with condition, min_price, and max_price to approximate category-scoped queries. You can fork this API on Parse and revise it to add a category browse endpoint if you need results scoped to a taxonomy node without a keyword.