suruga-ya.jp APIwww.suruga-ya.jp ↗
Access Suruga-ya product listings, condition definitions, branch number mappings, and pricing for Japan's second-hand goods marketplace via a structured API.
No input parameters required.
curl -X GET 'https://api.parse.bot/scraper/c15ae5c1-0b6b-476c-b6d4-18a0e104fcb9/get_branch_definitions' \ -H 'X-API-Key: $PARSE_API_KEY'
Returns all known branch_number definitions (0001-0207) that map to product conditions on suruga-ya.jp. Branch numbers represent the condition/state variant of a used product listing. Numbers 9000-9999 are generic marketplace seller listings, and numbers beyond 0207 are generic used condition.
No input parameters required.
{
"type": "object",
"fields": {
"notes": "object with explanatory notes about special ranges",
"total": "integer - count of defined branch numbers",
"definitions": "object mapping branch_number strings to their Japanese condition labels"
},
"sample": {
"data": {
"notes": {
"0001": "Default listing (new/used standard condition)",
"0208+": "Numbers beyond 0207 that are not explicitly defined typically map to generic 中古 (used)",
"9000-9999": "Marketplace seller listings (マケプレ) - generic used condition, seller provides specific condition description"
},
"total": 207,
"definitions": {
"0001": "新品/中古（通常）",
"0076": "Aランク",
"0077": "Bランク"
}
},
"status": "success"
}
}About the suruga-ya.jp API
The Suruga-ya API exposes 4 endpoints covering product search, product detail retrieval, and condition (branch_number) lookups for suruga-ya.jp, one of Japan's largest used-goods marketplaces. The get_product_detail endpoint returns fields including product_name, condition_type, condition_detail, prices, and buyback_price for any product ID. The get_branch_definitions endpoint maps all 0001–0207 condition codes to their Japanese labels, plus rules for the 9000–9999 marketplace seller range.
Product Search and Detail
The search_products endpoint accepts a search_word parameter (Japanese or English text, or a numeric product ID) and returns paginated results — up to 24 items per page — with fields including product_id, title, category, condition, price, brand, release_date, and image_url. You can filter by category (e.g. '5' for おもちゃ・ホビー, '2' for ゲーム) and sort by relevance, price ascending, price descending, or newest.
The get_product_detail endpoint takes a product_id and two optional parameters: branch_number to select a specific condition variant and store_id to scope results to a particular physical store listing. The response includes product_name, condition_type (broad label such as 中古 or 新品), condition_detail (extracted from parentheses in the product name), prices (an object with new_price and/or used_price as integers in yen), buyback_price, and a branch_definition field mapped from the known branch number table.
Condition and Branch Number System
Suruga-ya uses a 4-digit zero-padded branch_number to encode the condition state of each listing. get_branch_definitions returns the full mapping of all defined codes (0001–0207) to their Japanese condition labels, along with a notes object explaining special ranges. Codes in the 9000–9999 range indicate marketplace seller listings rather than Suruga-ya's own graded conditions.
The lookup_branch_number endpoint resolves a single code and returns the definition (Japanese label), is_used boolean, and a source field indicating whether the result came from the static mapping (static_mapping), an inferred range rule (range_rule), or was unrecognized (not_found). This is useful for decoding branch numbers encountered in product URLs or search results without loading the full definition table.
- Build a price tracker for specific Suruga-ya product IDs, monitoring
used_priceandnew_pricechanges over time. - Decode condition codes in bulk by mapping
branch_numbervalues from product URLs to human-readable Japanese labels viaget_branch_definitions. - Compare buyback (
buyback_price) versus sale price for used items to identify trade-in value gaps. - Search Suruga-ya inventory by Japanese keyword (e.g. 'ガンダム') and filter by category to build niche collectibles catalogs.
- Check store-specific pricing by passing
store_idtoget_product_detailto surface regional in-store listings. - Classify scraped product IDs as used or new by feeding their
branch_numbertolookup_branch_numberand reading theis_usedfield. - Aggregate search results across multiple pages and sort orders to find the cheapest available condition for a given item.
| 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 | 250 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 Suruga-ya offer an official developer API?+
What does `get_product_detail` return for price information?+
prices object containing new_price and/or used_price as integers in yen, plus a separate buyback_price integer for the trade-in offer. Either price field may be null if that condition is not listed for the queried product and branch_number combination.What is the difference between `condition_type` and `condition_detail` in product responses?+
condition_type is the broad category label from the page title, such as 中古 (used) or 新品 (new). condition_detail is a more specific grading string extracted from the parenthetical portion of the full product name, such as a specific wear or completeness grade. The branch_definition field adds the standardized Japanese label mapped from the branch number table.Does the API expose seller reviews, seller ratings, or listing history for individual sellers?+
Are there any limitations on search result coverage or pagination?+
search_products page returns a maximum of 24 items, and the total_count field tells you how many results exist across all pages. Category filtering is limited to the predefined category codes listed in the endpoint (映像ソフト, 音楽ソフト, おもちゃ・ホビー, etc.). Filtering by sub-category or brand is not currently supported. You can fork the API on Parse and revise it to add finer-grained category or attribute filters.