# ikyu.com Room Rates Scraper (一休) (`boncross/ikyu-room-rates`) Actor Scrape each room and rate plan ikyu.com (一休) sells for a hotel or ryokan on your dates. Just add hotel URLs, ids or names and get stay and nightly prices in JPY and your currency, list price, meals, points, rooms left, cancellation, room size, beds and images. $3.50 per 1,000 priced hotel-stays. - **URL**: https://apify.com/boncross/ikyu-room-rates.md - **Developed by:** [BonCross API](https://apify.com/boncross) (community) - **Categories:** Travel - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.10 / 1,000 hotel-priceds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## ikyu.com Room Rates Scraper (一休) ### What is ikyu.com Room Rates Scraper (一休)? ikyu.com Room Rates Scraper returns the full list of rooms and plans (プラン) a hotel or ryokan sells on ikyu.com (一休) for your dates, with the price, meals and cancellation terms of each one. Paste hotel URLs, 8-digit ikyu ids or hotel names, set the stay, and press Start. One night at Hotel Granvia Kyoto came back as 18 room types, 20 plans and 96 rates. What you get here that a cheapest-price list can't tell you: - The whole grid, at one price per stay. A stay costs $0.0035 on the Free plan whether it holds 20 rates or 96. - Cancellation you can act on. Each rate has its last free-cancellation date and the charge ladder after it. The windows are short and differ by hotel: two days before arrival at one Kyoto hotel we measured, four at another. - Meals as data. Breakfast and dinner are two true-or-false columns beside ikyu's wording, and you can keep only plans with either. - A price for the party you actually have. With one 8-year-old added, a hotel's lowest rate went from ¥23,330 to ¥32,561 and its 11 rates became 6, because plans that don't take children drop out. - A sold-out date is still an answer. You get a row that says so, for $0.0005. **BonCross Verified** means we tested this actor against the live site before release and kept the record: - 40 of 40 live checks on its inputs and filters passed on 7 October 2026 - 5 hotels run the same day on 2 stays each: 6 stays priced, 2 sold out, 1 name not found - Charges matched the rows - A sold-out stay, or one your filters empty, gets a row that says so And the rest, in short: - Price several stays for the same hotels in one run, up to 366 date ranges - Read the crossed-out list price, the discount, ikyu points and rooms left on each rate - Get room size, capacity, bed sizes and photos for each room type - Add plan details for the cheapest rates: payment option, where and when meals are served, child pricing by age group, minimum and maximum nights - Add the hotel's address, coordinates, access, hot spring, parking and aspect ratings at no extra charge - Choose one row per hotel and stay, or one row per rate for a spreadsheet - Watch a set of hotels daily and get back only the stays whose lowest price moved ### What data do you get for each rate (プラン)? | | | |---|---| | 🏨 Hotel name, id and URL | 🛏️ Room type name, type and images | | Room size in square metres | Minimum and maximum capacity | | Bed configuration | Plan name and plan id | | 💴 Stay total and nightly price in JPY, tax included | Same prices in your currency | | ♨️ Hot spring tax already in each rate | Tax-inclusive flag | | List price and discount percentage | ikyu points and point rate | | 🍽️ Meal plan, with breakfast and dinner flags | Rooms left on each plan | | Free cancellation status and last free date | Charge ladder and no-show charge | | 🕒 Plan check-in and check-out times | Grid size: room types, plans, rates | | Lowest total, lowest refundable and lowest with breakfast | Previous lowest price and change | | 📍 Address, coordinates and access | Hot spring, amenities, parking, pets and children policy | ### How to scrape ikyu.com room rates 1. [Sign up for Apify](https://console.apify.com/sign-up), which is free, and open [ikyu.com Room Rates Scraper](https://apify.com/boncross/ikyu-room-rates). 2. Paste your hotels, one per line. An ikyu URL such as `https://www.ikyu.com/en-us/00000146/` works, and so does the id `00000146` or the hotel's name in English or Japanese. 3. Set the dates, adults and rooms. If you want prices in another currency beside the yen, pick it. 4. Press Start, then download the grid as Excel, CSV or JSON. If you don't have the hotels yet, [ikyu.com Search Scraper (一休)](https://apify.com/boncross/ikyu-search) lists the properties in an area with their ids. ### ⬇️ Input All it needs is a hotel. With nothing else set, you get one night for two adults in one room, 30 days from today, in yen, as one record per hotel with its room types and rates nested inside. A long list of links can go in "Start URLs (bulk upload)" as a file, a Google Sheet or a remote list. It's combined with whatever you typed under Hotels. Dates and guests inside a pasted ikyu URL are honoured. There are two run-wide limits, and they count different things. "Maximum hotel-stays for the whole run" counts priced stays: one hotel on one set of dates, with all its rooms and plans. "Maximum rows for the whole run" counts rows. The run stops at whichever it reaches first, and 0 switches a limit off. When the row limit falls partway through a stay, you get that stay's cheapest plans up to the limit, and it's billed as one stay. #### One hotel on fixed dates, with prices in dollars too ```json { "hotels": ["https://www.ikyu.com/en-us/00000146/"], "checkIn": "2026-11-20", "checkOut": "2026-11-22", "adults": 2, "currency": "USD" } ``` #### Ryokan by name, dinner plans only, with hotel details ```json { "hotels": ["Hiiragiya", "俵屋旅館", "00000284"], "checkInDaysAhead": 45, "nights": 1, "dinnerOnly": true, "includeHotelDetails": true, "language": "ja" } ``` #### Two hotels over two stays, one row per rate ```json { "hotels": ["00000146", "00000630"], "stays": [ { "checkIn": "2026-11-20", "checkOut": "2026-11-22" }, { "checkIn": "2026-12-24", "checkOut": "2026-12-26" } ], "flattenRooms": true, "freeCancellationOnly": true } ``` #### A daily watch that returns only the stays that changed ```json { "hotels": ["00000146", "00000284", "00000630"], "checkInDaysAhead": 30, "nights": 1, "priceStoreName": "ikyu-grid", "onlyNewOrChanged": true } ``` | Field | Notes | |---|---| | `hotels`, `startUrls` | ikyu URLs, 8-digit ids or names, typed or loaded in bulk. | | `maxItems`, `maxRows` | Run-wide caps on priced hotel-stays and on rows. Both default to 0, no cap. | | `maxRowsPerStay` | With one row per rate, the most rows kept per stay, cheapest first. Default 300, which is also the maximum. | | `checkIn`, `checkOut` | Fixed dates, YYYY-MM-DD. | | `checkInDaysAhead`, `nights` | Used when the dates are empty. Defaults 30 and 1. | | `stays` | Several date ranges for the same hotels, up to 366 a run. | | `adults`, `rooms`, `childrenAges` | Adults per room (default 2), rooms (default 1) and one age per child, 0 to 12. | | `freeCancellationOnly`, `breakfastOnly`, `dinnerOnly` | Keep only plans still free to cancel today, or with that meal. | | `minPerNight`, `maxPerNight` | A nightly price band per room, in the selected currency. 0 is off. | | `includePlanDetails`, `planDetailsPerStay` | Plan details for each stay's cheapest rates (default 5, and 0 means every rate). | | `includeHotelDetails` | The hotel's address, coordinates, times, amenities and images. No extra charge. | | `maxRatesPerRoom` | How many rate plans come back per room type, cheapest first. Default 30, up to 100. | | `flattenRooms` | One row per rate plan, with the hotel and stay fields repeated. | | `currency`, `language` | `JPY` by default, and yen prices are always included. `en` (default) or `ja`. | | `priceStoreName`, `onlyNewOrChanged` | The price memory for scheduled runs, and the switch that returns only changed stays. | | `maxConcurrency`, `delayMs` | Parallel requests (default 8) and an optional pause before each one (default 0). | #### For developers - `maxItems` counts priced hotel-stays. Sold-out and unchanged stays aren't counted. `maxRows` counts rows, and with `flattenRooms` a row is one room and rate plan. - `maxRatesPerRoom` caps the rate plans under each room type. The default of 30 covered every hotel we measured. If a hotel publishes more than your setting on one room, the run log says so. - `includePlanDetails` makes one extra request per rate, for the cheapest `planDetailsPerStay` rates of each stay. It isn't spent on sold-out or unchanged stays. - `childrenAges` maps to ikyu's age groups: 10 to 12 and 6 to 9 are priced as primary-school children, under 6 as an infant with meals and bedding. - `priceStoreName` names a key-value store that remembers the lowest nightly price per hotel, stay, occupancy and currency. The next run fills `previousLowestPerNight`, `priceChange` and `priceChangePct`. With `onlyNewOrChanged`, a stay whose lowest price hasn't moved writes no row. - `stays` accepts `checkIn`/`checkOut` or lowercase `checkin`/`checkout`. It replaces `checkIn` and `checkOut` when set. Lowercase `checkin`, `checkout` and `checkinDaysAhead` work at the top level too. - `maxConcurrency` runs from 1 to 32 and `delayMs` up to 10,000. The defaults are the fastest we measured without errors. - Rows are written in the order of your hotels and stays. A run Apify restarts part-way picks up where it stopped, and no stay is delivered or charged twice. ### ⬆️ Output One record per hotel and stay, holding its room types and the rates on each. With "One row per rate plan" switched on, each rate is its own row and the hotel and stay fields repeat. This is Hotel Granvia Kyoto for one night, from a run on 7 October 2026. The real record has 18 room types and 96 rates. It's shortened here to the first room type, its first rate and two of its six photos: ```json { "input": "00000146", "id": "00000146-2027-01-15-2027-01-16", "hotelId": "00000146", "hotelName": "Hotel Granvia Kyoto", "url": "https://www.ikyu.com/en-us/00000146/", "checkIn": "2027-01-15", "checkOut": "2027-01-16", "nights": 1, "adults": 2, "rooms": 1, "currency": "JPY", "totalRoomTypes": 18, "totalPlans": 20, "rateCount": 96, "isAvailable": true, "lowestTotalJpy": 19144, "lowestPerNightJpy": 19144, "lowestTotal": 19144, "lowestPerNight": 19144, "pricesIncludeTax": true, "lowestHotSpringTaxIncludedJpy": 0, "lowestRoom": "Standard 【Non-Smoking】", "lowestPlan": "[Early Bird 60] Book at least 60 days in advance for an even better deal! (No meals included)", "lowestMeal": "No meals", "lowestFreeCancellationPerNightJpy": 19144, "lowestBreakfastPerNightJpy": 29736, "pointRate": 15, "mealFacets": [ { "meal": "No meals", "mealCode": "000", "count": 11 }, { "meal": "Breakfast included", "mealCode": "001", "count": 18 }, { "meal": "Dinner included", "mealCode": "002", "count": 0 }, { "meal": "Dinner and Breakfast included", "mealCode": "003", "count": 6 }, { "meal": "Breakfast and Lunch included", "mealCode": "004", "count": 0 }, { "meal": "Lunch included", "mealCode": "005", "count": 0 }, { "meal": "Full board", "mealCode": "006", "count": 0 }, { "meal": "Lunch and Dinner included", "mealCode": "007", "count": 0 } ], "previousLowestPerNight": null, "priceChange": null, "priceChangePct": null, "previousScrapedAt": null, "scrapedAt": "2026-10-07T13:46:35.419Z", "roomTypes": [ { "roomId": "10030272", "name": "Standard 【Non-Smoking】", "type": "Twin", "sizeSqm": 30, "sizeSqmTo": null, "floorPlan": null, "floors": null, "capacity": { "min": 1, "max": 3 }, "beds": [ { "count": 2, "sleeps": 1, "widthCm": 115, "lengthCm": null } ], "checkInFrom": "15:00", "checkInUntil": "24:00", "checkOutUntil": "12:00", "renewalDate": null, "images": [ { "url": "https://www.img-ikyu.com/contents/common/image/acc6/00000146/1/org/11189370.jpg", "alt": "Standard Twin (30 sqm) (Image)" }, { "url": "https://www.img-ikyu.com/contents/common/image/acc6/00000146/1/org/11547068.jpg", "alt": "Unit bus type" } ], "attributeCodes": ["20", "6", "30", "28", "9", "29"], "rates": [ { "planId": "11539639", "plan": "[Early Bird 60] Book at least 60 days in advance for an even better deal! (No meals included)", "planImages": [ "https://www.img-ikyu.com/contents/common/image/acc6/00000146/0/org/13235400.jpg" ], "meal": "No meals", "mealCode": "000", "isBreakfastIncluded": false, "isDinnerIncluded": false, "sale": "USUALLY", "memberRankRequired": null, "isLimitedTwoWeeks": false, "isBookableStartSoon": false, "isBookableEndSoon": false, "planCheckInFrom": null, "planCheckInUntil": null, "planCheckOutUntil": null, "priceTotalJpy": 19144, "pricePerNightJpy": 19144, "priceListedTotalJpy": 25024, "baseDiscountPercent": 10, "discountPercent": 23.5, "currency": "JPY", "priceTotal": 19144, "pricePerNight": 19144, "pricesIncludeTax": true, "hotSpringTaxIncludedJpy": 0, "points": 3378, "pointRate": 15, "instantPoints": 3378, "roomsLeft": 11, "nights": 1, "adults": 2, "roomCount": 1, "priceTotalEarnPointsJpy": 22522, "children": {}, "isOccupancyAsRequested": true, "isFreeCancellation": true, "freeCancellationUntil": "2027-01-13", "freeCancellationDaysBefore": 2, "ladder": [ { "daysBefore": 1, "chargePercent": 20, "charge": null }, { "daysBefore": 0, "chargePercent": 80, "charge": null } ], "noShowChargePercent": 100 } ] } ] } ``` **Reading the prices.** They're ikyu's public rates per room, for the whole stay and the party you asked for. `priceTotalJpy` is the headline price, with the stay's points spent at once, which is how ikyu shows it. `priceTotalEarnPointsJpy` is the price if you earn the points instead. `pricesIncludeTax` is true on every rate, and on the hotel-stay row where it describes the lowest rate: ikyu quotes consumption tax and service charge inside the price. `hotSpringTaxIncludedJpy` (`lowestHotSpringTaxIncludedJpy` for the lowest rate) is the hot spring tax already inside the price, in yen for the stay, and 0 where the plan isn't sold with it included. A local accommodation tax, or a bathing tax the property collects on arrival, isn't in the price and has no amount in the data. **`id`** names the hotel and the stay, and the same hotel over several date ranges gives rows that don't collide. With one row per rate, the `id` includes the room and plan ids as well. **`isOccupancyAsRequested`** matters more than it looks. ikyu will quietly price a different party when it can't price the one you asked for. Each rate records the nights, adults and rooms ikyu priced, and this flag is false on any rate where they differ from your request. More columns on each rate: | Field | What it holds | |---|---| | `planImages` | The plan's own photo URLs. An empty list when it has none | | `sale` | ikyu's sale status code for the plan (for example `USUALLY` for a regular plan). Null when not given | | `memberRankRequired` | The ikyu membership rank the plan is restricted to. Null for a plan open to everyone | | `isLimitedTwoWeeks` | true when ikyu flags the plan as limited to a two-week window | | `isBookableStartSoon` / `isBookableEndSoon` | true when the plan's booking window opens soon / closes soon | | `planCheckInFrom` / `planCheckInUntil` / `planCheckOutUntil` | Check-in and check-out times set by this plan, where they differ from the hotel's. Null when the plan uses the hotel's times | | `baseDiscountPercent` | The discount rate ikyu shows on the plan, in percent. Null when there is none | | `instantPoints` | Points applied at once for this rate. Null when not given | | `roomCount` | The number of rooms the rate was priced for | **With plan details on**, the cheapest rates of each stay add `planNotes` and `planContent` (the plan's notes and description), `paymentOption` (for example "card online only" or "pay at the hotel") with ikyu's code in `paymentOptionCode`, `minNights` / `maxNights` and `minRooms` / `maxRooms`, the plan's meals with where and when they're served and the menu, `childPricing` (one entry per child category with `category`, `rule` and `value`, where `rule` is `percentOfAdult`, `fixedJpy`, `notAccepted`, `sameAsAdult` or `free`), `bookingError` (ikyu's reason this stay can't be booked on the plan, null when it can) and `nightDates`. All are null or empty when ikyu gives nothing. **With hotel details on**, the record gains a `hotel` object: address, coordinates, access, amenities, facilities, hot spring, parking, pickup, pets, children policy, tax note, aspect ratings and images. ### How much does it cost to scrape ikyu.com room rates? | Event | Free plan | Starter | Scale | Business | |---|---|---|---|---| | `actor-start`, per run | $0.002 | $0.002 | $0.002 | $0.002 | | `hotel-resolved`, per hotel name looked up (URLs and ids skip it) | $0.002 | $0.002 | $0.002 | $0.002 | | `hotel-checked`, per hotel and stay ikyu answered, priced or not: a sold-out stay, a stay whose plans were all filtered out or unchanged, and an id ikyu has no hotel for are charged this alone | $0.0005 | $0.0005 | $0.0005 | $0.0005 | | `hotel-priced`, per hotel and stay returned, however many rooms and plans it holds | $0.003 | $0.0027 | $0.0024 | $0.0021 | Enterprise plans pay the Business price. **$3.50 per 1,000 priced hotel-stays** on the Free plan, $2.60 on Business. You pay by the stay, not by the row, and hotel details cost nothing extra. Proxy usage and platform usage are included. - Ten hotels by id, one stay each: $0.002 + 10 × ($0.003 + $0.0005) = **$0.037** ($0.028 on Business) - Twenty hotels by name, three stays each: $0.002 + 20 × $0.002 + 60 × ($0.003 + $0.0005) = **$0.252** ($0.198 on Business) What you pay when there's nothing to price: - A sold-out stay comes back as one row with `isSoldOut: true` and costs $0.0005. - A stay whose rates were all removed by your own filters comes back as one row with `rateCount: 0`, `ratesFound` (how many rates ikyu had) and the reason in `error`, and costs $0.0005. - An unchanged stay in an only-changes run writes no row and costs $0.0005. - A stay ikyu didn't answer, and a hotel name ikyu can't match, cost nothing. You get a row saying why. On Apify's Free plan, the $5 of credits you get each month covers about 135 runs like the first example, or roughly 1,350 priced hotel-stays. ### How big is a grid, and how fast is a run? | Run | Result | Time | |---|---|---| | Hotel Vischio Kyoto by GRANVIA, 1 night | 1 hotel-stay, 5 room types | 5 s | | 4 Kyoto hotels × 3 stays, one row per room and rate plan | 12 hotel-stays, 307 rate rows | 4 s | | 6 hotels × 6 stays, one row per room and rate plan | 36 hotel-stays, 1,665 rate rows | 8 s | | 99 hotels across Japan × 3 stays | 297 hotel-stays (252 priced, 45 sold out) | 30 to 37 s on most runs, up to 2 min | These are whole runs on Apify, measured between 1 and 3 October 2026. On a long list you can expect about 500 hotel-stays a minute. One measured run in five was slower, at about 150 a minute. The default one-hour run limit therefore covers roughly 9,000 to 30,000 hotel-stays, and you can raise the run timeout for more. ### FAQ #### How should I pass a hotel? The id or the URL is the safe way, and both are free to resolve. A name in English or Japanese works too, but it resolves to ikyu's first suggestion for that name, and a namesake is possible. A name ikyu can't match at all gets a row saying so, at no charge. #### What happens when a hotel is sold out on my dates? You get one row for that hotel and stay with `isSoldOut: true` and no rates, billed $0.0005. In the 99-hotel run above, 45 of 297 stays came back that way. #### Why did "Free-cancellation plans only" remove nothing, or everything? It depends how close the stay is. The filter keeps plans that are still free to cancel today. Thirty days out, every rate at the hotels we measured was free to cancel (87 of 87 and 21 of 21), so nothing is removed. Three days out, all 7 rates at one hotel had passed their deadline. Read `freeCancellationUntil` on each rate if you need the date itself. #### Can I get one row per rate plan for a spreadsheet? Switch on "One row per rate plan". Each rate becomes its own row with the hotel, stay and room fields repeated. "Maximum rows per hotel-stay" then keeps the cheapest rates of a stay, up to 300. #### How are children priced? Add each child's age (0 to 12) under "Children's ages". ikyu prices children by age group and drops plans that don't accept them. With plan details on, `childPricing` shows each plan's rule per age group: a percentage of the adult price, a fixed amount in yen, free, the same as an adult, or not accepted. #### Do I need proxies or an ikyu account? No proxy to set up, no proxy charges, and no login. The prices are the ones ikyu shows to any visitor. #### What are the limits? - Member-only ikyu Plus rates need a login and aren't included. A plan restricted to a membership rank is flagged in `memberRankRequired`. - Up to 100 rate plans come back per room type, 30 unless you raise it. - With one row per rate, a stay is cut to its 300 cheapest rates. - Plan details cover each stay's cheapest rates (5 by default). Set "Plan details for the cheapest N rates" to 0 for all of them, at one extra request per rate. - Room sizes given in tatami mats have no square-metre figure, and `sizeSqm` is null for those rooms. #### Is it legal to scrape ikyu.com? The actor reads only the rates ikyu serves to any logged-out visitor. Collecting public prices is generally legal. How you use them is your responsibility, under ikyu's terms and the law that applies to you. ### Watch rates on a schedule, or price a stay from code For a rolling watch on a competitor set, create an Apify Schedule with "Check-in days ahead" and a price memory store. Add "Only new or changed prices" and each run reports only the stays whose lowest price moved. A webhook can push those rows to Slack or a Google Sheet through Apify's integrations. To price a stay from your own system, `POST https://api.apify.com/v2/acts/boncross~ikyu-room-rates/run-sync-get-dataset-items` with the input JSON as the body. It answers with the grid in the same call for a handful of hotels. For a long list, start the run asynchronously and read the dataset when it finishes. The `apify-client` packages for Node.js and Python wrap both. Through the Apify MCP server (`mcp.apify.com`) the actor is a tool named `boncross/ikyu-room-rates`. An agent can price a named ryokan for given dates and read back its rooms and plans. ### More from BonCross - [ikyu.com Reviews Scraper (一休)](https://apify.com/boncross/ikyu-reviews): ikyu.com (一休) reviews for hotels and ryokan. - [ikyu.com Search Scraper (一休)](https://apify.com/boncross/ikyu-search): ikyu.com (一休) search results for any Japanese area, station or landmark on your dates. - [Jalan.net Area Rates Scraper (じゃらん)](https://apify.com/boncross/jalan-area-rates): Jalan (じゃらん) prices and rooms left for every available hotel in an area, a whole… - [Jalan.net Room Rates Scraper (じゃらん)](https://apify.com/boncross/jalan-room-rates): Every plan and room Jalan (じゃらん) lists for a hotel on a date. - [Jalan.net Hotel Search Scraper (じゃらん)](https://apify.com/boncross/jalan-search): Jalan (じゃらん) hotel search results for any area and your dates. - [Marriott Hotel Details Scraper](https://apify.com/boncross/marriott-hotel-details): Everything a Marriott property publishes: address, coordinates, phones, brand, guest… ### Your feedback If a grid looks short, a rate doesn't match ikyu's page, or you need a plan field that isn't here, open an issue on the Issues tab in Apify Console with the hotel id and dates. BonCross reads each one and replies there. # Changelog This Actor's version history is a separate document: https://apify.com/boncross/ikyu-room-rates/changelog.md # Actor input Schema ## `hotels` (type: `array`): One per entry: an ikyu hotel URL (https://www.ikyu.com/en-us/00000146/, dates and guests in the URL are honoured), the 8-digit accommodation id (00000146), or a hotel name in English or Japanese (resolved by name). ## `startUrls` (type: `array`): ikyu page addresses, with the option to load them in bulk from a file, a Google Sheet or a remote list. Use this when you have more links than you want to paste. Combined with anything in the list above. ## `maxItems` (type: `integer`): Stop after this many priced hotel-stays across the run: one hotel and one stay, with all its rooms and plans. 0 means no limit. Sold-out and unchanged stays are not counted. ## `maxRows` (type: `integer`): Stop after this many rows (one per room and plan when rows are flattened). The last hotel-stay is cut to fit, keeping its cheapest plans, and billed as one stay. 0 means no limit; the run stops at whichever cap it reaches first. ## `maxRowsPerStay` (type: `integer`): With flattened rows, keep at most this many rates per hotel-stay, cheapest first (up to 300). A stay is billed once however many rows it has. ## `checkIn` (type: `string`): YYYY-MM-DD. Empty = use Check-in days ahead (or the dates in the hotel URL). Ignored when Stays is set. Lowercase `checkin` also works. ## `checkOut` (type: `string`): YYYY-MM-DD. Empty = use Nights. Lowercase `checkout` also works. ## `checkInDaysAhead` (type: `integer`): Used when Check-in is empty (for scheduled runs). Lowercase `checkinDaysAhead` also works. ## `nights` (type: `integer`): Used when Check-out is empty. ## `stays` (type: `array`): \[{"checkin":"2026-11-20","checkout":"2026-11-22"}, …], one record per hotel per stay. Up to 366 stays a run. ## `adults` (type: `integer`): Per room. ikyu prices per room for this many people. ## `rooms` (type: `integer`): Number of rooms. ## `childrenAges` (type: `array`): Optional. The age of each child, 0-12, one per line. ikyu prices children by age group: 10-12 and 6-9 as primary-school children, under 6 as an infant with meals and bedding. Adults are set above. ## `freeCancellationOnly` (type: `boolean`): Keep only plans that are still free to cancel today for the stay. ## `breakfastOnly` (type: `boolean`): Keep only plans with breakfast. ## `dinnerOnly` (type: `boolean`): Keep only plans with dinner (kaiseki etc.). ## `minPerNight` (type: `number`): In the selected currency, per room. 0 = off. ## `maxPerNight` (type: `number`): In the selected currency, per room. 0 = off. ## `includePlanDetails` (type: `boolean`): Add each rate plan's notes, payment option, meals (where and when they are served, and the menu), the nights and rooms it allows, member-only status, how children are priced by age group, and why a stay cannot be booked if it cannot. One extra request per rate, for the cheapest rates of each stay (set how many below). ## `planDetailsPerStay` (type: `integer`): How many of each stay's cheapest rates get plan details. 0 means every rate. ## `includeHotelDetails` (type: `boolean`): Also return address, coordinates, check-in and check-out times, access, amenities, facilities, hot spring, parking, ratings by aspect and images. No extra charge. ## `maxRatesPerRoom` (type: `integer`): How many rate plans to return for each room type, cheapest first. The default of 30 covers every hotel measured so far; raise it for a large ryokan that publishes more plans than that on a single room. A run that hits the limit says so in the log. ## `flattenRooms` (type: `boolean`): Push one dataset row per rate plan (hotel and stay fields repeated) instead of one row per hotel and stay with a roomTypes array. ## `currency` (type: `string`): JPY prices are always included; set USD, EUR, GBP, KRW, CNY, TWD, HKD, SGD, THB, AUD… to add ikyu's own conversion. ## `language` (type: `string`): en = ikyu's English room and plan names; ja = Japanese originals. ## `priceStoreName` (type: `string`): Key-value store name. Remembers the lowest per-night price per hotel / stay / occupancy / currency and adds previousLowestPerNight and priceChange next run. ## `onlyNewOrChanged` (type: `boolean`): With a price memory store: skip (and don't charge) hotel-stays whose lowest price is unchanged. ## `maxConcurrency` (type: `integer`): How many requests run at once across the whole run. The default is the fastest level measured clean; lower it only if a run reports refusals or errors. ## `delayMs` (type: `integer`): Optional pause before each call, in milliseconds. 0 (the default) runs as fast as the parallel limit allows. ## Actor input object example ```json { "hotels": [ "https://www.ikyu.com/en-us/00000146/" ], "startUrls": [], "maxItems": 0, "maxRows": 0, "maxRowsPerStay": 300, "checkIn": "", "checkOut": "", "checkInDaysAhead": 30, "nights": 1, "stays": [], "adults": 2, "rooms": 1, "childrenAges": [], "freeCancellationOnly": false, "breakfastOnly": false, "dinnerOnly": false, "minPerNight": 0, "maxPerNight": 0, "includePlanDetails": false, "planDetailsPerStay": 5, "includeHotelDetails": false, "maxRatesPerRoom": 30, "flattenRooms": false, "currency": "JPY", "language": "en", "priceStoreName": "", "onlyNewOrChanged": false, "maxConcurrency": 8, "delayMs": 0 } ``` # Actor output Schema ## `dataset` (type: `string`): ikyu room rates: every row the run returned. ## `stats` (type: `string`): Counts for the run: what was resolved, fetched, filtered and returned. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "hotels": [ "https://www.ikyu.com/en-us/00000146/" ] }; // Run the Actor and wait for it to finish const run = await client.actor("boncross/ikyu-room-rates").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "hotels": ["https://www.ikyu.com/en-us/00000146/"] } # Run the Actor and wait for it to finish run = client.actor("boncross/ikyu-room-rates").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 '{ "hotels": [ "https://www.ikyu.com/en-us/00000146/" ] }' | apify call boncross/ikyu-room-rates --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,boncross/ikyu-room-rates" } } } ``` 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 ` 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/gNxPiMXTZujeq4lh2/builds/h6OHjAyHJS4oAVifD/openapi.json