Rakuten Travel Hotel Scraper

One query in, one flat table out. Give it a Japanese destination and a date and it returns the hotels and ryokan Rakuten Travel has available that night, each with the lowest bookable plan price in JPY, the plan that price belongs to, the guest rating and the review count.

Built to be called by an agent: small input, small output, no pagination to drive, no session to keep, deterministic field names.

Input

field	meaning
destination	tokyo, kyoto, 東京都, or narrowed: tokyo/新宿, kyoto/嵐山
hotelIds	optional; hotel numbers or Rakuten hotel URLs, instead of a search
checkIn	ISO date, e.g. 2026-09-10
nights	length of stay; check-out is derived
adults, rooms	party size, which changes the price and not just the filter
maxResults	hard stop; the run costs what it collects
includeUnpriced	off by default; see below

Areas are resolved against Rakuten Travel's own area index while the run is happening, not against a table baked into this actor. An unrecognised area name fails immediately with the list of areas that do exist, so a typo costs one request rather than an empty dataset.

Output

One row per hotel:

{
  "hotel_id": "141356",
  "hotel_name": "高濃度炭酸泉　八重桜の湯　スーパーホテルＰｒｅｍｉｅｒ東京駅八重洲中央口",
  "hotel_name_romaji": null,
  "area": "新宿・中野・荻窪・四谷",
  "price_jpy": 26000,
  "plan_name": "【素泊まり】【さき楽早得型】14日前のご予約におすすめ！…",
  "rating": 4.45,
  "review_count": 4176,
  "url": "https://travel.rakuten.co.jp/HOTEL/141356/141356.html",
  "access": "アクセス　：東京駅より徒歩３分…",
  "check_in": "2026-09-10",
  "check_out": "2026-09-11",
  "nights": 1,
  "adults": 2,
  "rooms": 1
}

price_jpy is tax-inclusive, covers the whole stay for the whole party as searched, and is the cheapest plan Rakuten showed for those dates. plan_name is the plan that price belongs to, read from the same block, so the two always match.

What this actor will not do

hotel_name_romaji is always null. Rakuten Travel's Japanese site publishes no romaji or English hotel name anywhere on a search result. travel.rakuten.com does carry English names, but it refuses connections from datacenter addresses outright. Rather than transliterate the Japanese name and hand you a machine guess dressed as a fact, the field is null. The same rule covers the rest of the row: a hotel with no reviews yet gets rating: null and review_count: null, never 0, because a zero reads as a measurement.

area is null when you search by hotelIds, because a single-hotel lookup carries no area heading to read it from.

A hotel with no bookable plan for your dates is dropped, not billed for. Rakuten sometimes lists a property on a result page with nothing bookable on it. You asked what it costs to stay there that night, and a row with a null price is not that answer, so it is skipped, counted in the run log as unpriced skipped, and never charged for. Set includeUnpriced if you want those rows anyway - for example to enumerate every property in an area regardless of availability.

An empty result always arrives with its reason attached. A run that delivers nothing sets a status message saying which of these happened: the area was genuinely sold out, every listed hotel was unpriced, the hotel id had no availability, or Rakuten refused the search outright. It never returns an unexplained empty dataset.

A refused search is never reported as a sold-out night. searchVacant answers parameters it will not accept by redirecting to Rakuten's own area index - HTTP 200, ~48 KB of prefecture links, no "no vacancy" notice anywhere on it. This actor detects that page, along with bot interstitials and responses that did not come from Rakuten at all, and fails the request instead of reading "no hotel cards" as "no hotels". Interstitials and off-site responses are treated as transient, so the retry rotates to a fresh exit address; a result page whose markup has genuinely been rebuilt is treated as permanent, because no address fixes that and retrying it would only spend your money.

Dates that cannot be answered are refused before anything is charged. A check-in in the past, one more than 365 days out, or a stay longer than 30 nights fails immediately with the reason, without billing the start event.

Prices are what Rakuten displayed, not a quote. They move; re-run for fresh ones.

Anti-bot

Measured 2026-08-24: travel.rakuten.co.jp answers datacenter addresses with HTTP 200, no bot check, no cookie and no JavaScript required. The proxy input is there for large jobs and for the day that changes; it is not needed today.

Billing

Pay per event. actor-start covers the fixed cost of a run - including a run that legitimately finds nothing on a sold-out night - and hotel-scraped is charged once per row that reaches the dataset. Duplicates across pages are not charged twice, and neither unpriced hotels nor a refused search are charged for at all.