# Mercari Japan — 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.

> Search and browse millions of product listings on Mercari Japan with bilingual support, filtering by categories and getting detailed pricing, item specifications, and seller information. Access comprehensive marketplace data including product summaries, category overviews, and individual seller profiles to find exactly what you're looking for.

**Category:** Marketplaces | **Website:** [jp.mercari.com/](https://jp.mercari.com/) | **Docs:** [parse.bot/marketplace/48cf336c-1769-42fe-a6e5-84751511e765/jp-mercari-com-api](https://parse.bot/marketplace/48cf336c-1769-42fe-a6e5-84751511e765/jp-mercari-com-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-jp-mercari-com-api-48cf336c/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_all_categories

Fetch the complete hierarchical category tree for Mercari Japan. Returns all product categories with parent-child relationships, display ordering, image URLs, and short labels. Use category IDs from this tree to filter search results or browse items by category.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-jp-mercari-com-api-48cf336c/get_all_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_category_items

Browse items under a specific category with optional price and sort filters. Uses the same search engine as search_items but requires a category_id. Returns up to 120 items per page with cursor-based pagination.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | Yes | Category ID to browse (from get_all_categories) |
| `order` | string | No | Sort order |
| `page_token` | string | No | Pagination token from previous response's next_page_token. Managed automatically by the SDK paginator. |
| `price_max` | integer | No | Maximum price in JPY |
| `price_min` | integer | No | Minimum price in JPY |
| `sort` | string | No | Sort field. Omitting sorts by relevance. |
| `status` | string | No | Item status filter |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-jp-mercari-com-api-48cf336c/get_category_items \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","order":"<string>","page_token":"<string>","price_max":"<integer>","price_min":"<integer>","sort":"<string>","status":"<string>"}'
```

### get_item_detail

Fetch full details for a single Mercari item by its ID. Returns the complete listing including description, seller information, images, condition, shipping details, and category. Item IDs start with 'm' followed by digits (e.g. 'm77009256155'). Returns stale_input if the item does not exist.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `item_id` | string | Yes | Mercari item ID starting with 'm' followed by digits (e.g. 'm77009256155') |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-jp-mercari-com-api-48cf336c/get_item_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"item_id":"<string>"}'
```

### get_search_summary

Get aggregate price statistics for a search query based on up to 120 sample items. Returns min, max, average, and median prices across all statuses. Useful for market analysis before purchasing. The sample_size indicates how many items were used for the calculation (max 120 even when total_count is higher).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `keyword` | string | Yes | Search keyword to get price statistics for |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-jp-mercari-com-api-48cf336c/get_search_summary \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"<string>"}'
```

### get_seller_profile

Fetch all items listed by a specific seller. Returns items across all statuses (on sale, sold out, trading) from the seller's profile. Seller IDs are numeric and can be found in get_item_detail responses.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `user_id` | string | Yes | Seller's numeric user ID (from get_item_detail seller.id field) |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-jp-mercari-com-api-48cf336c/get_seller_profile \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"<string>"}'
```

### search_items

Search for items on Mercari Japan with optional filters including keyword, category, price range, and sort options. Returns up to 120 items per page with cursor-based pagination via next_page_token. When no keyword or category is specified, returns trending/recent items. Total count is capped at 15000 by the upstream API.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_id` | string | No | Filter by category ID from get_all_categories endpoint |
| `keyword` | string | No | Search keyword to match item titles and descriptions |
| `order` | string | No | Sort order |
| `page_token` | string | No | Pagination token from previous response's next_page_token. Managed automatically by the SDK paginator. |
| `price_max` | integer | No | Maximum price in JPY |
| `price_min` | integer | No | Minimum price in JPY |
| `sort` | string | No | Sort field. Omitting sorts by relevance. |
| `status` | string | No | Item status filter |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-jp-mercari-com-api-48cf336c/search_items \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_id":"<string>","keyword":"<string>","order":"<string>","page_token":"<string>","price_max":"<integer>","price_min":"<integer>","sort":"<string>","status":"<string>"}'
```