# Japan Rakuten Product & Hotel Search (Official API) (`jpopendata/japan-rakuten-api`) Actor

Search Rakuten Ichiba products and Rakuten Travel hotels via the official Rakuten Web Service APIs (JSON). You supply your own Rakuten application ID / access key. Unofficial; not affiliated with Rakuten Group.

- **URL**: https://apify.com/jpopendata/japan-rakuten-api.md
- **Developed by:** [JP Open Data](https://apify.com/jpopendata) (community)
- **Categories:**
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 record scrapeds

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Japan Rakuten Product & Hotel Search (Official API)

**Search Japan's Rakuten Ichiba product catalogue and Rakuten Travel hotels through the official Rakuten Web Service APIs (JSON) — clean, structured records: price, shop, genre, points, review score, stock; hotel min-charge, location, review score, access.**

This Actor is a thin, polite client for the **official** Rakuten Web Service APIs (`openapi.rakuten.co.jp`): the **Rakuten Ichiba Item Search API** and the **Rakuten Travel SimpleHotelSearch API**. It is **not a scraper** — it calls the documented JSON APIs the way Rakuten intends, using **your own Rakuten application ID**, and returns each hit as a flat record with a legal envelope (`source` / `sourceUrl` / `license` / `retrievedAt`) on every item.

> **Unofficial tool.** Independently built and maintained. **Not affiliated with, endorsed by, or connected to Rakuten Group, Inc.** "Rakuten", "楽天市場", and "楽天トラベル" are trademarks of their respective owners. Every record carries the credit **Supported by Rakuten Developers** that the Rakuten Web Service terms require.

***

### Quick start — verified input

Copy, paste, replace the keys, run (verified against mock API fixtures in `npm test`; a live run needs your own application ID — see the next section for how to get one in two minutes):

```json
{
  "mode": "ichiba_items",
  "applicationId": "<your key>",
  "accessKey": "<your key>",
  "keyword": "緑茶",
  "maxItems": 100
}
```

Get both values at https://webservice.rakuten.co.jp/ (free; Rakuten ID needed) → **アプリID発行** → the dashboard shows the アプリID (`applicationId`) and アクセスキー (`accessKey`). For hotels use `{"mode": "travel_hotels", "middleClassCode": "tokyo", ...}`.

### ⚠️ You need your own Rakuten application ID (and access key)

This Actor **does not bundle an API key.** You must supply your **own** free Rakuten application ID (and, on the current endpoint versions, an access key) in the `applicationId` / `accessKey` inputs.

1. Sign in with a Rakuten member account.
2. Register an application at **https://webservice.rakuten.co.jp/** (a developer may register up to 5 apps).
3. Copy your **applicationId** and **accessKey** from the app dashboard into this Actor's inputs (both are stored as secrets and redacted from all logs).

Why this design? The Rakuten Web Service terms bind API usage — including the ~1 request/second rate limit and the commercial-use rules — to the **application-ID holder**. By running under **your** ID, every call stays inside **your** own Rakuten Web Service agreement, and there is no shared-key ownership problem.

### Terms you are responsible for (please read)

You are the API user, so **compliance with the [Rakuten Web Service 利用規約](https://webservice.rakuten.co.jp/guide/rule) is your responsibility.** Two clauses matter most:

- **第10条(4)** — you may earn income from this data **only via Rakuten Affiliate** (or with Rakuten's explicit permission). This Actor supports that sanctioned path: set `affiliateId` and every record gains an `affiliateUrl`.
- **第10条(9)** — you must **not** store the retrieved information "in a place that enables sharing with unspecified and/or many people" (i.e. no public redistribution). The Actor writes results to **your own private Apify dataset**; keep them private.
- **第13条 (credit)** — display **Supported by Rakuten Developers** when you use the data. It is embedded verbatim in the `license` field of every record.

If your use case does not fit these terms (e.g. reselling the raw data publicly), this Actor is not the right tool.

### Two modes

Set `mode`:

- **`ichiba_items`** — Rakuten Ichiba product search. At least **one** of `keyword` / `genreId` / `itemCode` / `shopCode` is required. Optional `minPrice` / `maxPrice`, `sort`.
- **`travel_hotels`** — Rakuten Travel hotel/ryokan search. At least **one** of: `middleClassCode` (prefecture) \[+ `smallClassCode` / `detailClassCode`], **or** `latitude` + `longitude` \[+ `searchRadius`], **or** `hotelNo`.

Discover Rakuten's genre IDs and Travel area class codes with Rakuten's own genre-search / GetAreaClass APIs.

### Sample output — Ichiba (dataset item)

```json
{
  "itemName": "静岡県産 深蒸し緑茶 100g 3袋セット",
  "itemCode": "storeaaa:greentea-100g-3set",
  "priceJpy": 1980,
  "shopName": "静岡茶園 楽天市場店",
  "shopCode": "storeaaa",
  "genreId": "100227",
  "janCode": null,
  "availability": "in_stock",
  "pointRate": 1,
  "reviewAverage": 4.55,
  "reviewCount": 231,
  "imageUrl": "https://thumbnail.image.rakuten.co.jp/@0_mall/storeaaa/x_m.jpg",
  "itemUrl": "https://item.rakuten.co.jp/storeaaa/greentea-100g-3set/",
  "affiliateUrl": null,
  "source": "楽天ウェブサービス（楽天市場商品検索API／楽天トラベル施設検索API） / Rakuten Web Service (Rakuten Group, Inc.)",
  "sourceUrl": "https://webservice.rakuten.co.jp/documentation/ichiba-item-search",
  "license": "Supported by Rakuten Developers（…第13条に基づく表示）。… unofficial, not affiliated with … Rakuten Group, Inc. …",
  "retrievedAt": "2026-08-26T09:12:44Z"
}
```

### Sample output — Travel (dataset item)

```json
{
  "hotelName": "新宿グランドホテル",
  "hotelNo": "143637",
  "prefecture": "東京都",
  "city": "新宿区",
  "minChargeJpy": 8800,
  "reviewAverage": 4.12,
  "reviewCount": 1204,
  "access": "JR新宿駅 東口より徒歩5分",
  "hotelSpecial": "全室Wi-Fi無料。新宿駅至近のビジネスホテル。",
  "latitude": 128010.5,
  "longitude": 502340.2,
  "imageUrl": "https://img.travel.rakuten.co.jp/image/hotel/143637_m.jpg",
  "hotelInfoUrl": "https://img.travel.rakuten.co.jp/HOTEL/143637/143637.html",
  "affiliateUrl": null,
  "source": "楽天ウェブサービス…",
  "sourceUrl": "https://webservice.rakuten.co.jp/documentation/simple-hotel-search",
  "license": "Supported by Rakuten Developers…",
  "retrievedAt": "2026-08-26T09:12:44Z"
}
```

`reviewAverage`/`reviewCount` are the **numeric** review score and count only — **review text, reviewer names, and hotel/shop phone numbers are never retrieved.** Missing values are `null` (not zero-filled or empty-stringed).

### Input example

```json
{
  "mode": "ichiba_items",
  "applicationId": "<your key>",
  "accessKey": "<your key>",
  "keyword": "緑茶",
  "minPrice": 500,
  "maxPrice": 3000,
  "sort": "-reviewCount",
  "maxItems": 200
}
```

#### Common input mistakes

| Mistake | Correct |
|---------|---------|
| `"applicationId": "<your key>"` left as is / empty | paste your real 19-digit アプリID (the run fails immediately with a link to get one) |
| `"keyword": "緑茶"` with `"mode": "travel_hotels"` | keyword is an Ichiba field — use `"mode": "ichiba_items"`, or give `middleClassCode` for hotels |
| `"middleClassCode": "Tokyo"` / `"東京都"` | lower-case romaji class code: `"tokyo"` (upper case is folded for you; kanji is not) |
| `"latitude": 35.69` without `longitude` | both coordinates together, decimal degrees |
| `"searchRadius": 10` | 0.1–3.0 km |
| `"sort": "price"` / `"newest"` | accepted — canonical tokens are `+itemPrice`, `-itemPrice`, `-reviewCount`, `-updateTimestamp` … |

#### Empty results?

A run that finds nothing completes with 0 items and a warning in the log (not a failure). Typical causes: an English `keyword` for a product listed only in Japanese (try `緑茶` instead of `green tea`), a `shopCode`/`genreId`/`itemCode` that does not exist, a Travel `smallClassCode` that does not belong to the given `middleClassCode`, or a geo search in an area with no Rakuten Travel facilities within the radius. Broaden the query or drop a filter and retry. HTTP 400 `wrong_parameter` with a valid key usually means a class code is misspelled; 401/403 means the application ID / access key is wrong.

### Affiliate links (optional & recommended)

Set `affiliateId` (your Rakuten affiliate ID) and each record will include an `affiliateUrl`. This is the income path Rakuten's terms permit (第10条(4)).

### Pricing

Pay per result — see the pricing tab. Note the Rakuten API's own limit of **~1 request per second** per application; this Actor spaces requests ≥ 1.1 s apart and pages 30 hits per request, so a few hundred items take a minute or two.

### FAQ

**Is this official?**
No. **Unofficial**, not affiliated with Rakuten Group. It is a client of Rakuten's official public Web Service APIs.

**Do you store or resell Rakuten's data?**
No. The Actor fetches results live under **your** application ID and writes them to **your** Apify dataset. You are the API user; the data lands in your account. Keep it private (第10条(9)) and keep the **Supported by Rakuten Developers** credit (embedded in every record) when you display it.

**Why are `applicationId` / `accessKey` required and not provided?**
Because Rakuten binds API usage, rate limits, and commercial-use rules to an application ID, and that ID should be yours. They are entered as secrets and redacted from all logs.

**Any privacy concerns?**
Product / shop / hotel data only. Review bodies, reviewer names, and phone/fax numbers are deliberately not read. Automated tests assert no phone/e-mail strings and full source attribution on every record.

**Rate limits / server load?**
One sequential connection, ≥ 1.1 s between requests (Rakuten caps at ~1/sec per app), exponential backoff on 429/5xx, a hard per-run request budget, and no rate-limit evasion — a persistent block fails the run visibly.

### Search terms this Actor answers

Rakuten API actor · Rakuten Ichiba product data · Japan e-commerce product data · Rakuten Travel data · Rakuten hotel search API · Japan online shopping price data · Rakuten Ichiba item search · Japan hotel & ryokan data · Rakuten affiliate product feed

### Note for the Apify automated build test

This Actor **requires** a valid personal Rakuten `applicationId` (secret, plus `accessKey` on current endpoint versions) to make any live call, so Apify's default automated run test cannot pass unattended (no key). **An automated-test exemption is requested for this Actor** (same handling as other key-required API Actors, e.g. `japan-yahoo-shopping-api`, `japan-radio-certifications`). Functionality is covered by the unit test suite (`npm test`, 37 tests) over mock API fixtures for both modes; a live run needs the buyer's own application ID.

***

*Official APIs: Rakuten Ichiba Item Search — https://webservice.rakuten.co.jp/documentation/ichiba-item-search ; Rakuten Travel SimpleHotelSearch — https://webservice.rakuten.co.jp/documentation/simple-hotel-search . Terms: https://webservice.rakuten.co.jp/guide/rule . Credit **Supported by Rakuten Developers** is embedded in every record. Unofficial; not affiliated with Rakuten Group, Inc.*

# Actor input Schema

## `mode` (type: `string`):

Choose the sub-API to call: `ichiba_items` (default) = Rakuten Ichiba product search (set keyword / genreId / itemCode / shopCode), or `travel_hotels` = Rakuten Travel hotel/ryokan search (set middleClassCode, or latitude+longitude, or hotelNo). Aliases "ichiba"/"travel"/"hotels" are accepted. Example: "ichiba\_items".

## `applicationId` (type: `string`):

REQUIRED. YOUR OWN Rakuten application ID (a 19-digit number from the Rakuten Web Service app dashboard). This Actor does NOT bundle a shared key — every request runs under your application ID so it stays within your own Rakuten Web Service agreement, and Rakuten's per-app rate limit applies to you. Register a free app (up to 5 per developer): https://webservice.rakuten.co.jp/ → アプリID発行 → copy the アプリID/developerId.

## `accessKey` (type: `string`):

Your Rakuten access key (アクセスキー), shown next to the application ID in the Rakuten Web Service app dashboard. The current Rakuten endpoint versions require it alongside the application ID (older apps may work without it).

## `affiliateId` (type: `string`):

Optional. Your Rakuten affiliate ID. When set, each record includes an affiliateUrl. Note: Rakuten's terms permit earning income from this data only via Rakuten Affiliate (第10条(4)).

## `keyword` (type: `string`):

\[Ichiba] Free-text product keyword (e.g. "緑茶", "Nintendo Switch"). Japanese matches best. Ichiba mode: at least ONE of keyword / genreId / itemCode / shopCode is required.

## `genreId` (type: `string`):

\[Ichiba] Rakuten Ichiba genre ID to restrict results (numeric, e.g. "100316"). Discover IDs with Rakuten's genre-search API.

## `itemCode` (type: `string`):

\[Ichiba] Exact Rakuten item code in the form shopCode:itemId (e.g. "shop-name:10000123") to look up a specific product.

## `shopCode` (type: `string`):

\[Ichiba] Restrict results to a single Rakuten Ichiba shop by its shop code (the shop slug in the URL, e.g. "rakuten24").

## `minPrice` (type: `integer`):

\[Ichiba] Lower price bound in yen (inclusive, whole number, e.g. 500).

## `maxPrice` (type: `integer`):

\[Ichiba] Upper price bound in yen (inclusive, whole number, e.g. 3000). Must be >= minPrice.

## `sort` (type: `string`):

\[Ichiba] Result ordering. `standard` relevance (default), `+itemPrice`/`-itemPrice` price asc/desc, `-reviewCount` most reviewed, `-reviewAverage` best rated, `-updateTimestamp` newest. Aliases such as "price\_asc", "cheapest", "newest" are accepted via the API.

## `largeClassCode` (type: `string`):

Rakuten Travel large class code. Defaults to `japan`.

## `middleClassCode` (type: `string`):

\[Travel] Rakuten Travel middle class code = prefecture, lower-case romaji, e.g. "tokyo", "osaka", "kyoto", "hokkaido", "okinawa". Travel mode requires this, OR latitude+longitude, OR hotelNo. Discover codes with Rakuten's GetAreaClass API.

## `smallClassCode` (type: `string`):

\[Travel] Rakuten Travel small class code (city/area within the prefecture, e.g. "shinjuku"). Requires middleClassCode.

## `detailClassCode` (type: `string`):

\[Travel] Rakuten Travel detail class code (a sub-area, e.g. "A"). Requires smallClassCode.

## `latitude` (type: `string`):

\[Travel] Latitude for a geo radius search, decimal degrees (WGS84), e.g. "35.6895". Provide together with longitude.

## `longitude` (type: `string`):

\[Travel] Longitude for a geo radius search, decimal degrees (WGS84), e.g. "139.6917". Provide together with latitude.

## `searchRadius` (type: `string`):

\[Travel] Radius for a geo search, 0.1 to 3.0 km (one decimal, e.g. "3.0"). Defaults to 3.0 when a geo search is used.

## `hotelNo` (type: `string`):

\[Travel] Look up a single Rakuten Travel facility by its hotelNo (the number in the hotel's travel.rakuten.co.jp URL, e.g. "1234").

## `maxItems` (type: `integer`):

Maximum number of records to output (1-3000, default 100). The upstream paginates 30 hits per request up to page 100 (~3000 hits per query).

## `maxApiRequests` (type: `integer`):

Hard safety cap on API requests per run (1-110, default 5; each page = up to 30 items). Politeness (1 connection, >= 1.1 s spacing per Rakuten's ~1 req/sec limit, exponential backoff on 429/5xx) is enforced in code.

## `proxyConfiguration` (type: `object`):

Apify proxy settings. Default is NO proxy (direct connection) — an official JSON API rarely needs one. The Actor backs off exponentially on 429/5xx and fails visibly on a persistent block; it never attempts rate-limit evasion.

## Actor input object example

```json
{
  "mode": "ichiba_items",
  "keyword": "緑茶",
  "largeClassCode": "japan",
  "middleClassCode": "tokyo",
  "maxItems": 100,
  "maxApiRequests": 5,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `records` (type: `string`):

Structured product / hotel records with source attribution (source, sourceUrl, license, retrievedAt) on every item.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "ichiba_items",
    "keyword": "緑茶",
    "maxItems": 100,
    "maxApiRequests": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("jpopendata/japan-rakuten-api").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "ichiba_items",
    "keyword": "緑茶",
    "maxItems": 100,
    "maxApiRequests": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("jpopendata/japan-rakuten-api").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "ichiba_items",
  "keyword": "緑茶",
  "maxItems": 100,
  "maxApiRequests": 5
}' |
apify call jpopendata/japan-rakuten-api --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,jpopendata/japan-rakuten-api"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/WfbhIg7e1Ku7HSOMP/builds/iLXyqvwo5qCQ8akkH/openapi.json