# AI Holiday Planner: Every Stay Compared, Your Days Planned (`zaiq/holiday-planner`) Actor Enter where, when, who is going, your budget and your kind of trip (family, relaxing, adrenaline, nightlife...). It compares every stay on Google Hotels and Airbnb, reads their reviews, checks opening hours and drive times, and returns a trip page, PDF and calendar. Pay only for a plan that passes. - **URL**: https://apify.com/zaiq/holiday-planner.md - **Developed by:** [Zaiq](https://apify.com/zaiq) (community) - **Categories:** Travel, AI - **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $7,992.00 / 1,000 full plans 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 ## AI Holiday Planner: every stay compared, the reviews read, your days planned Tell it where, when, who is going, your budget and the kind of holiday you want: family, relaxing, adrenaline, nightlife (a jol), romantic, culture, food and wine, nature, beach, luxury or budget. It compares every place to stay it can find for your dates on Google Hotels (with every booking site's price) and Airbnb, reads the recent reviews of the best ones, including Booking.com's for the leading hotels, plans each day around real opening hours and drive times, prices car hire and finds the experiences worth booking. You get a trip page made for your phone, a PDF, a calendar file and a booking link for every stay. **$9.99 for a full plan, $2.99 for Express**, charged once and only when the plan passes every check: each place open at its planned time, every drive possible, the stay fits your party and budget, every review quote found word for word in the reviews, and the files delivered. The AI it uses is billed by Apify at cost, about $0.40 a plan (measured 18 Oct). ### What you get | Field | What it holds | |---|---| | Trip page | One page for your phone: where to stay, day by day, budget and what to book ahead. Also as a PDF and a calendar file (.ics). | | Where to stay | The best picks from the whole market for your party, each with its price for your dates, why it suits you, dated review quotes, what to watch for and a booking link. | | Popular, but skipped | Well-known stays it ruled out, and why (no price for your party, too few beds, review red flags, too far from your days). | | Day by day | Themed days with times, opening hours checked for that day, drive times, a rest at your stay when the pace calls for it, lunch and dinner nearby, and tips from recent reviews. | | Car hire | Live car hire prices for your dates from the main airport: the cheapest car that fits your party and bags, the cheapest automatic, the best-rated supplier and a roomier option, with the deposit, excess and mileage as stated. The price is checked on the offer page and goes into your budget. | | Experiences to book | Bookable tours and activities for your trip style, such as shark cage diving, paragliding, wine tours, boat trips and pub crawls, with from-prices, ratings and links; dated where the site shows your dates. | | Your kind of holiday | Trip styles change what is searched and how days run: bars and clubs after dinner for nightlife, an adventure operator on calm mornings for adrenaline, spas and long lunches for relaxing. | | Your needs | Halal, kosher, vegetarian, vegan or gluten-free meals, wheelchair-friendly stops and stays, and pet-friendly stays. | | Pack | A packing list for these days, this weather and these activities. | | Budget | Your stay, meals from Google's price ranges, official entry fees where the attraction publishes them; anything unpriced is listed, never counted as zero. | | Flights | With Add flights: the cheapest and fastest options from your city and nearby dates, with links to book. | | Data | plan.json and dataset rows (stays, days, stops, flights, budget lines) for your own app or agent; SUMMARY records sources, coverage and AI cost. | ### What people use it for - **Families:** Stays that really sleep everyone, kid-friendly days with rest time, and reviews read for safety, noise, beds and parking. - **Couples and friends:** A jol, an adrenaline weekend or a romantic escape: the best-reviewed places for that style, days that do not zigzag across the city. - **Travel agencies:** A branded first draft for a client in minutes: add your agency name, logo and contact line. - **Apps and AI agents:** Call it from the API and get structured stays, days and budget lines with sources and dates. ### How to use it 1. Enter the destination with its country, your dates, who is going and your total budget. 2. Add what you enjoy and anything the stay must have (pool, parking, two bedrooms). Optionally describe the trip in your own words. 3. Choose Full or Express. Turn on Add flights and enter your city for flight prices. 4. Open the Trip page link in the output. Check prices again before you book: they are snapshots from the time of the run. ### Input | Field | Example | Notes | |---|---|---| | Where are you going? | Cape Town, South Africa | City or region with its country. | | Arrive / Leave | 2026-12-12 / 2026-12-17 | 1 to 14 nights. | | Plan | Full ($9.99) or Express ($2.99) | Express compares fewer stays and skips the editor's check. | | Adults, children's ages | 2; \[7, 10] | Every price and stay is checked for the whole party. | | Trip style | nightlife, adrenaline | Any of family, relaxing, adrenaline, nightlife, romantic, culture, food and wine, nature, beach, luxury, budget. | | Total budget, currency | 40000, ZAR | Any three-letter currency. | | What you enjoy, pace | beaches, food, nature; relaxed | Shapes the days and the rest time. | | Food needs, wheelchair, pet | halal; on; off | Every meal stop and stay is checked against them. | | The stay must have | pool, parking | Only stays that list it qualify; minimum bedrooms and beds too. | | Add flights, flying from | on; Johannesburg | Flight prices for your dates and nearby dates. | | Your agency name, logo URL | optional | Shown on the trip page and PDF. | ### Output Each result is one row in the run's dataset (download it as JSON, CSV, Excel, XML or HTML, or read it through the API). An example row (values shortened): ```json { "kind": "stay", "name": "Example family apartment", "total": 15975.0, "currency": "ZAR", "rating": 4.72, "reviewCount": 330, "bedrooms": 2, "beds": 3, "sleeps": 4, "priceBasis": "displayed total; taxes/fees may remain", "fit": { "status": "yes", "reasons": [], "basis": "Published capacity and requested-party quote; bedrooms alone never establish occupancy" }, "url": "https://example.org/stays/family-apartment" } ``` This example is based on a real direct Cape Town test run on 18 October 2026. Property names and site addresses were replaced. The test used a fake model, produced six days and fourteen scheduled stops, and did not charge a plan event. Review dates and prices are snapshots. SUMMARY records source coverage and limitations. ### Pricing - **$9.99 per validated Full plan** (primary event). - **$2.99 per validated Express plan**. - The price is charged once per delivered plan, after validation and delivery of HTML, PDF, JSON and calendar files. A failed source alone is not a charged row. - If the remaining spending limit is below the selected event price, the Actor makes no source or AI requests and returns a free note naming that price. - AI usage is separate, billed by Apify’s gateway to the buyer. The design target is about $1 for a full plan, but real usage varies and has not been measured in these free tests. The engine stops further AI work at its $3 usage threshold; a call already in progress may exceed that threshold. What typical jobs cost at the list price: | Job | Cost | |---|---| | One Full plan | $9.99 plus gateway model usage | | One Express plan | $2.99 plus gateway model usage | | Failed validation | $0 plan event; any model usage already incurred may still be billed | | Limit below event price | No source or model requests | On Apify's Scale and Business plans the per-event prices are lower (Store discounts). Set **Maximum cost per run** and the Actor stops cleanly when it is reached: you never pay more than that. ### Tips - Put the country in the destination (Cape Town, South Africa) so the right city is planned. - Children's ages matter: stays are priced and checked for the exact party. - Book the stay soon after the run: prices and availability move. - For a weekend away, choose Express. - Pick one or two trip styles; more than three makes every day a compromise. ### Use it through the API **Python** ```python from apify_client import ApifyClient client = ApifyClient("") run = client.actor("zaiq/holiday-planner").call(run_input={"destination": "Cape Town, South Africa", "adults": 2, "budget": 40000, "currency": "ZAR", "planLevel": "express"}) for row in client.dataset(run["defaultDatasetId"]).iterate_items(): print(row) ``` **JavaScript** ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: '' }); const run = await client.actor('zaiq/holiday-planner').call({"destination": "Cape Town, South Africa", "adults": 2, "budget": 40000, "currency": "ZAR", "planLevel": "express"}); const { items } = await client.dataset(run.defaultDatasetId).listItems(); ``` **HTTP (one call, results back)** ```bash curl -X POST 'https://api.apify.com/v2/acts/zaiq~holiday-planner/run-sync-get-dataset-items?token=' \ -H 'Content-Type: application/json' \ -d '{"destination": "Cape Town, South Africa", "adults": 2, "budget": 40000, "currency": "ZAR", "planLevel": "express"}' ``` ### Integrations and schedules - **Schedules:** run it every hour, day or week from the Apify Console (Schedules) and keep a history of results. - **Make, Zapier, n8n, Google Sheets, Slack, Airtable:** connect it through Apify's integrations, or send each finished run to a **webhook**. - **Datasets:** results stay in the run's dataset; export them or read them by API whenever you need them. ### Use it with AI agents (MCP) Add Apify's MCP server (`https://mcp.apify.com`) to Claude, ChatGPT, Cursor, VS Code or any MCP client. The agent can find this Actor and run it for you: ask it for "Plan a five-night coastal holiday for a family of four, with priced stays and a sourced budget". AI agents can also pay for runs directly through Apify's agentic payments. ### Limits - No login, CAPTCHA solving or forged challenge tokens. A source can withhold public data. - Search caps and the 150-request run allowance mean market counts describe observed listings, not every stay in a destination. - A missing price does not mean a property is sold out. Cross-site merging requires both name and location; approximate home pins do not identify an apartment unit. - Airbnb may return only one or two reviews even in fresh sessions. Google place reviews are the public top sample, not a complete newest-review feed. - A flight result is a round-trip from-price with an outbound itinerary. Return flights, baggage and final fare conditions must be selected on the flight site. Date comparisons shift the same trip length by up to three days; they are not a complete 7×7 grid. - Forecasts cover the next sixteen days; otherwise the engine uses the last five completed matching date windows. Archive UV and historical sea-temperature normals are not available in this implementation. - Public weekly hours may differ on public holidays. Reconfirm before departure. - Official entry fees are extracted only when quoted prices, party counts and arithmetic can be verified. Missing prices remain check. - The local free-test environment cannot run Chrome. Production PDF and Booking browser behavior need cloud verification before release. ### FAQ **Is this just a chatbot answer?** No. Every stay, price, place and opening time comes from live public listings fetched during your run; the AI only chooses among checked options and writes the reasons, and every quote it shows is verified word for word. **Does it book anything?** No. It gives you the plan and booking links; you book on the site. **Are the prices final?** They are the prices shown for your dates and party at the time of the run. Taxes and fees can apply, and prices change: check before paying. **What if it cannot make a good plan?** Then you are not charged for the plan. The run says what went wrong. AI usage already spent is billed by Apify at cost. **Can I use my agency's branding?** Yes: add your agency name, logo URL and contact line. **Which AI does it use?** The newest Claude models through Apify's OpenRouter gateway, at cost on your Apify account. You can choose another model in Advanced. **Can it plan a party weekend or an adventure trip?** Yes: choose Nightlife for bars, clubs and live music after dinner, or Adrenaline for an adventure operator on calm mornings, booked ahead. **Does it include car hire?** Yes. With Getting around set to Car, it prices car hire for your dates at the main airport and puts the cheapest car that fits your party and bags into the budget, with the deposit and excess shown. ### Related Actors from Zaiq - [google-hotels-scraper](https://apify.com/zaiq/google-hotels-scraper): standalone hotel search and offers - [airbnb-scraper](https://apify.com/zaiq/airbnb-scraper): standalone rental listings and reviews - [booking-scraper](https://apify.com/zaiq/booking-scraper): standalone accommodation search ### Support Questions, a site that changed, or a field you need? Open an issue on this Actor's **Issues** tab: we answer there, usually within a day. *** Also found as: AI trip planner, holiday planner, vacation planner, travel itinerary generator, itinerary planner, family holiday planner, hotel and Airbnb comparison, travel agent tool, nightlife planner, adventure trip planner, honeymoon planner. # Actor input Schema ## `destination` (type: `string`): City or region with its country, for example Cape Town, South Africa. ## `checkIn` (type: `string`): First night of the stay. Leave empty for 30 days from today. ## `checkOut` (type: `string`): Day you check out (1 to 14 nights). Leave empty for five nights. ## `planLevel` (type: `string`): Full: every source, the deepest review reading, an editor's check. Express: a faster plan from fewer stays. ## `adults` (type: `integer`): Everyone 18 or older. ## `childrenAges` (type: `array`): One age per child, for example \[7, 10]. Prices and stays are checked for the whole party. ## `budget` (type: `number`): For the whole party: stay, food, activities and local transport (flights are shown separately). ## `currency` (type: `string`): Three-letter code, for example ZAR, EUR, USD or GBP. ## `stayBudget` (type: `number`): Optional. Otherwise 55% of the total budget is set aside for the stay. ## `tripStyles` (type: `array`): The kind of holiday: it changes what is searched, how each day runs and which stays are favoured. Nightlife (a jol) adds bars and clubs after dinner; adrenaline adds an adventure activity on calm days. ## `interests` (type: `array`): For example beaches, food, nature, family fun, culture, nightlife. ## `pace` (type: `string`): Relaxed leaves time to rest; busy fits more in. ## `mustSees` (type: `array`): Places that must be in the plan, for example Table Mountain. ## `avoid` (type: `array`): Anything to keep out, for example long hikes or nightclubs. ## `brief` (type: `string`): Optional, in your own words: 'we love seafood, the kids get car sick, no early starts'. The fields above win if they disagree. ## `mustHaves` (type: `array`): For example pool, parking, kitchen, backup power. Only stays that list it qualify. ## `dietary` (type: `array`): Every meal stop must suit these. ## `wheelchair` (type: `boolean`): Step-free stays and stops only, no hikes. ## `pets` (type: `boolean`): Only stays that allow pets. ## `minBedrooms` (type: `integer`): Leave 0 for no minimum. ## `minBeds` (type: `integer`): Leave 0 for no minimum. ## `rooms` (type: `integer`): Rooms to price at hotels. ## `origin` (type: `string`): City or airport, for flight prices. ## `includeFlights` (type: `boolean`): Compare flight prices from your city for these dates and nearby dates. ## `transport` (type: `string`): Car or taxi use driving times; walking uses walking estimates. ## `pickUpPlace` (type: `string`): airport (the main airport), city, or an airport code such as CPT. ## `driverAge` (type: `integer`): Car hire prices and rules depend on it. ## `luggage` (type: `integer`): Suitcases to fit in the hire car; leave empty if unsure. ## `arrivalTime` (type: `string`): Local time you can start on the first day, HH:MM. ## `departureTime` (type: `string`): Local time the last day must end, HH:MM. ## `maxDriveMinutes` (type: `integer`): Optional. Default 60 relaxed, 100 otherwise. ## `brandName` (type: `string`): Optional: shown at the top of the trip page and PDF. ## `brandLogoUrl` (type: `string`): Optional public https link to your logo. ## `brandContact` (type: `string`): Optional: shown on the trip page. ## `language` (type: `string`): Language of the written reasons and notes. ## `carPerDay` (type: `number`): Optional, added to the budget as an estimate. ## `foodPerPersonPerMeal` (type: `number`): Optional fallback where a restaurant shows no price. ## `interestWeights` (type: `object`): Optional, for example {"beaches": 2, "food": 1}. ## `aiModel` (type: `string`): Optional OpenRouter model ID to use for every AI step instead of the defaults. ## Actor input object example ```json { "destination": "Cape Town, South Africa", "planLevel": "full", "adults": 2, "childrenAges": [ 7, 10 ], "budget": 40000, "currency": "ZAR", "tripStyles": [ "family", "beach" ], "interests": [ "beaches", "food", "nature", "family fun" ], "pace": "relaxed", "mustSees": [], "avoid": [], "mustHaves": [], "wheelchair": false, "pets": false, "minBedrooms": 2, "minBeds": 3, "rooms": 1, "includeFlights": false, "transport": "car", "pickUpPlace": "airport", "driverAge": 30, "arrivalTime": "14:00", "departureTime": "12:00", "language": "English" } ``` # Actor output Schema ## `results` (type: `string`): Dataset: the results. ## `summary` (type: `string`): What each input returned, and notes. # 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 = { "destination": "Cape Town, South Africa", "adults": 2, "childrenAges": [ 7, 10 ], "budget": 40000, "currency": "ZAR", "tripStyles": [ "family", "beach" ], "interests": [ "beaches", "food", "nature", "family fun" ], "minBedrooms": 2, "minBeds": 3 }; // Run the Actor and wait for it to finish const run = await client.actor("zaiq/holiday-planner").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 = { "destination": "Cape Town, South Africa", "adults": 2, "childrenAges": [ 7, 10, ], "budget": 40000, "currency": "ZAR", "tripStyles": [ "family", "beach", ], "interests": [ "beaches", "food", "nature", "family fun", ], "minBedrooms": 2, "minBeds": 3, } # Run the Actor and wait for it to finish run = client.actor("zaiq/holiday-planner").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 '{ "destination": "Cape Town, South Africa", "adults": 2, "childrenAges": [ 7, 10 ], "budget": 40000, "currency": "ZAR", "tripStyles": [ "family", "beach" ], "interests": [ "beaches", "food", "nature", "family fun" ], "minBedrooms": 2, "minBeds": 3 }' | apify call zaiq/holiday-planner --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,zaiq/holiday-planner" } } } ``` 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/KvZtkig0Ni7n8I0hl/builds/argbeHIV2SWOnvdbH/openapi.json