Buyee APIbuyee.jp ↗
Search Yahoo Auctions Japan, Mercari Japan, and Rakuma via 6 endpoints. Retrieve item listings, auction details, prices, bids, and condition data.
What is the Buyee API?
The Buyee API covers 6 endpoints for searching and retrieving item listings across major Japanese marketplaces — Yahoo Auctions Japan (JDirectItems), Mercari Japan, and Rakuma. You can run a cross-platform search with search_all_platforms to get structured results from multiple sources simultaneously, or go deeper into individual platforms with dedicated search and detail endpoints. Response fields include auction bid counts, time remaining, item condition, seller shipping terms, and full image arrays.
curl -X GET 'https://api.parse.bot/scraper/cbe679cb-de03-4482-8b06-9b336574f68f/search_all_platforms?limit=5&query=pokemon' \ -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 buyee-jp-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: Buyee Japan Marketplace SDK — search across platforms, drill into items."""
from parse_apis.buyee_japan_marketplace_api import (
Buyee, CrossSearchResult, YahooAuctionItem, MercariItem, ItemNotFound
)
client = Buyee()
# Cross-platform search — returns results from Yahoo Auctions, Mercari, Rakuma in one call.
for result in client.platforms.search(query="pokemon", limit=3):
print(result.total_result_count, "results across platforms")
for item in result.results[:2]:
print(item.title, item.current_price, item.site)
# Yahoo Auctions search — paginated; take one item and drill into details.
auction = client.yahooauctions.search(query="nintendo", limit=1).first()
if auction:
detail = auction.details()
print(detail.title, detail.time_remaining)
print("Condition:", detail.details.get("Item Condition", "unknown"))
# Mercari search — take one item then fetch full details.
mercari_item = client.mercaris.search(keyword="gundam", limit=1).first()
if mercari_item:
full = mercari_item.details()
print(full.title, full.price, len(full.images), "images")
# Browse available shop categories on Buyee.
for cat in client.yahooauctions.categories(limit=3):
print(cat.category, len(cat.shop_list), "shops")
# Typed error handling — catch when an item no longer exists.
try:
bad_item = YahooAuctionItem(_api=client, id="x0000000000")
bad_item.details()
except ItemNotFound as exc:
print(f"Item not found: {exc.item_id}")
print("exercised: platforms.search / yahooauctions.search / item.details / mercaris.search / categories / error handling")
Cross-platform search across multiple Japanese marketplaces (Yahoo Auctions, Mercari, Rakuma, etc.) simultaneously. Returns structured results with item details, prices, and platform information. Paginates internally per-platform; the limit controls how many results are returned per platform in a single call.
| Param | Type | Description |
|---|---|---|
| limit | integer | Maximum results per platform |
| queryrequired | string | Search keyword (e.g. 'pokemon', 'nintendo') |
{
"type": "object",
"fields": {
"results": "array of platform result objects each containing keywords, totalResultCount, totalPageCount, currentPageNumber, and results array with item details"
},
"sample": {
"data": {
"results": [
{
"results": [
{
"Bids": 0,
"site": "mercari",
"Image": "//static.mercdn.net/thumb/item/jpeg/m88747587655_1.jpg",
"Title": "ポケモンキッズ",
"BidOrBuy": 555,
"AuctionID": "m88747587655",
"StartTime": "2026-06-11T18:24:39+09:00",
"CurrentPrice": 555
}
],
"keywords": [],
"totalPageCount": 41533,
"totalResultCount": 207661,
"currentPageNumber": 1
}
]
},
"status": "success"
}
}About the Buyee API
Search Across Platforms
The search_all_platforms endpoint accepts a query string and an optional limit parameter to cap results per platform. It returns an array of platform result objects, each containing keywords, totalResultCount, totalPageCount, currentPageNumber, and a nested results array. This is the fastest way to survey availability and pricing across Yahoo Auctions, Mercari, and Rakuma in a single call.
Yahoo Auctions (JDirectItems) Endpoints
search_yahoo_auctions takes a query and optional page parameter (1-based) and returns up to approximately 50 items per page. Each item object includes id, title, url, image, current_price, buyout_price, time_remaining, and bids. Use item_id values from these results with get_yahoo_auction_item to retrieve full auction detail: an images array, a prices object mapping price labels to values, a details object covering fields like Item Condition and Number of Bids, and the raw description_html.
Mercari Japan Endpoints
search_mercari_japan accepts a keyword and optional page parameter and returns up to approximately 97 items per page along with a total count. Each item includes id, title, url, price_jpy, and image. Passing an id to get_mercari_item retrieves detailed data: full images, price with currency, a details object with Brand, Item Condition, and Shipping Paid By fields, seller information, and description_html.
Platform Discovery
get_yahoo_auction_categories requires no parameters and returns a categories array. Each category object contains a category_id, a category name (e.g. Fashion, Toys & Games), and a shop_list of marketplace entries with names, descriptions, and URLs. This endpoint is useful for programmatically mapping which marketplaces are available through the Buyee proxy service.
The Buyee API is a managed, monitored endpoint for buyee.jp — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when buyee.jp 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 buyee.jp 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 auction prices and bid counts on Yahoo Auctions Japan for specific collectibles or electronics
- Compare prices for the same item across Mercari Japan and Yahoo Auctions in a single cross-platform query
- Monitor
time_remainingandbuyout_pricefields on auction items to alert users before listings close - Aggregate Mercari Japan listings by condition using the
details.Item Conditionfield for resale analysis - Build a catalog of available Japanese marketplaces using
get_yahoo_auction_categoriesshop metadata - Pull full image arrays and HTML descriptions for auction items to populate a product detail view
- Estimate market demand for Japanese goods by comparing
totalResultCountper platform fromsearch_all_platforms
| 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 Buyee have an official developer API?+
What does get_yahoo_auction_item return beyond what the search results include?+
images array, a prices object with all price label-to-value mappings, a structured details object (Item Condition, Starting Price, Number of Bids, and similar fields), and the raw description_html of the listing.Does pagination work the same way across all search endpoints?+
search_yahoo_auctions and search_mercari_japan both use a 1-based page parameter for explicit pagination. search_all_platforms uses a limit parameter that caps results per platform rather than exposing page-level control, so you cannot walk through all pages of results with that endpoint alone. For deep pagination, use the platform-specific search endpoints.Does the API cover Rakuma item detail pages, not just search results?+
search_all_platforms results without a dedicated detail endpoint. You can fork the API on Parse and revise it to add a Rakuma item detail endpoint.Can I filter search results by price range, condition, or category?+
current_price and details.Item Condition fields returned in results, or you can fork the API on Parse and revise it to add filter parameters.