# Suruga Ya — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access product condition definitions and retrieve detailed information about second-hand items from Suruga-ya, a popular Japanese marketplace for used goods. Look up specific product conditions by branch number and get comprehensive product details to compare items across the platform.

**Category:** Marketplaces | **Website:** [www.suruga-ya.jp/](https://www.suruga-ya.jp/) | **Docs:** [parse.bot/marketplace/f88f2551-620f-40b1-9d9d-ee6c086c2c67/suruga-ya-jp-api](https://parse.bot/marketplace/f88f2551-620f-40b1-9d9d-ee6c086c2c67/suruga-ya-jp-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-suruga-ya-jp-api-f88f2551/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_branch_definitions

Returns all 207 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. The response is a static mapping — no network call is made.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-suruga-ya-jp-api-f88f2551/get_branch_definitions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_product_detail

Fetch product details from suruga-ya.jp for a specific product ID, optionally with a branch_number to specify condition variant and/or store_id to specify a particular store's listing. Returns the product name, condition type, condition detail, prices, buyback price, and the branch_number definition. Requires a network fetch to suruga-ya.jp.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `branch_number` | string | No | 4-digit zero-padded branch number specifying the condition variant (e.g. 0001, 0002, 0076). When omitted, the default product page is returned. |
| `product_id` | string | Yes | Suruga-ya product ID (numeric string, e.g. 112000127, 602314882). Found in product URLs like /product/detail/{product_id}. |
| `store_id` | string | No | Store code (tenpo_cd) to view a specific store's listing (e.g. 400550). When omitted, the default online listing is shown. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-suruga-ya-jp-api-f88f2551/get_product_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch_number":"<string>","product_id":"<string>","store_id":"<string>"}'
```

### lookup_branch_number

Look up the condition definition for a specific branch_number. Returns the Japanese condition label and whether the item is used. For numbers in the 9000-9999 range, returns marketplace seller info. For undefined numbers beyond 0207, returns generic used condition info. Static lookup — no network call.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `branch_number` | string | Yes | 4-digit zero-padded branch number (e.g. 0001, 0002, 0075, 9000). Must be exactly 4 digits. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-suruga-ya-jp-api-f88f2551/lookup_branch_number \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"branch_number":"<string>"}'
```

### search_products

Search products on suruga-ya.jp by keyword or product ID. Returns paginated results (24 items per page) with product name, category, condition, price, brand, release date, and image URL. Supports sorting and category filtering. Requires a network fetch to suruga-ya.jp.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | No | Category filter code. Empty string means all categories. |
| `page` | integer | No | Page number for pagination. Each page returns up to 24 items. |
| `search_word` | string | Yes | Search keyword (Japanese or English) or product ID number. |
| `sort` | string | No | Sort order for results. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-suruga-ya-jp-api-f88f2551/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","page":"<integer>","search_word":"<string>","sort":"<string>"}'
```