Rakuten Travel Purpose-Based Hotel Recommender
Pricing
from $0.00005 / actor start
Search Rakuten Travel hotels by area, budget, and purpose — get onsen, business, family, and solo-traveler picks with a score.
You can access the Rakuten Travel Purpose-Based Hotel Recommender programmatically from your own applications by using the Apify API. You can also choose the language preference from below. To use the Apify API, you’ll need an Apify account and your API token, found in API & Integrations in Apify Console.
{ "openapi": "3.0.1", "info": { "version": "0.1", "x-build-id": "UOVPeeByPXtrsVgZB" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/woolen_snake~rakuten-travel-purpose-recommender/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-woolen_snake-rakuten-travel-purpose-recommender", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/woolen_snake~rakuten-travel-purpose-recommender/runs": { "post": { "operationId": "runs-sync-woolen_snake-rakuten-travel-purpose-recommender", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/woolen_snake~rakuten-travel-purpose-recommender/run-sync": { "post": { "operationId": "run-sync-woolen_snake-rakuten-travel-purpose-recommender", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "applicationId", "accessKey", "middleClassCode", "smallClassCode", "detailClassCode" ], "properties": { "applicationId": { "title": "Rakuten Web Service application ID", "type": "string", "description": "Your own applicationId (UUID format since the May 2026 Rakuten Web Service migration) issued at https://webservice.rakuten.co.jp/app/create. Required to call the Rakuten Travel API. Never shared or logged by this Actor." }, "accessKey": { "title": "Rakuten Web Service access key", "type": "string", "description": "Your own accessKey, issued alongside applicationId on the same registration screen. Required since Rakuten's May 2026 API migration (the old applicationId-only auth no longer works). Never shared or logged by this Actor." }, "largeClassCode": { "title": "Area - large class code", "type": "string", "description": "Top-level area code from the Rakuten area-code hierarchy (GetAreaClass API). \"japan\" covers all of Japan and rarely needs to change.", "default": "japan" }, "middleClassCode": { "title": "Area - middle class code (required)", "type": "string", "description": "Prefecture-level area code (e.g. \"tokyo\", \"osaka\", \"kyoto\"). Look up exact codes with the GetAreaClass API (not yet wired into this v0.1 template). Prefilled with a known-working Tokyo example.", "default": "tokyo" }, "smallClassCode": { "title": "Area - small class code (required)", "type": "string", "description": "City/ward-level area code narrowing down middleClassCode further (e.g. \"tokyo\" for Tokyo's 23 wards). REQUIRED as of the Rakuten API's May 2026 migration: despite Rakuten's own docs saying middleClassCode alone should suffice, VacantHotelSearch was confirmed (2026-08-06, against a live key) to reject the request unless the full large/middle/small/detail chain is given. Look up via the GetAreaClass API. Prefilled with a known-working Tokyo example.", "default": "tokyo" }, "detailClassCode": { "title": "Area - detail class code (required)", "type": "string", "description": "Station/neighborhood-level area code narrowing down smallClassCode further. REQUIRED for the same reason as smallClassCode above (e.g. \"A\" under Tokyo's 23-ward small class). Look up via the GetAreaClass API. Prefilled with a known-working Tokyo example.", "default": "A" }, "minCharge": { "title": "Minimum price per room per night (JPY)", "minimum": 0, "type": "integer", "description": "Lower bound of the budget band. Leave blank for no lower bound." }, "maxCharge": { "title": "Maximum price per room per night (JPY)", "minimum": 0, "type": "integer", "description": "Upper bound of the budget band. Leave blank for no upper bound. Must be greater than minCharge if both are set." }, "checkinDate": { "title": "Check-in date (optional)", "type": "string", "description": "Format YYYY-MM-DD. Defaults to tomorrow if left blank (Rakuten Travel requires a real, available date range to search vacancies).", "default": "" }, "checkoutDate": { "title": "Check-out date (optional)", "type": "string", "description": "Format YYYY-MM-DD. Defaults to the day after checkinDate if left blank.", "default": "" }, "adultNum": { "title": "Number of adults", "minimum": 1, "maximum": 10, "type": "integer", "description": "Number of adults staying. Also used as a light contextual signal for the \"solo traveler\" purpose tag (1 adult nudges solo confidence up).", "default": 2 }, "purpose": { "title": "Purpose", "enum": [ "any", "onsen", "business", "family", "solo" ], "type": "string", "description": "onsen is an OFFICIAL filter (Rakuten's own squeezeCondition=onsen, confidence always 1.0). business / family / solo are ESTIMATED by keyword-dictionary matching against the hotel's own description text (see README) and are output with a purposeTagConfidence between 0 and 1 rather than treated as certain. any returns all hotels in the area/budget band, ranked by recommendationScore only.", "default": "any" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 100, "type": "integer", "description": "Maximum number of hotels to output. A charge event is generated for every item, so this directly drives run cost.", "default": 20 }, "requestDelayMs": { "title": "Request delay (ms)", "minimum": 1100, "maximum": 10000, "type": "integer", "description": "Delay between paginated calls to the Rakuten API. Rakuten enforces 1 request/second per applicationId (429 if exceeded), so this cannot be set below 1100ms for safety.", "default": 1100 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } }}OpenAPI is a standard for designing and describing RESTful APIs, allowing developers to define API structure, endpoints, and data formats in a machine-readable way. It simplifies API development, integration, and documentation.
OpenAPI is effective when used with AI agents and GPTs by standardizing how these systems interact with various APIs, for reliable integrations and efficient communication.
By defining machine-readable API specifications, OpenAPI allows AI models like GPTs to understand and use varied data sources, improving accuracy. This accelerates development, reduces errors, and provides context-aware responses, making OpenAPI a core component for AI applications.
You can download the OpenAPI definitions for Rakuten Travel Purpose-Based Hotel Recommender from the options below:
If you’d like to learn more about how OpenAPI powers GPTs, read our blog post.
You can also check out our other API clients: