Mercari
Mercari Search API
Search Mercari listings by keyword on Mercari US (USD, English) or Mercari Japan (JPY, Japanese): each item with its id, title, price, the seller's earlier price and discount when the price was dropped, status, condition, brand, category, seller id and listing time. status sold returns sold listings with the price they sold at, so asking and sold prices come from one search; on Mercari US, sold results come most recently sold first and match the keyword more loosely, so check titles before comparing prices. us returns 50 a page up to page 20, jp 120 a page up to page 91, sorted by relevance, newest or price and filtered by price, condition, shipping, category and brand. Costs 1 credit.
Authorizations
AuthorizationstringheaderrequiredBearer authentication header of the form Bearer <token>, where <token> is your Scavio API key (e.g. Bearer sk_live_your_key).
Body
application/jsonquerystringSearch keywords, 1-200 characters. Required unless category_id or brand_id is sent. On jp, Japanese keywords match best.
Example: nintendo switch
countrystringdefault:usThe Mercari market: us and jp (default us). us = mercari.com (USD, English), jp = Mercari Japan (JPY, Japanese). Mercari UK closed: gb and uk answer 400, as does any other value, before anything is charged.
Example: us
statusenum<string>default:on_saleWhich listings.
Example: sold
on_sale— Listings on sale now. The default.sold— Sold listings, including items sold but still in transit (status trading), with the price they sold at.all— No status filter.
pageintegerdefault:1Results page, 1-based: us 50 per page up to page 20, jp 120 per page up to page 91. Later us pages can repeat items from earlier pages (promoted placements): dedupe by item_id.
Example: 2
sortenum<string>default:relevanceResult order.
Example: price_asc
relevance— Mercari's best match. The default. On a us sold search Mercari still orders results most recently sold first.newest— Newest first. On jp this is Mercari Japan's own order, in which relisted items move up, so created_at is not strictly descending.price_asc— Price, low to high.price_desc— Price, high to low.likes— Most liked first. jp only.recently_sold— Most recently sold first, with status sold. us only (a us sold search is in this order under relevance too).
category_idstringA category id of the same market (categories answer) to search within.
Example: 797
brand_idstringA brand id of the same market (brands answer).
Example: 4591
price_minnumberLowest price: US dollars on us, whole yen on jp.
Example: 50
price_maxnumberHighest price: US dollars on us, whole yen on jp.
Example: 300
conditionstring | string[]One or more of new, like_new, good, fair, poor; bad on jp only. Several are ORed.
Example: ["new", "like_new"]
shippingenum<string>free (the seller pays shipping) or buyer_pays. On us, result rows carry free_shipping only when you send this filter.
Example: free
size_idstringus only: a Mercari US size id (digits).
deals_onlybooleanus only: only listings on Mercari's deals filter (the seller dropped the price).
Example: true
shops_onlybooleanjp only: only Mercari Shops products (business sellers).
Example: true
Notes
Markets. This endpoint serves both Mercari markets: us and jp (default us). us is mercari.com (USD, English); jp is Mercari Japan (JPY, Japanese). Every answer echoes country, currency and language. Mercari UK closed: gb and uk answer 400, as does any other country, before anything is charged.
| country | Market | Prices | Language |
|---|---|---|---|
us | Mercari US (mercari.com) | USD, dollars and cents | English |
jp | Mercari Japan (jp.mercari.com) | JPY, whole yen | Japanese, as sellers wrote it (not translated) |
Request
from statistics import median
from scavio import ScavioClient
client = ScavioClient(api_key="sk_live_your_key", timeout=180)
# Asking vs sold prices for one query: 1 credit per call.
# Sold results come most recently sold first and match the keyword loosely,
# so keep only titles that carry every query word before comparing.
q = "coach tabby"
def prices(data):
return [i["price"] for i in data["items"] if all(w in i["title"].lower() for w in q.split())]
on_sale = prices(client.mercari.search(query=q, country="us")["data"])
sold = prices(client.mercari.search(query=q, country="us", status="sold")["data"])
if on_sale and sold:
print("asking median", median(on_sale), "sold median", median(sold))Response