# Rakuten Ichiba API scraper — Japan e-commerce product search, item detail, full reviews, shop catalog, rankings & genres (rakuten.co.jp)

> Search Rakuten Ichiba by keyword or genre with sort and price filters — returns items with name, price (JPY), shop, points, shipping, rating and images. Paginated.
> ReefAPI engine `rakuten` · 7 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/rakuten/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /rakuten/v1/search — 1 credit
Search Rakuten Ichiba by keyword or genre with sort and price filters — returns items with name, price (JPY), shop, points, shipping, rating and images. Paginated.

**Parameters:**
- `keyword` (string, optional) — Search keyword (Japanese or English). Provide keyword OR genre_id.
- `genre_id` (string, optional) — Rakuten genre id to browse (discover ids via the genres action).
- `page` (integer, optional, default 1) — Result page (1-based). Page forward with meta.next_page.
- `sort` (enum, optional, default "standard") — Result ordering. [one of: standard, price_asc, price_desc, review, new]
- `min_price` (integer, optional) — Minimum price filter (JPY).
- `max_price` (integer, optional) — Maximum price filter (JPY).

**Returns:** results[] (item_name, item_price JPY, shop, points, shipping_price, review_url, images), page, total, has_more, next_page

**Example request body:**
```json
{
  "keyword": "ヘッドホン"
}
```

### POST /rakuten/v1/item — 1 credit
Get a Rakuten Ichiba product's detail — title, price (JPY), brand, shop, rating, images, category breadcrumbs, spec attributes, shipping and points.

**Parameters:**
- `url` (string, optional) — Full Rakuten item URL (the simplest input). Alternative: shop_code + item_path.
- `shop_code` (string, optional) — Rakuten shop code (pair with item_path as an alternative to url).
- `item_path` (string, optional) — Item path within the shop (pair with shop_code).

**Returns:** item{} — item_id, item_name, item_price, brand, shop, review_average/count, image_urls, breadcrumbs[], attributes[], description, free_shipping, variant_count

**Example request body:**
```json
{
  "url": "https://item.rakuten.co.jp/seedcoms/10003515-198/"
}
```

### POST /rakuten/v1/reviews — 1 credit
Get ALL buyer reviews for a Rakuten Ichiba item, paginated (30/page) — rating, body, reviewer nickname, post date and helpful count, plus the total review count.

**Parameters:**
- `url` (string, optional) — Full Rakuten item URL (the simplest input). Alternative: shop_code + item_path.
- `shop_code` (string, optional) — Rakuten shop code (pair with item_path as an alternative to url).
- `item_path` (string, optional) — Item path within the shop (pair with shop_code).
- `page` (integer, optional, default 1) — Result page (1-based). Page forward with meta.next_page.

**Returns:** reviews[] (rating, body, reviewer, posted_at, helpful_count), summary{review_average, review_count}, page, total, has_more, next_page

**Example request body:**
```json
{
  "url": "https://item.rakuten.co.jp/seedcoms/10003515-198/"
}
```

### POST /rakuten/v1/variants — 1 credit
Get a Rakuten Ichiba item's SKU variant matrix — every color/size/option combination with its price and images.

**Parameters:**
- `url` (string, optional) — Full Rakuten item URL (the simplest input). Alternative: shop_code + item_path.
- `shop_code` (string, optional) — Rakuten shop code (pair with item_path as an alternative to url).
- `item_path` (string, optional) — Item path within the shop (pair with shop_code).

**Returns:** variants[] {variant_id, selector_values, item_price, images}, selectors[], variant_count

**Example request body:**
```json
{
  "url": "https://item.rakuten.co.jp/seedcoms/10003515-198/"
}
```

### POST /rakuten/v1/shop — 1 credit
List a Rakuten Ichiba shop's catalog by shop_code — every item the shop sells, paginated.

**Parameters:**
- `shop_code` (string, required) — Rakuten shop code (the shop's urlCode, e.g. 'rakuten24').
- `page` (integer, optional, default 1) — Result page (1-based). Page forward with meta.next_page.

**Returns:** results[] shop catalog items, shop_code, page, total, has_more, next_page

**Example request body:**
```json
{
  "shop_code": "rakuten24"
}
```

### POST /rakuten/v1/ranking — 1 credit
Get the Rakuten Ichiba best-seller ranking — overall or for a genre, by day/week/realtime/month.

**Parameters:**
- `genre_id` (string, optional) — Genre id to rank within ('0' = overall, the default).
- `period` (enum, optional, default "daily") — Ranking time window. [one of: daily, weekly, realtime, monthly]
- `page` (integer, optional, default 1) — Result page (1-based). Page forward with meta.next_page.

**Returns:** results[] ranked items {rank, item_name, item_price, item_url}, genre_id, period

**Example request body:**
```json
{
  "genre_id": "0"
}
```

### POST /rakuten/v1/genres — 1 credit
Browse the Rakuten Ichiba category (genre) tree — top-level categories, or pass genre_id for a subtree.

**Parameters:**
- `genre_id` (string, optional) — Genre id to read the subtree of (omit for the top-level tree).

**Returns:** genres{} — genre tree with children[] {genre_id, name, count, leaf}, genre_id

## More
- Try it live, no code: https://reefapi.com/playground?engine=rakuten
- Human docs page: https://reefapi.com/docs/rakuten
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt