# Booking Hotel Finder & Scraper: AI best-value shortlist (`rich_minds/booking-hotel-finder-ai`) Actor

First 10 hotels free. Booking hotel finder: runs the Booking Scraper, drops sold-out and over-budget hotels free, ranks a hotel shortlist by value per night with AI brief match and hotel price drop alerts. Pay per result, per qualified hotel. Free demo on any plan; live search on your Apify account.

- **URL**: https://apify.com/rich\_minds/booking-hotel-finder-ai.md
- **Developed by:** [Rich Minds](https://apify.com/rich_minds) (community)
- **Categories:** Travel, Automation, AI
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 qualified hotel (rules only)s

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?

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

## Booking Hotel Finder & Scraper: AI best-value shortlist

**The best-value Booking.com hotels for your dates, budget and brief — ranked and explained.**

⚡ First **10 hotels free** · 💵 **$0.004** per qualified hotel · 🤖 **$0.01** with AI assessment · 🔑 **No API key needed** — the AI uses the model access of your Apify plan, or your own key · ⏱️ free demo in 3 s

![Ranked Booking.com shortlist — price per night, rating, value score, free cancellation, distance and why each hotel made it](https://api.apify.com/v2/key-value-stores/0E9Je47vjbntgL8FA/records/shortlist.svg)

> **Try it in 30 seconds.** Click **Try it** — the form is already filled with a free demo on six sample Lisbon hotels.
> Type your destination and press Start to search Booking.com live (a Store Actor on your Apify plan); your first
> **10 qualified hotels** are free.
> → [What a run costs](#-pricing--what-a-run-really-costs) · [What the AI adds](#-what-the-ai-tier-adds) · [Run it weekly](#-run-it-weekly)

### ⚡ At a glance

| | |
|---|---|
| **What you get** | a ranked hotel shortlist: price per night, value score with reasons, free cancellation, amenities, fine-print risks, a why-this-hotel line |
| **You provide** | a destination and dates — optionally a budget, must-have amenities and a one-line traveller brief |
| **Output** | JSON / CSV / Excel dataset, best value first, plus `DIGEST` and `OUTPUT` |
| **Typical run** | up to 100 properties scraped → your `maxQualified` (25) best-value hotels |
| **Cost of that run** | $0.50 Booking Scraper on your account + 25 × $0.004 here = **$0.60** — **$0.40** with the $0.003 scraper |
| **Free tier** | first 10 qualified hotels per account |
| **Keys / setup** | none — the AI uses Apify's model access; plans without it set `llmProvider: byok` |
| **Works with** | Schedules, e-mail, Slack, webhooks, Google Sheets, Make / n8n / Zapier, MCP & AI agents |

### 🎯 What this Actor does

This booking hotel finder runs a **Booking scraper** on your account (full listings, or a cheaper one), drops junk for
free and hands you a shortlist you can send to a client:

- **Price per night you can compare** — Booking's stay price ÷ nights, next to rating and reviews.
- **Verified facts** — amenities from Booking's facility list, free cancellation and breakfast from the room options.
- **Fine print before it bites** — city tax, resort fee, deposit, cash only, late check-in fees, quoted verbatim.
- **Price-drop alerts** — scheduled runs deliver only new hotels or cheaper rates, even with relative dates.

#### 🏷️ Best value hotels: the value score

`valueScore` (0–100) weighs guest rating shrunk by review count (35 %), price per night against this search (30 %),
Booking's *Value for money / Location / Cleanliness* (15 %), your amenities (10 %), free cancellation (5 %) and distance
to `nearPoint` (5 %). `valueReasons` says why; `rank` and `valueTier` sort the sheet; `minScore` is the bar.

#### 📋 A hotel shortlist your client can read

`whyThisHotel` is one line per hotel, `pros` / `cons` come from Booking's review summary, and `shortlistMemo: true`
writes a top-5 comparison into `SHORTLIST_MEMO`. Every run also writes **`REPORT`** — a client-ready page (photo,
price per night, rating, why this hotel, fine print, Booking link) whose link, `OUTPUT.reportUrl`, you forward.

#### 🔔 Hotel price drop alert and hotel price tracker

Each delivered stay and its price is remembered (hotel + nights + `adults` when the dates are relative, `30 days`). With
`onlyNewOrPriceDrop` a scheduled run delivers only new hotels or drops of `minPriceDropPct` % or more, with
`previousPrice`, `priceChangePct` and a Slack-ready line: `↓12 % Hotel X, $143/night, 8.7 Excellent`.

#### 🧾 Filters that cost nothing

`minRating`, `minReviews`, `minStars`, `propertyTypes`, `maxPricePerNight`, `mustHaveAmenities`,
`freeCancellationOnly`, `breakfastIncludedOnly`, `maxDistanceKm`, sold-out rooms, missing prices and duplicates.

### 🚀 How to use it

1. **Click `Try it`** — the form is pre-filled with the free demo on sample Lisbon hotels; it works as is.
2. **Type your `destination`, `checkIn` and `checkOut`** — the run switches to the live search by itself, capped by
   `maxDiscoveryChargeUsd`. Pick the Booking scraper in `discoveryActorId`, add a `travellerBrief`, keep `enableAi` on.
3. **Press Start** — the `Shortlist` view is ranked best value first.
4. **Schedule it daily or weekly** with your address in `notifyEmail` — only new hotels and price drops are charged.

![Client sheet — pros, cons, fine-print risks with quotes and the amenities each hotel really has](https://api.apify.com/v2/key-value-stores/0E9Je47vjbntgL8FA/records/client-sheet.svg)

📚 **Learn more:** [Step-by-step tutorial — find the best-value Booking.com hotels with this Actor](https://api.apify.com/v2/key-value-stores/0E9Je47vjbntgL8FA/records/tutorial.html)

### 🆚 Why this instead of a Booking Scraper?

| | [Booking Scraper (`voyager/booking-scraper`)](https://apify.com/voyager/booking-scraper) | [`ryanclinton/booking-scraper`](https://apify.com/ryanclinton/booking-scraper) | [`lentic_clockss/booking-hotels-scraper`](https://apify.com/lentic_clockss/booking-hotels-scraper) | **Booking Hotel Finder** |
|---|---|---|---|---|
| **Price** | $0.005 per property · 828 users / 30 days | $0.006 per record + $0.02 per query | $0.002 per row + $0.005 start | $0.004 per qualified hotel, 10 free |
| **What you pay for** | every row, incl. sold-out | every record | every row | only hotels that pass your filters |
| **Same 100 hotels, all in** | $0.50: 100 unsorted rows to read | $0.62: 100 records, no brief | $0.21: 100 unsorted rows | the 25 best, ranked and explained: **$0.10 here** + the scraper run on your account; junk costs $0 |
| **Ranking** | search order | value queue | search order | per night, reasons, your brief |
| **Repeat runs** | the same hotels again | watchlist deltas | the same hotels again | only new hotels or price drops |

<details><summary>Other Booking and hotel-price Actors compared</summary>

| Actor | Price | Users / 30 d | Drawback | What we add |
|---|---|---|---|---|
| `santamaria-automations/booking-com-scraper` | $0.003 | 247 | charges every row | selectable as our source — filters, value rank, memory |
| `voyager/fast-booking-scraper` | $0.002 | 36 | search page only | selectable as our source — ranked, explained |
| `buseta/trivago-scraper` | $0.01 per hotel + AI events | 1 | per-hotel AI calls billed extra | brief match included in $0.01 |
| `solidcode/booking-scraper` | $0.0015 + $0.01 start | 35 | start fee | no start fee |
| `noraview/Booking-price-scraper` | $0.005 + start | 32 | 13 % of runs fail | partial runs still delivered |
| `zerobreak/google-hotels-scraper` | $0.00499 | 511 | 56 % of runs fail | a steady source |

</details>

#### 💸 Cheaper than a rate-shopper seat

**Lighthouse (formerly OTA Insight) Rate Insight** (~$250/month) and **RateGain Rate Shopper** (~$200/month) are per
property (indicative). A daily watch
here — 100 properties, ~5 new or cheaper a day with AI — is ≈ $0.50 source + 5 × ($0.01 + ≈ $0.003 tokens) =
**$0.57 a day, ≈ $17/month**, no seat.

### 💵 Pricing — what a run really costs

Pay per result: **one event per qualified hotel, nothing else.** No start fee.

| Event | When it is charged | Price |
|---|---|---|
| `free-tier` | your first 10 qualified hotels, in any mode | **$0.00** |
| `qualified-hotel-basic` | AI off — value score, room facts, Booking's pros/cons, regex fine print | **$0.004** |
| `qualified-hotel-ai` | AI on — plus brief match with evidence, why-this-hotel, AI pros/cons and flags | **$0.01** |

**Never charged:** hotels below `minScore` or failing a filter, duplicates, your exclude list, unchanged hotels from
an earlier run. The source run is billed by the Booking scraper on your account.

**How that compares** — $0.004 is the median row price of the Booking scrapers and of the Store search next to this
card (one Actor per publisher) — the same price per unit, but one qualified hotel replaces 4 raw rows you would read and
discard: $0.001 per raw-row equivalent. Junk costs nothing.

**Worked example** — 100 properties scraped = $0.50 on your account → 25 qualify → 10 free + 15 × $0.004 = $0.06 on
your first run. Next run with
AI on: 25 × $0.01 + 25 × ≈ $0.003 tokens = $0.33 here + $0.50 source = **$0.83, $0.033 per hotel** (AI off: $0.10 +
$0.50 = $0.60). With the $0.003 scraper the source is $0.30: **$0.63** all in (AI on), **$0.40** (AI off).

**AI tier, all in:** ≈ **$0.013 per hotel** ($0.01 + ≈ $0.003 tokens at ~1,600 in / 300 out with
`anthropic/claude-haiku-4.5` through Apify's model access) — 2.5× the basic event; with your own key the tokens go to it.

### 🤖 What the AI tier adds

The same demo hotel, AI **off** — facts, value score, Booking's own pros/cons and a keyword brief match:

```json
{"name": "Baixa Garden Suites", "pricePerNight": 149.0, "rating": 8.9, "valueScore": 68, "briefMatchScore": 100,
 "whyThisHotel": "Rated 8.9 Fabulous from 640 reviews; $149/night, cheaper than 50% of this search; Value for money 8.6, Location 9.6, Cleanliness 9.1.",
 "briefMatched": [{"requirement": "pool", "evidence": "Rooftop pool"},
                  {"requirement": "free cancellation", "evidence": "free cancellation on a room option"}],
 "cons": ["Early check-in cut-off"]}
```

AI **on** — judged against *"Quiet hotel for a couple, walkable to the old town, with a pool and free cancellation"*:

```json
{"name": "Baixa Garden Suites", "pricePerNight": 149.0, "rating": 8.9, "valueScore": 70, "briefMatchScore": 75,
 "briefMatched": [{"requirement": "walkable to the old town", "evidence": "300 metres from Rossio Square."},
                  {"requirement": "pool", "evidence": "shared rooftop pool"}],
 "briefUnmet": [{"requirement": "quiet hotel for a couple", "evidence": null}],
 "whyThisHotel": "Only $149/night, 0.14 km from Rossio Square, rooftop pool and free cancellation – a central stay for couples.",
 "finePrintFlags": [{"type": "late_checkin_fee", "quote": "late check-in carries an extra charge of EUR 30."},
                    {"type": "payment_restriction", "quote": "This property only accepts cash for the city tax."}]}
```

Local demo runs, 2026-09-26 (AI: `groq:openai/gpt-oss-120b`; the platform uses `anthropic/claude-haiku-4.5`). The AI
proves "walkable" with a quote, marks "quiet" unproven and flags the cash-only city tax — reading you skip.

### ⚙️ Input

| Field | Type | Default | What it does |
|---|---|---|---|
| `destination` | string | — | City, district or hotel name as on Booking.com (or `startUrls`); typed next to the demo, it searches live |
| `sourceMode` | `actor` | `dataset` | `list` | `actor` | Live Booking search, a Booking dataset, or pasted records. `{}` runs the free demo, nothing charged |
| `discoveryActorId` | select | `voyager/booking-scraper` | The Booking scraper: full details $0.005, or $0.003 / $0.002 per property for the search-page row |
| `checkIn` / `checkOut` | string | `30 days` / `32 days` | `YYYY-MM-DD` or relative days |
| `travellerBrief` | string | — | What the AI scores each hotel against |
| `minScore` | 0–100 | `40` | The field that decides what you pay: below this value score = not charged |
| `enableAi` | boolean | `true` | Brief match, why-this-hotel, pros/cons, fine print |
| `mustHaveAmenities` | string\[] | — | Hard requirement, matched with synonyms |
| `maxQualified` | integer | `25` | Hotels on the shortlist — the ceiling of what this Actor charges |
| `maxDiscoveryChargeUsd` | number | `0.5` | Caps the Booking scraper run, in the form and the API |

Budget, guests, `minRating`, `onlyNewOrPriceDrop`, webhooks and the advanced options are in the **Input** tab.

<details><summary>All flags (<code>targetFlags</code>; an unknown name stops the run with the list)</summary>

| Flag (`targetFlags` value) | Meaning |
|---|---|
| `free_cancellation` | a room option with free cancellation |
| `breakfast_included` | a room option with breakfast included |
| `genius_discount` | a Booking Genius discount on a room option |
| `few_rooms_left` | 3 rooms or fewer left for your dates |
| `top_rated` | guest rating 9.0 or higher |
| `great_value_for_money` | guests rate "Value for money" 8.5 or higher |
| `budget_friendly` | price per night in the cheapest third of this search |
| `all_amenities` | every amenity in `mustHaveAmenities` is listed |
| `near_point` | within 1 km of your `nearPoint` |
| `price_drop` | cheaper than when this stay was last delivered |
| `extra_fees` | the fine print names a city tax, resort fee or cleaning fee |
| `deposit_required` | the fine print asks for a deposit or pre-authorisation |

</details>

### 📤 Output

One dataset item per qualified hotel — JSON, CSV or Excel, or a webhook.

<details><summary>A demo row, shortened (JSON)</summary>

```json
{
  "hotelId": "demo-1002", "itemId": "409351971846", "name": "Hotel Miradouro da Graça",
  "url": "https://www.booking.com/hotel/pt/miradouro-da-graca-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
  "rating": 8.6, "reviewsCount": 2410, "distanceKm": 0.79, "nights": 2, "totalPrice": 248.0, "pricePerNight": 124.0,
  "currency": "USD", "freeCancellation": true, "breakfastIncluded": true, "roomsLeft": 5,
  "valueScore": 72, "rank": 1, "valueTier": "top_pick", "changeType": "price_drop", "previousPrice": 272,
  "priceChangePct": -8.8, "firstSeenAt": "2026-09-19T07:02:11+00:00",
  "finePrintFlags": [{"type": "deposit", "quote": "A damage deposit of EUR 100 is required on arrival and refunded at check-out."}],
  "chargedEvent": "demo", "dedupeKey": "hotel:demo-1002|2026-10-26|2026-10-28|2"
}
```

</details>

The demo's price memory is a sample (`sampleMemory`); real runs fill it from your earlier runs.

#### Output fields

<details><summary>Every field of a row</summary>

| Field | Description |
|---|---|
| `hotelId`, `itemId`, `name`, `url` | Booking hotel id, stable row id, name, the Booking link for your stay |
| `propertyType`, `stars`, `rating`, `ratingLabel`, `reviewsCount`, `categoryScores` | Listing quality from Booking |
| `address`, `city`, `country`, `lat`, `lng`, `distanceKm` | Location; `distanceKm` to your `nearPoint` |
| `checkInDate`, `checkOutDate`, `nights`, `totalPrice`, `pricePerNight`, `currency` | The stay and its price (ISO currency) |
| `priceComparisonPct` | Cheaper per night than this % of the other hotels in your search |
| `lowestRoom`, `freeCancellation`, `breakfastIncluded`, `roomsLeft`, `geniusDiscount`, `checkInTime`, `checkOutTime` | Room facts from the room options |
| `amenitiesMatched`, `amenitiesMissing`, `amenitiesExtraCharge` | Your must-haves against Booking's facility list (`amenitiesMissing` on a listing without facility data = not listed) |
| `valueScore`, `valueReasons`, `ruleScore`, `rank`, `valueTier` | The ranking; `score` = same value as `valueScore`, kept for integrations that sort on `score` |
| `changeType`, `previousPrice`, `priceChangePct`, `firstSeenAt` | Price-drop memory for the same stay |
| `briefMatchScore`, `briefMatched`, `briefUnmet`, `whyThisHotel`, `pros`, `cons`, `finePrintFlags` | Brief match and explanation — AI off, `briefMatchScore` is the share of your brief the listing names |
| `flags`, `targetFlagsMatched`, `image`, `searchQuery` | Flags, your target flags, photo, the search that found it |
| `aiStatus`, `aiModel`, `sourceActor`, `chargedEvent`, `billedAs`, `dedupeKey`, `scrapedAt` | Provenance and billing (`billedAs` = the price tier, also on free rows) |

</details>

**Upsert key for a CRM or Sheet:** `dedupeKey` — Booking hotel id + check-in + check-out + adults (hotel + nights +
adults with relative dates), the key the price memory uses; `itemId` is its short hash, `hotelId` the property.

Views: `Shortlist`, `Price drops` and `Client sheet (brief, pros, cons, fine print)`. The **`DIGEST`** record (top 10,
"vs last run: qualified 41 → 55") and `OUTPUT` (funnel, skips per reason, `topPicks`, `aiCoverage`, `timing`) sit next
to the dataset.

⭐ **Found it useful? A review on the Store helps others find it** — it takes a minute on the Actor's page.

### 🔁 Run it weekly

1. **Actions → Schedule** (daily for price-drop alerts) with your address in `notifyEmail` — each run with new hotels
   or drops e-mails you the digest and the trend vs the last run. Relative dates (`30 days`) keep working.
2. Keep `dedupeAcrossRuns` and `onlyNewOrPriceDrop` on — you are charged **only for what is new or cheaper**; the
   memory is kept per `travellerBrief`, so clients never mix.
3. Add `slackWebhookUrl` for a channel, or `webhookUrl` for your sheet — the
   [n8n workflow and Google Sheets template](docs/marketing/kit/integrations.md) import in one click.

Weekly cost is the new hotels only: 100 properties, ~10 new or cheaper a week, AI on ≈ $0.50 source + 10 × $0.013 all
in = **$0.63**.

#### 🎯 Try it for your niche

Ready-made inputs — paste one into the **JSON** tab of the input form, or save it as a Task:

| Niche | What it looks for | Input |
|---|---|---|
| Travel agent | family hotels with pool and parking under a budget | [preset-travel-agent.json](docs/img/preset-travel-agent.json) |
| Event planner | hotels within 2 km of the venue, rating ≥ 8 | [preset-event-planner.json](docs/img/preset-event-planner.json) |
| Deal hunter | daily hotel price drop alert ≥ 10 % on one stay | [preset-price-drop-alert.json](docs/img/preset-price-drop-alert.json) |

### 🔌 Integrations, automation and API

- **E-mail / Slack** — `notifyEmail` and `slackWebhookUrl` deliver the `DIGEST` after every run with new hotels.
- **Webhook** (Zapier, Make, n8n) — `webhookUrl` POSTs `{"event": "hotel.qualified", "hotel": {…}, "runId": "…"}` per
  hotel, or `{"event": "hotels.qualified", "hotels": [{…}], "runId": "…"}` per `webhookBatchSize` batch; a 429 / 5xx is
  retried once, a failed POST is counted in `OUTPUT.webhook.failed` and never fails the run.
- **Google Sheets** — one click from the **Integrations** tab.
- **Hotel search API for apps and AI agents / MCP** — every input is a plain typed field. **First call = the free
  trial:** `"sourceMode": "list"` ranks the Booking records you send, no source run.

```python
from apify_client import ApifyClient

client = ApifyClient("<YOUR_API_TOKEN>")
run = client.actor("rich_minds/booking-hotel-finder-ai").call(
    run_input={
        "sourceMode": "list",  # free trial; "actor" + "destination" + dates searches Booking.com live
        "itemsList": [{"name": "Hotel Example", "url": "https://www.booking.com/hotel/pt/example.html", "price": 300,
                       "checkInDate": "2026-10-26", "checkOutDate": "2026-10-28", "rating": 8.8, "reviews": 950}],
        "travellerBrief": "Quiet couple trip with a pool",
        "maxDiscoveryChargeUsd": 0.5,  # spend cap once you switch to "sourceMode": "actor"
    },
    timeout_secs=1800,  # a live search with AI — see "How long does a run take?"
    # build="0.1",  # pin the build your pipeline was tested with (Changelog below)
)
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["rank"], item["name"], item["pricePerNight"], item["whyThisHotel"])
```

<details><summary>JavaScript</summary>

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

const client = new ApifyClient({ token: '<YOUR_API_TOKEN>' });
const run = await client.actor('rich_minds/booking-hotel-finder-ai').call({
    sourceMode: 'list', // free trial; 'actor' + destination + dates searches Booking.com live
    itemsList: [{ name: 'Hotel Example', url: 'https://www.booking.com/hotel/pt/example.html', price: 300,
        checkInDate: '2026-10-26', checkOutDate: '2026-10-28', rating: 8.8, reviews: 950 }],
    maxDiscoveryChargeUsd: 0.5, // spend cap once you switch to sourceMode: 'actor'
}, { timeout: 1800 /* , build: '0.1' — pin the tested build */ });
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items.map((i) => [i.rank, i.name, i.pricePerNight]));
```

</details>

#### 🤖 Hotel search tool for AI agents (MCP)

```json
{"mcpServers": {"apify": {"url": "https://mcp.apify.com/?actors=rich_minds/booking-hotel-finder-ai"}}}
```

Minimal agent input — every other field has a default: `destination`, `checkIn`, `checkOut`, `travellerBrief`,
`maxQualified`, `maxDiscoveryChargeUsd`. Ask: *"Search Lisbon for 2 nights, `maxDiscoveryChargeUsd: 0.5`; give me the
5 best-value hotels."*

#### Run outcomes — what your integration sees

<details><summary>Every outcome: run status, dataset, <code>OUTPUT</code> field, charged?, what to do</summary>

| Outcome | Run status | Dataset | `OUTPUT` | Charged? | What to do |
|---|---|---|---|---|---|
| Free demo (the pre-filled sample) | SUCCEEDED | sample hotels | `demo: true` | no | type your destination and dates |
| Destination typed next to the demo | SUCCEEDED | qualified hotels | `switchedToLive` | per qualified hotel | — |
| Success | SUCCEEDED | qualified hotels, best first | funnel, `topPicks`, `aiCoverage` | per qualified hotel | — |
| Nothing matched (the demo too) | SUCCEEDED | empty | `qualified: 0`, skip counts | no | loosen `minScore` / filters |
| Source run timed out with rows | SUCCEEDED | the hotels it scraped | `sourceRunStatus` | per qualified hotel | raise `maxDiscoveryChargeUsd` or narrow the search |
| Demo brief kept with your destination | SUCCEEDED | hotels, rule-ranked | `demoTextsDropped` | per qualified hotel | write your own `travellerBrief` |
| Invalid input | FAILED | empty | — | no | fix the field the status message names |
| Source failed | FAILED | empty | `sourceError`, `sourceErrorKind` | no | follow the reason (plan, timeout, dataset mode) |
| AI unavailable | SUCCEEDED | rule-scored hotels | `aiError`, `freeAiReserve` | free while your free hotels last (a few are kept for the AI), then basic price | `llmProvider: byok` with your own key |

</details>

### 👥 Who is it for?

| You are… | You run it to… | Start with |
|---|---|---|
| Travel agent / concierge | send a client the 10 best-value hotels with free cancellation, parking and a pool | dates, `travellerBrief`, `mustHaveAmenities` |
| Corporate-travel or event planner | hotels within 2 km of the venue under a nightly cap, fine print flagged | `nearPoint`, `maxDistanceKm`, `maxPricePerNight` |
| Trip-planning app or AI agent | ranked hotels as JSON from destination, dates and a brief | the API / MCP call above |
| Deal hunter / travel creator | a morning alert when a hotel on your stay drops ≥ 10 % | `minPriceDropPct`, `notifyEmail`, a daily schedule |

### 🧠 How the AI works

- **Grounded.** One hotel per call; evidence and fine-print quotes must be exact substrings of the listing or they are
  dropped, and an invented number in `whyThisHotel` brings back the rule line.
- **Your brief.** `briefMatchScore` scores the hotel against `travellerBrief`; `valueScore` = 70 % rule + 30 % brief.
- **Tokens where they matter.** The best rule-scored candidates first, every one at or above `minScore` − 15, up to
  `aiCandidateMultiplier` × `maxQualified`.
- **No keys.** Default `anthropic/claude-haiku-4.5` via Apify's model access; `llmProvider: "byok"` for your own key.
- **Fallback.** If the model fails, hotels keep the rule tier (keyword brief match, Booking's pros/cons, regex fine
  print), and the status says how many — free while your free hotels last, then at the basic price, never AI.

### 🔒 Data, compliance and limits

- Public Booking.com listing data only; host and trader contact data is ignored — no personal data.
- Prices change by the minute — confirm on Booking.com. Without dates hotels rank on rating only. The source run is
  capped by `maxDiscoveryChargeUsd` and 600 s; the $0.003 / $0.002 scrapers return no facilities or fine print. Stay
  within Booking.com's terms and GDPR / CCPA.

### ❓ FAQ

**How much will one run cost me?** $0.50 of Booking Scraper for 100 properties ($0.30 with the $0.003 scraper) + 25
hotels × $0.004 (AI off) or ≈ $0.013 all in (AI on) here — first 10 free.

**Is this a Booking scraper or a Booking.com hotel scraper?** It runs one for you — `voyager/booking-scraper`,
`santamaria-automations/booking-com-scraper` or `voyager/fast-booking-scraper` — and adds price per night, value
ranking, verified amenities, fine print, brief match and memory; `sourceMode: dataset` ranks your own scraper runs.

**What will my first real search cost?** Up to 100 properties × $0.005 = $0.50 on your account (the
`maxDiscoveryChargeUsd` cap), and the first 10 qualified hotels here are free — 25 qualified cost 15 × $0.004 = $0.06.

**How long does a run take?** Measured: the demo 2.8 s (AI off), 6.9 s (AI on). A live search takes as long as the
scraper, then the AI. With Apify's model access calls run 8 at a time; with your own key 2 at a time — a free-tier key
took 191 s for 4 hotels. Rate-limit waits stop after 2 min, 30 s if the key answers no call (`OUTPUT.timing`); worst
case with a slow own key ≈ 17 min per 100 hotels, always before the run's timeout. Pass `timeoutSecs` 1800.

**Which Apify plan do I need?** Any plan runs the demo; the live search and built-in AI need a plan that runs Store
Actors — else rank a Booking dataset with `llmProvider: "byok"`.

<details><summary>More questions</summary>

**Is it a Lighthouse Rate Insight alternative?** For comparing hotels on your own dates, yes: Lighthouse and RateGain
start around $200–250/month per property (indicative); a daily watch here is ≈ $17/month. For 365-day rate calendars
per room type a rate shopper does more.

**Can I use it for hotel price comparison across dates?** Every row compares its price with the rest of your search
(`priceComparisonPct`); across dates, run or schedule it once per stay — each stay keeps its own price history.

**What happens if nothing matches my filters?** The run succeeds with 0 rows, charges nothing, and the status names the
filters that dropped the most hotels.

**What does "qualified" mean?** A hotel that passed every free filter and reached `minScore` — only those are charged.

**Will I be charged for the same hotel twice?** Not for the same stay: with `onlyNewOrPriceDrop` on it comes back only
after a price drop of `minPriceDropPct` % or more — relative dates included.

**Is the data public / is this legal?** Public listing data, no login, no personal data; use it within Booking.com's
terms.

**Can I schedule it?** Yes — see [Run it weekly](#-run-it-weekly).

</details>

### 🧩 More Actors from the same developer

- **[Google Reviews Analysis AI](https://apify.com/rich_minds/google-reviews-insights)** — what guests say about a hotel or venue on Google Maps: complaints, praise, reputation
- **[Reddit Brand Monitoring](https://apify.com/rich_minds/reddit-brand-monitoring-ai)** — what travellers say about a hotel, brand or destination on Reddit, with sentiment

### 🆘 Support

Something missing or wrong? Open an issue on the Actor's page or message the developer through the Apify Console —
requests from buyers are shipped first.

### 📝 Changelog

One line per published build, newest first — `/actor-publish` adds it with the commit subject.

- **0.1.4** (2026-09-26) — feat(marketing): 2026-09-26.md — M-01, M-02.

- **0.1.3** (2026-09-26) — fix(review): 2026-09-26-3.md — every finding implemented.

- **Next build** — free tier 10 hotels; `REPORT` page; a demo brief kept next to your destination is ranked without,
  not stopped. `score` (= `valueScore`) is deprecated and removed in 0.2 — sort on `valueScore`.

- **0.1.2** (2026-09-26) — fix(review): 2026-09-26.md — every finding implemented.

- **0.1.1** (2026-09-26) — feat: implement Booking Hotel Finder: AI best-value hotels, pay per result Actor.

- **0.1** (2026-09-26) — initial release.

# Actor input Schema

## `destination` (type: `string`):

City, district or hotel name as on Booking.com, e.g. <code>Lisbon</code>. Typed next to the prefilled demo, it starts the live search for you (capped by <b>Max source spend</b>). The live search runs a Store Actor on your Apify plan — if your plan cannot run Store Actors, rank a Booking dataset with the <i>dataset</i> mode.

## `sourceMode` (type: `string`):

<b>Live search</b> runs the Booking scraper picked below on your account (≈ $0.002–0.005 per property, capped by <b>Max source spend</b>). <b>Dataset</b> ranks an existing Booking scraper run. <b>List</b> ranks records you paste. <code>{}</code> over the API runs the free demo; a destination typed next to the demo searches it live.

## `checkIn` (type: `string`):

<code>YYYY-MM-DD</code> or relative, e.g. <code>30 days</code> from today. Without dates Booking shows no prices and hotels are ranked on rating only. With relative dates a schedule tracks each hotel by hotel + nights + adults, so price drops still show; fixed dates track one exact stay.

## `checkOut` (type: `string`):

<code>YYYY-MM-DD</code> or relative, e.g. <code>32 days</code> (= 2 nights after a <code>30 days</code> check-in). Price per night = Booking's stay price ÷ nights.

## `maxQualified` (type: `integer`):

The best-value hotels are delivered first, up to this many — and the ceiling of what <b>this Actor</b> charges: at most this many × $0.01 with AI on (× $0.004 with AI off), e.g. 25 × $0.01 = $0.25. The source's own spend has its cap right below.

## `maxDiscoveryChargeUsd` (type: `number`):

Hard cap on what the Booking scraper run may charge your account in live mode — $0.50 (≈ 100 properties with the default scraper, ≈ 166 with the $0.003 one) in the form and for an API or agent call that leaves it out. Raise it for bigger searches.

## `notifyEmail` (type: `string`):

After every run with at least one new hotel or price drop, the digest (top 10 with price per night, rating and links) is e-mailed here through Apify's send-mail Actor. Schedule the run daily or weekly (Actions → Schedule) for price-drop alerts. Never sent for the free demo.

## `discoveryActorId` (type: `string`):

Which Store Actor searches Booking.com on your account — most of what a run costs. The default brings the full listing (facilities, fine print, review summary); the $0.003 and $0.002 scrapers bring the search-page row — price, rating, free cancellation, meal plan — at 40–60 % less.

## `travellerBrief` (type: `string`):

Who is travelling and what matters, in plain words. The AI scores every hotel against it with verbatim evidence from the listing and writes a why-this-hotel line. Without AI, the amenities it names are matched against Booking's facility list.

## `minScore` (type: `integer`):

The field that decides what you pay: hotels whose value score (price per night vs rating, reviews, location, cancellation — AI-adjusted with your brief) is below this are dropped and <b>not charged</b>.

## `enableAi` (type: `boolean`):

Scores each hotel against your brief with evidence quotes, writes a why-this-hotel line and pros/cons, and flags fine-print risks (city tax, deposit, cash only). <b>On = $0.01 per qualified hotel + AI tokens; off = $0.004</b> (rule-based value score, Booking's pros/cons, regex fine-print flags).

## `adults` (type: `integer`):

Guests per search. Part of the price and of the stay the price-drop memory tracks.

## `minRating` (type: `number`):

Booking guest rating. Passed to the scraper as its <code>minScore</code> and checked again here. Hotels without a rating yet are dropped while this is above 0.

## `maxPricePerNight` (type: `number`):

In the currency below. Passed to Booking's price filter and checked again on the computed price per night. Empty = no budget cap.

## `mustHaveAmenities` (type: `array`):

Matched against Booking's structured facility list with synonyms (wifi, parking, pool, air conditioning, pets allowed, gym, kitchen, airport shuttle, spa, elevator …). A hotel missing one is dropped free; one at extra charge stays and is named in <code>amenitiesExtraCharge</code>.

## `freeCancellationOnly` (type: `boolean`):

Keep only hotels with at least one room option that can be cancelled for free.

## `breakfastIncludedOnly` (type: `boolean`):

Keep only hotels with a room option whose conditions say breakfast is included.

## `minReviews` (type: `integer`):

Drops properties with too few reviews to trust their rating.

## `minStars` (type: `integer`):

0 = any. Checked on each property (Booking's own star filter takes one exact value only).

## `children` (type: `integer`):

Number of children.

## `rooms` (type: `integer`):

Number of rooms.

## `nearPoint` (type: `string`):

Your venue, beach or old town, e.g. <code>38.7139,-9.1394</code> (right-click a place in Google Maps to copy it). Every hotel gets <code>distanceKm</code> and closer ones score higher.

## `maxDistanceKm` (type: `number`):

Drops hotels farther than this from <b>Near this point</b> (free). Needs that point.

## `propertyTypes` (type: `array`):

Empty = any. One type is passed to Booking's own filter; several are filtered here on each property's type.

## `currency` (type: `string`):

Currency Booking shows prices in (and of <code>maxPricePerNight</code>).

## `language` (type: `string`):

Language of descriptions, facilities and policies.

## `startUrls` (type: `array`):

Booking search result, hotel or shared-list URLs, passed to the scraper as <code>startUrls</code>; typed next to the demo, they start the live search. The live search runs a Store Actor on your Apify plan — if your plan cannot run Store Actors, use the <i>dataset</i> mode.

## `shortlistMemo` (type: `boolean`):

Writes a memo comparing the top 5 into the <code>SHORTLIST\_MEMO</code> record and <code>OUTPUT</code> — one AI call per run with AI on, a markdown table otherwise.

## `onlyNewOrPriceDrop` (type: `boolean`):

Price-drop monitoring: a hotel already delivered for the same stay comes back only when its price fell by at least the percentage below — with <code>previousPrice</code> and <code>priceChangePct</code>. The stay is dates + adults, or hotel + nights + adults when the dates are relative. Off = every run delivers the full shortlist, still marked new / price\_drop / unchanged.

## `minPriceDropPct` (type: `number`):

A remembered hotel counts as a price drop when its stay price fell by at least this much.

## `slackWebhookUrl` (type: `string`):

A Slack incoming-webhook URL (<code>https://hooks.slack.com/services/…</code>). After every run with at least one new hotel or price drop, the digest is posted to that channel as a readable message. Never sent for the free demo.

## `webhookUrl` (type: `string`):

Qualified hotels are POSTed here as JSON with a Slack-ready <code>text</code> line (Zapier, Make, n8n, your app). Stored encrypted, like a key.

## `webhookHeaders` (type: `object`):

Extra HTTP headers for the webhook, e.g. <code>{"Authorization": "Bearer …"}</code>. Stored encrypted — never shown in the run input.

## `webhookBatchSize` (type: `integer`):

1 = one POST per hotel the moment it is ready. Higher = one POST per N hotels.

## `dedupeAcrossRuns` (type: `boolean`):

Keeps every delivered hotel stay and its price in a named key-value store on your account — needed for price-drop alerts. Off = every run starts fresh.

## `dedupeStoreName` (type: `string`):

Key-value store for the cross-run memory. Left at the default, the memory is kept per traveller brief, so two clients never hide hotels from each other. Type your own name to share one memory, or keep one per trip.

## `llmProvider` (type: `string`):

<b>Apify (no keys)</b> — the AI runs through Apify's built-in OpenRouter proxy; tokens are billed to your Apify account at OpenRouter's rates. <b>My own key</b> — use your OpenAI / Anthropic / Gemini / Groq key instead; a free-tier key is slower (2 calls at a time, one after a rate limit).

## `llmModel` (type: `string`):

Leave empty for the default (<code>anthropic/claude-haiku-4.5</code>). Apify mode takes an OpenRouter slug such as <code>openai/gpt-4.1-mini</code>; own-key mode takes <code>provider:model</code>, e.g. <code>anthropic:claude-haiku-4-5-20251001</code>.

## `llmApiKey` (type: `string`):

Required when <b>AI model access</b> is <i>My own API key</i>. Stored encrypted by Apify, never logged.

## `aiCandidateMultiplier` (type: `integer`):

How many of the best rule-scored hotels get the AI pass, as a multiple of <b>Max hotels on the shortlist</b> — best first, every one at or above the minimum value score − 15. Higher = more thorough, more tokens.

## `datasetId` (type: `string`):

Only for <b>dataset</b> mode: a dataset of <code>voyager/booking-scraper</code> (or another Booking scraper with name, url and price / rating). Pick it so the Actor is granted read access.

## `itemsList` (type: `array`):

Only for <b>list</b> mode. JSON array of Booking records (voyager/booking-scraper fields: <code>name</code>, <code>url</code>, <code>price</code>, <code>checkInDate</code>, <code>checkOutDate</code>, <code>rating</code>, <code>reviews</code>, <code>rooms</code>, <code>facilities</code> …). The prefill is the free demo's sample.

## `discoveryInput` (type: `object`):

Merged over the scraper input this Actor builds (e.g. <code>{"flexWindow": "1"}</code>). The live search runs a Store Actor on your Apify plan — if your plan cannot run Store Actors, use the <i>dataset</i> mode.

## `maxToProcess` (type: `integer`):

The scraper's row limit — also cut by <b>Max source spend</b> ÷ the scraper's price per property.

## `targetFlags` (type: `array`):

Only deliver hotels with at least one of these flags, e.g. <code>free\_cancellation</code>, <code>price\_drop</code>, <code>top\_rated</code>, <code>great\_value\_for\_money</code> (<code>freeCancellation</code> works too); an unknown name stops the run at once with the list of valid ones.

## `suppressionList` (type: `array`):

Hotel names, URLs or hotel ids to never output. Skipped before any processing and never charged.

## Actor input object example

```json
{
  "sourceMode": "list",
  "checkIn": "30 days",
  "checkOut": "32 days",
  "maxQualified": 25,
  "maxDiscoveryChargeUsd": 0.5,
  "discoveryActorId": "voyager/booking-scraper",
  "travellerBrief": "Quiet hotel for a couple, walkable to the old town, with a pool and free cancellation",
  "minScore": 40,
  "enableAi": true,
  "adults": 2,
  "minRating": 7.5,
  "freeCancellationOnly": false,
  "breakfastIncludedOnly": false,
  "minReviews": 20,
  "minStars": 0,
  "children": 0,
  "rooms": 1,
  "currency": "USD",
  "language": "en-gb",
  "shortlistMemo": false,
  "onlyNewOrPriceDrop": true,
  "minPriceDropPct": 5,
  "webhookBatchSize": 1,
  "dedupeAcrossRuns": true,
  "dedupeStoreName": "booking-hotel-finder-ai-seen",
  "llmProvider": "apify",
  "aiCandidateMultiplier": 2,
  "itemsList": [
    {
      "hotelId": "demo-1001",
      "name": "Casa do Largo Boutique Hotel",
      "url": "https://www.booking.com/hotel/pt/casa-do-largo-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Hotel",
      "stars": 4,
      "description": "Set in a restored 18th-century townhouse in Alfama, Casa do Largo Boutique Hotel offers a rooftop terrace with an outdoor swimming pool and views over the Tagus. The quiet side street is a 6-minute walk from Lisbon Cathedral.",
      "price": 356,
      "currency": "US$",
      "rating": 9.1,
      "ratingLabel": "Wonderful",
      "reviews": 1284,
      "checkIn": "From 15:00 to 23:00",
      "checkOut": "Until 12:00",
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7112",
        "lng": "-9.1312"
      },
      "address": {
        "full": "Largo do Contador-Mor 7, Alfama, 1100-194 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1001.jpg",
      "rooms": [
        {
          "roomType": "Superior Double Room",
          "available": true,
          "roomsLeft": 2,
          "facilities": [
            "Air conditioning",
            "Free WiFi",
            "Soundproofing"
          ],
          "options": [
            {
              "price": 356,
              "persons": 2,
              "freeCancellation": true,
              "yourChoices": [
                "Breakfast included",
                "Free cancellation before 24 October 2026"
              ],
              "hasGeniusDiscount": true
            }
          ]
        }
      ],
      "facilities": [
        {
          "name": "Pool",
          "facilities": [
            {
              "name": "Outdoor swimming pool",
              "additionalInfo": {
                "requiresAdditionalCharge": false
              }
            }
          ]
        },
        {
          "name": "Internet",
          "facilities": [
            {
              "name": "Free WiFi"
            }
          ]
        },
        {
          "name": "Parking",
          "facilities": [
            {
              "name": "Public parking is possible at a location nearby (reservation is not needed) and costs EUR 18 per day.",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            }
          ]
        },
        {
          "name": "General",
          "facilities": [
            {
              "name": "Non-smoking rooms"
            },
            {
              "name": "Elevator"
            },
            {
              "name": "Soundproof rooms"
            }
          ]
        }
      ],
      "categoryReviews": [
        {
          "title": "Staff",
          "score": 9.6
        },
        {
          "title": "Cleanliness",
          "score": 9.4
        },
        {
          "title": "Location",
          "score": 9.3
        },
        {
          "title": "Value for money",
          "score": 8.8
        },
        {
          "title": "Free WiFi",
          "score": 8.1
        }
      ],
      "reviewSummary": {
        "summary": "Guests love the rooftop pool, the calm street and the breakfast; a few mention the steep walk up from the tram.",
        "pros": [
          {
            "description": "Rooftop pool with river views",
            "numberOfMentions": 212
          },
          {
            "description": "Quiet, spotless rooms",
            "numberOfMentions": 180
          },
          {
            "description": "Generous breakfast",
            "numberOfMentions": 151
          }
        ],
        "cons": [
          {
            "description": "Steep uphill walk from the tram stop",
            "numberOfMentions": 64
          }
        ]
      },
      "finePrint": "A city tax of EUR 4 per person per night is charged at the property for guests aged 13 and older, up to 7 nights.",
      "policies": [
        {
          "title": "Children and beds",
          "content": "Children of any age are welcome."
        },
        {
          "title": "Pets",
          "content": "Pets are not allowed."
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:02.000Z"
    },
    {
      "hotelId": "demo-1002",
      "name": "Hotel Miradouro da Graça",
      "url": "https://www.booking.com/hotel/pt/miradouro-da-graca-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Hotel",
      "stars": 3,
      "description": "Hotel Miradouro da Graça sits next to the Graça viewpoint and tram 28. Rooms are simple and bright; the lounge serves breakfast with a view of the castle.",
      "price": 248,
      "currency": "US$",
      "rating": 8.6,
      "ratingLabel": "Excellent",
      "reviews": 2410,
      "checkIn": "From 14:00",
      "checkOut": "Until 11:00",
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7166",
        "lng": "-9.1310"
      },
      "address": {
        "full": "Rua da Graça 88, 1170-167 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1002.jpg",
      "rooms": [
        {
          "roomType": "Standard Double Room",
          "available": true,
          "roomsLeft": 5,
          "facilities": [
            "Air conditioning",
            "Free WiFi"
          ],
          "options": [
            {
              "price": 248,
              "persons": 2,
              "freeCancellation": false,
              "yourChoices": [
                "Breakfast US$14 (optional)",
                "Non-refundable"
              ]
            },
            {
              "price": 276,
              "persons": 2,
              "freeCancellation": true,
              "yourChoices": [
                "Breakfast included",
                "Free cancellation before 25 October 2026"
              ]
            }
          ]
        }
      ],
      "facilities": [
        {
          "name": "Internet",
          "facilities": [
            {
              "name": "Free WiFi"
            }
          ]
        },
        {
          "name": "Parking",
          "facilities": [
            {
              "name": "Private parking is possible on site (reservation is needed) and costs EUR 20 per day.",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            }
          ]
        },
        {
          "name": "General",
          "facilities": [
            {
              "name": "Air conditioning"
            },
            {
              "name": "24-hour front desk"
            },
            {
              "name": "Elevator"
            }
          ]
        }
      ],
      "categoryReviews": [
        {
          "title": "Staff",
          "score": 9
        },
        {
          "title": "Cleanliness",
          "score": 8.7
        },
        {
          "title": "Location",
          "score": 8.9
        },
        {
          "title": "Value for money",
          "score": 8.9
        },
        {
          "title": "Comfort",
          "score": 8.2
        }
      ],
      "reviewSummary": {
        "summary": "Great value near the tram with a castle view at breakfast; rooms are on the small side.",
        "pros": [
          {
            "description": "Next to tram 28 and the viewpoint",
            "numberOfMentions": 301
          },
          {
            "description": "Great value for Lisbon",
            "numberOfMentions": 188
          }
        ],
        "cons": [
          {
            "description": "Small rooms",
            "numberOfMentions": 97
          },
          {
            "description": "Street noise on weekends",
            "numberOfMentions": 41
          }
        ]
      },
      "finePrint": "A damage deposit of EUR 100 is required on arrival and refunded at check-out. Check-in after 22:00 carries a surcharge of EUR 20.",
      "policies": [
        {
          "title": "Cancellation/ prepayment",
          "content": "Cancellation and prepayment policies vary according to accommodation type."
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:05.000Z",
      "sampleMemory": {
        "price": 272,
        "firstSeenAt": "2026-09-19T07:02:11+00:00",
        "note": "sample memory — the free demo's price drop"
      }
    },
    {
      "hotelId": "demo-1003",
      "name": "Baixa Garden Suites",
      "url": "https://www.booking.com/hotel/pt/baixa-garden-suites-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Apartment",
      "stars": 4,
      "description": "Baixa Garden Suites offers apartments with a kitchenette and a shared rooftop pool, 300 metres from Rossio Square. Each suite has a washing machine.",
      "price": 298,
      "currency": "US$",
      "rating": 8.9,
      "ratingLabel": "Fabulous",
      "reviews": 640,
      "checkIn": "From 16:00 to 20:00",
      "checkOut": "Until 11:00",
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7127",
        "lng": "-9.1388"
      },
      "address": {
        "full": "Rua dos Correeiros 112, Baixa, 1100-167 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1003.jpg",
      "rooms": [
        {
          "roomType": "One-Bedroom Apartment",
          "available": true,
          "roomsLeft": 1,
          "facilities": [
            "Kitchenette",
            "Washing machine",
            "Air conditioning"
          ],
          "options": [
            {
              "price": 298,
              "persons": 2,
              "freeCancellation": true,
              "yourChoices": [
                "Free cancellation before 23 October 2026",
                "No prepayment needed"
              ]
            }
          ]
        }
      ],
      "facilities": [
        {
          "name": "Pool",
          "facilities": [
            {
              "name": "Rooftop pool"
            },
            {
              "name": "Outdoor swimming pool"
            }
          ]
        },
        {
          "name": "Kitchen",
          "facilities": [
            {
              "name": "Kitchenette"
            },
            {
              "name": "Washing machine"
            }
          ]
        },
        {
          "name": "Internet",
          "facilities": [
            {
              "name": "Free WiFi"
            }
          ]
        },
        {
          "name": "Parking",
          "facilities": [
            {
              "name": "Public parking is possible at a location nearby and costs EUR 25 per day.",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            }
          ]
        }
      ],
      "categoryReviews": [
        {
          "title": "Staff",
          "score": 8.8
        },
        {
          "title": "Cleanliness",
          "score": 9.1
        },
        {
          "title": "Location",
          "score": 9.6
        },
        {
          "title": "Value for money",
          "score": 8.6
        }
      ],
      "reviewSummary": {
        "summary": "Central apartments with a pool; check-in closes at 20:00.",
        "pros": [
          {
            "description": "Unbeatable central location",
            "numberOfMentions": 140
          },
          {
            "description": "Kitchenette and washing machine",
            "numberOfMentions": 66
          }
        ],
        "cons": [
          {
            "description": "Early check-in cut-off",
            "numberOfMentions": 38
          }
        ]
      },
      "finePrint": "Guests arriving after 20:00 must contact the property in advance; late check-in carries an extra charge of EUR 30. This property only accepts cash for the city tax.",
      "policies": [
        {
          "title": "Parties",
          "content": "Parties/events are not allowed."
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:07.000Z"
    },
    {
      "hotelId": "demo-1004",
      "name": "Avenida Liberdade Grand",
      "url": "https://www.booking.com/hotel/pt/avenida-liberdade-grand-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Hotel",
      "stars": 5,
      "description": "A five-star hotel on Avenida da Liberdade with an indoor pool, spa and fitness centre. Valet parking is available.",
      "price": 780,
      "currency": "US$",
      "rating": 9,
      "ratingLabel": "Wonderful",
      "reviews": 3120,
      "checkIn": "From 15:00",
      "checkOut": "Until 12:00",
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7201",
        "lng": "-9.1460"
      },
      "address": {
        "full": "Avenida da Liberdade 185, 1250-141 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1004.jpg",
      "rooms": [
        {
          "roomType": "Deluxe King Room",
          "available": true,
          "facilities": [
            "Air conditioning",
            "Free WiFi",
            "Bathtub"
          ],
          "options": [
            {
              "price": 780,
              "persons": 2,
              "freeCancellation": true,
              "yourChoices": [
                "Breakfast included",
                "Free cancellation before 24 October 2026"
              ]
            }
          ]
        }
      ],
      "facilities": [
        {
          "name": "Pool",
          "facilities": [
            {
              "name": "Indoor swimming pool"
            }
          ]
        },
        {
          "name": "Wellness",
          "facilities": [
            {
              "name": "Spa",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            },
            {
              "name": "Fitness centre"
            }
          ]
        },
        {
          "name": "Parking",
          "facilities": [
            {
              "name": "Valet parking",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            }
          ]
        },
        {
          "name": "Internet",
          "facilities": [
            {
              "name": "Free WiFi"
            }
          ]
        }
      ],
      "categoryReviews": [
        {
          "title": "Staff",
          "score": 9.4
        },
        {
          "title": "Cleanliness",
          "score": 9.3
        },
        {
          "title": "Location",
          "score": 9.1
        },
        {
          "title": "Value for money",
          "score": 8
        }
      ],
      "reviewSummary": {
        "summary": "Luxury on the avenue with an excellent spa; pricey for Lisbon.",
        "pros": [
          {
            "description": "Excellent spa and indoor pool",
            "numberOfMentions": 260
          },
          {
            "description": "Attentive staff",
            "numberOfMentions": 233
          }
        ],
        "cons": [
          {
            "description": "Expensive extras",
            "numberOfMentions": 88
          }
        ]
      },
      "finePrint": "A resort fee of EUR 25 per room per night applies. A credit card pre-authorisation is taken at check-in.",
      "policies": [
        {
          "title": "Pets",
          "content": "Pets are allowed on request. Charges may apply."
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:09.000Z"
    },
    {
      "hotelId": "demo-1005",
      "name": "Rossio Budget Hostel",
      "url": "https://www.booking.com/hotel/pt/rossio-budget-hostel-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Hostel",
      "stars": 1,
      "description": "Dorms and private rooms on Rossio Square.",
      "price": 96,
      "currency": "US$",
      "rating": 7.6,
      "ratingLabel": "Good",
      "reviews": 512,
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7141",
        "lng": "-9.1398"
      },
      "address": {
        "full": "Praça Dom Pedro IV 40, 1100-200 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "rooms": [
        {
          "roomType": "Private Double Room",
          "available": true,
          "options": [
            {
              "price": 96,
              "persons": 2,
              "freeCancellation": false,
              "yourChoices": [
                "Non-refundable"
              ]
            }
          ]
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:11.000Z"
    },
    {
      "hotelId": "demo-1006",
      "name": "Tejo Riverside Lofts",
      "url": "https://www.booking.com/hotel/pt/tejo-riverside-lofts-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Apartment",
      "stars": 4,
      "description": "Loft apartments on the riverfront in Cais do Sodré.",
      "currency": "US$",
      "rating": 9.3,
      "ratingLabel": "Superb",
      "reviews": 208,
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7060",
        "lng": "-9.1440"
      },
      "address": {
        "full": "Rua da Ribeira Nova 12, 1200-370 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "rooms": [
        {
          "roomType": "Loft",
          "available": false,
          "options": []
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:13.000Z"
    }
  ],
  "discoveryInput": {},
  "maxToProcess": 100
}
```

# Actor output Schema

## `qualified` (type: `string`):

All qualified hotels as JSON, best-scoring first.

## `sheet` (type: `string`):

The same hotels as a spreadsheet.

## `runSummary` (type: `string`):

JSON record with the funnel (loaded -> filtered -> AI-assessed -> qualified), per-reason skip counts, charged events by type, free-tier hotels used and remaining, whether a budget limit was reached, webhook delivery counts and the dedupe store size.

# 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 = {
    "sourceMode": "list",
    "maxDiscoveryChargeUsd": 0.5,
    "travellerBrief": "Quiet hotel for a couple, walkable to the old town, with a pool and free cancellation",
    "itemsList": [
        {
            "hotelId": "demo-1001",
            "name": "Casa do Largo Boutique Hotel",
            "url": "https://www.booking.com/hotel/pt/casa-do-largo-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Hotel",
            "stars": 4,
            "description": "Set in a restored 18th-century townhouse in Alfama, Casa do Largo Boutique Hotel offers a rooftop terrace with an outdoor swimming pool and views over the Tagus. The quiet side street is a 6-minute walk from Lisbon Cathedral.",
            "price": 356,
            "currency": "US$",
            "rating": 9.1,
            "ratingLabel": "Wonderful",
            "reviews": 1284,
            "checkIn": "From 15:00 to 23:00",
            "checkOut": "Until 12:00",
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7112",
                "lng": "-9.1312"
            },
            "address": {
                "full": "Largo do Contador-Mor 7, Alfama, 1100-194 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal"
            },
            "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1001.jpg",
            "rooms": [
                {
                    "roomType": "Superior Double Room",
                    "available": true,
                    "roomsLeft": 2,
                    "facilities": [
                        "Air conditioning",
                        "Free WiFi",
                        "Soundproofing"
                    ],
                    "options": [
                        {
                            "price": 356,
                            "persons": 2,
                            "freeCancellation": true,
                            "yourChoices": [
                                "Breakfast included",
                                "Free cancellation before 24 October 2026"
                            ],
                            "hasGeniusDiscount": true
                        }
                    ]
                }
            ],
            "facilities": [
                {
                    "name": "Pool",
                    "facilities": [
                        {
                            "name": "Outdoor swimming pool",
                            "additionalInfo": {
                                "requiresAdditionalCharge": false
                            }
                        }
                    ]
                },
                {
                    "name": "Internet",
                    "facilities": [
                        {
                            "name": "Free WiFi"
                        }
                    ]
                },
                {
                    "name": "Parking",
                    "facilities": [
                        {
                            "name": "Public parking is possible at a location nearby (reservation is not needed) and costs EUR 18 per day.",
                            "additionalInfo": {
                                "requiresAdditionalCharge": true
                            }
                        }
                    ]
                },
                {
                    "name": "General",
                    "facilities": [
                        {
                            "name": "Non-smoking rooms"
                        },
                        {
                            "name": "Elevator"
                        },
                        {
                            "name": "Soundproof rooms"
                        }
                    ]
                }
            ],
            "categoryReviews": [
                {
                    "title": "Staff",
                    "score": 9.6
                },
                {
                    "title": "Cleanliness",
                    "score": 9.4
                },
                {
                    "title": "Location",
                    "score": 9.3
                },
                {
                    "title": "Value for money",
                    "score": 8.8
                },
                {
                    "title": "Free WiFi",
                    "score": 8.1
                }
            ],
            "reviewSummary": {
                "summary": "Guests love the rooftop pool, the calm street and the breakfast; a few mention the steep walk up from the tram.",
                "pros": [
                    {
                        "description": "Rooftop pool with river views",
                        "numberOfMentions": 212
                    },
                    {
                        "description": "Quiet, spotless rooms",
                        "numberOfMentions": 180
                    },
                    {
                        "description": "Generous breakfast",
                        "numberOfMentions": 151
                    }
                ],
                "cons": [
                    {
                        "description": "Steep uphill walk from the tram stop",
                        "numberOfMentions": 64
                    }
                ]
            },
            "finePrint": "A city tax of EUR 4 per person per night is charged at the property for guests aged 13 and older, up to 7 nights.",
            "policies": [
                {
                    "title": "Children and beds",
                    "content": "Children of any age are welcome."
                },
                {
                    "title": "Pets",
                    "content": "Pets are not allowed."
                }
            ],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:02.000Z"
        },
        {
            "hotelId": "demo-1002",
            "name": "Hotel Miradouro da Graça",
            "url": "https://www.booking.com/hotel/pt/miradouro-da-graca-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Hotel",
            "stars": 3,
            "description": "Hotel Miradouro da Graça sits next to the Graça viewpoint and tram 28. Rooms are simple and bright; the lounge serves breakfast with a view of the castle.",
            "price": 248,
            "currency": "US$",
            "rating": 8.6,
            "ratingLabel": "Excellent",
            "reviews": 2410,
            "checkIn": "From 14:00",
            "checkOut": "Until 11:00",
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7166",
                "lng": "-9.1310"
            },
            "address": {
                "full": "Rua da Graça 88, 1170-167 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal"
            },
            "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1002.jpg",
            "rooms": [
                {
                    "roomType": "Standard Double Room",
                    "available": true,
                    "roomsLeft": 5,
                    "facilities": [
                        "Air conditioning",
                        "Free WiFi"
                    ],
                    "options": [
                        {
                            "price": 248,
                            "persons": 2,
                            "freeCancellation": false,
                            "yourChoices": [
                                "Breakfast US$14 (optional)",
                                "Non-refundable"
                            ]
                        },
                        {
                            "price": 276,
                            "persons": 2,
                            "freeCancellation": true,
                            "yourChoices": [
                                "Breakfast included",
                                "Free cancellation before 25 October 2026"
                            ]
                        }
                    ]
                }
            ],
            "facilities": [
                {
                    "name": "Internet",
                    "facilities": [
                        {
                            "name": "Free WiFi"
                        }
                    ]
                },
                {
                    "name": "Parking",
                    "facilities": [
                        {
                            "name": "Private parking is possible on site (reservation is needed) and costs EUR 20 per day.",
                            "additionalInfo": {
                                "requiresAdditionalCharge": true
                            }
                        }
                    ]
                },
                {
                    "name": "General",
                    "facilities": [
                        {
                            "name": "Air conditioning"
                        },
                        {
                            "name": "24-hour front desk"
                        },
                        {
                            "name": "Elevator"
                        }
                    ]
                }
            ],
            "categoryReviews": [
                {
                    "title": "Staff",
                    "score": 9
                },
                {
                    "title": "Cleanliness",
                    "score": 8.7
                },
                {
                    "title": "Location",
                    "score": 8.9
                },
                {
                    "title": "Value for money",
                    "score": 8.9
                },
                {
                    "title": "Comfort",
                    "score": 8.2
                }
            ],
            "reviewSummary": {
                "summary": "Great value near the tram with a castle view at breakfast; rooms are on the small side.",
                "pros": [
                    {
                        "description": "Next to tram 28 and the viewpoint",
                        "numberOfMentions": 301
                    },
                    {
                        "description": "Great value for Lisbon",
                        "numberOfMentions": 188
                    }
                ],
                "cons": [
                    {
                        "description": "Small rooms",
                        "numberOfMentions": 97
                    },
                    {
                        "description": "Street noise on weekends",
                        "numberOfMentions": 41
                    }
                ]
            },
            "finePrint": "A damage deposit of EUR 100 is required on arrival and refunded at check-out. Check-in after 22:00 carries a surcharge of EUR 20.",
            "policies": [
                {
                    "title": "Cancellation/ prepayment",
                    "content": "Cancellation and prepayment policies vary according to accommodation type."
                }
            ],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:05.000Z",
            "sampleMemory": {
                "price": 272,
                "firstSeenAt": "2026-09-19T07:02:11+00:00",
                "note": "sample memory — the free demo's price drop"
            }
        },
        {
            "hotelId": "demo-1003",
            "name": "Baixa Garden Suites",
            "url": "https://www.booking.com/hotel/pt/baixa-garden-suites-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Apartment",
            "stars": 4,
            "description": "Baixa Garden Suites offers apartments with a kitchenette and a shared rooftop pool, 300 metres from Rossio Square. Each suite has a washing machine.",
            "price": 298,
            "currency": "US$",
            "rating": 8.9,
            "ratingLabel": "Fabulous",
            "reviews": 640,
            "checkIn": "From 16:00 to 20:00",
            "checkOut": "Until 11:00",
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7127",
                "lng": "-9.1388"
            },
            "address": {
                "full": "Rua dos Correeiros 112, Baixa, 1100-167 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal"
            },
            "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1003.jpg",
            "rooms": [
                {
                    "roomType": "One-Bedroom Apartment",
                    "available": true,
                    "roomsLeft": 1,
                    "facilities": [
                        "Kitchenette",
                        "Washing machine",
                        "Air conditioning"
                    ],
                    "options": [
                        {
                            "price": 298,
                            "persons": 2,
                            "freeCancellation": true,
                            "yourChoices": [
                                "Free cancellation before 23 October 2026",
                                "No prepayment needed"
                            ]
                        }
                    ]
                }
            ],
            "facilities": [
                {
                    "name": "Pool",
                    "facilities": [
                        {
                            "name": "Rooftop pool"
                        },
                        {
                            "name": "Outdoor swimming pool"
                        }
                    ]
                },
                {
                    "name": "Kitchen",
                    "facilities": [
                        {
                            "name": "Kitchenette"
                        },
                        {
                            "name": "Washing machine"
                        }
                    ]
                },
                {
                    "name": "Internet",
                    "facilities": [
                        {
                            "name": "Free WiFi"
                        }
                    ]
                },
                {
                    "name": "Parking",
                    "facilities": [
                        {
                            "name": "Public parking is possible at a location nearby and costs EUR 25 per day.",
                            "additionalInfo": {
                                "requiresAdditionalCharge": true
                            }
                        }
                    ]
                }
            ],
            "categoryReviews": [
                {
                    "title": "Staff",
                    "score": 8.8
                },
                {
                    "title": "Cleanliness",
                    "score": 9.1
                },
                {
                    "title": "Location",
                    "score": 9.6
                },
                {
                    "title": "Value for money",
                    "score": 8.6
                }
            ],
            "reviewSummary": {
                "summary": "Central apartments with a pool; check-in closes at 20:00.",
                "pros": [
                    {
                        "description": "Unbeatable central location",
                        "numberOfMentions": 140
                    },
                    {
                        "description": "Kitchenette and washing machine",
                        "numberOfMentions": 66
                    }
                ],
                "cons": [
                    {
                        "description": "Early check-in cut-off",
                        "numberOfMentions": 38
                    }
                ]
            },
            "finePrint": "Guests arriving after 20:00 must contact the property in advance; late check-in carries an extra charge of EUR 30. This property only accepts cash for the city tax.",
            "policies": [
                {
                    "title": "Parties",
                    "content": "Parties/events are not allowed."
                }
            ],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:07.000Z"
        },
        {
            "hotelId": "demo-1004",
            "name": "Avenida Liberdade Grand",
            "url": "https://www.booking.com/hotel/pt/avenida-liberdade-grand-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Hotel",
            "stars": 5,
            "description": "A five-star hotel on Avenida da Liberdade with an indoor pool, spa and fitness centre. Valet parking is available.",
            "price": 780,
            "currency": "US$",
            "rating": 9,
            "ratingLabel": "Wonderful",
            "reviews": 3120,
            "checkIn": "From 15:00",
            "checkOut": "Until 12:00",
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7201",
                "lng": "-9.1460"
            },
            "address": {
                "full": "Avenida da Liberdade 185, 1250-141 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal"
            },
            "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1004.jpg",
            "rooms": [
                {
                    "roomType": "Deluxe King Room",
                    "available": true,
                    "facilities": [
                        "Air conditioning",
                        "Free WiFi",
                        "Bathtub"
                    ],
                    "options": [
                        {
                            "price": 780,
                            "persons": 2,
                            "freeCancellation": true,
                            "yourChoices": [
                                "Breakfast included",
                                "Free cancellation before 24 October 2026"
                            ]
                        }
                    ]
                }
            ],
            "facilities": [
                {
                    "name": "Pool",
                    "facilities": [
                        {
                            "name": "Indoor swimming pool"
                        }
                    ]
                },
                {
                    "name": "Wellness",
                    "facilities": [
                        {
                            "name": "Spa",
                            "additionalInfo": {
                                "requiresAdditionalCharge": true
                            }
                        },
                        {
                            "name": "Fitness centre"
                        }
                    ]
                },
                {
                    "name": "Parking",
                    "facilities": [
                        {
                            "name": "Valet parking",
                            "additionalInfo": {
                                "requiresAdditionalCharge": true
                            }
                        }
                    ]
                },
                {
                    "name": "Internet",
                    "facilities": [
                        {
                            "name": "Free WiFi"
                        }
                    ]
                }
            ],
            "categoryReviews": [
                {
                    "title": "Staff",
                    "score": 9.4
                },
                {
                    "title": "Cleanliness",
                    "score": 9.3
                },
                {
                    "title": "Location",
                    "score": 9.1
                },
                {
                    "title": "Value for money",
                    "score": 8
                }
            ],
            "reviewSummary": {
                "summary": "Luxury on the avenue with an excellent spa; pricey for Lisbon.",
                "pros": [
                    {
                        "description": "Excellent spa and indoor pool",
                        "numberOfMentions": 260
                    },
                    {
                        "description": "Attentive staff",
                        "numberOfMentions": 233
                    }
                ],
                "cons": [
                    {
                        "description": "Expensive extras",
                        "numberOfMentions": 88
                    }
                ]
            },
            "finePrint": "A resort fee of EUR 25 per room per night applies. A credit card pre-authorisation is taken at check-in.",
            "policies": [
                {
                    "title": "Pets",
                    "content": "Pets are allowed on request. Charges may apply."
                }
            ],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:09.000Z"
        },
        {
            "hotelId": "demo-1005",
            "name": "Rossio Budget Hostel",
            "url": "https://www.booking.com/hotel/pt/rossio-budget-hostel-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Hostel",
            "stars": 1,
            "description": "Dorms and private rooms on Rossio Square.",
            "price": 96,
            "currency": "US$",
            "rating": 7.6,
            "ratingLabel": "Good",
            "reviews": 512,
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7141",
                "lng": "-9.1398"
            },
            "address": {
                "full": "Praça Dom Pedro IV 40, 1100-200 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal"
            },
            "rooms": [
                {
                    "roomType": "Private Double Room",
                    "available": true,
                    "options": [
                        {
                            "price": 96,
                            "persons": 2,
                            "freeCancellation": false,
                            "yourChoices": [
                                "Non-refundable"
                            ]
                        }
                    ]
                }
            ],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:11.000Z"
        },
        {
            "hotelId": "demo-1006",
            "name": "Tejo Riverside Lofts",
            "url": "https://www.booking.com/hotel/pt/tejo-riverside-lofts-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Apartment",
            "stars": 4,
            "description": "Loft apartments on the riverfront in Cais do Sodré.",
            "currency": "US$",
            "rating": 9.3,
            "ratingLabel": "Superb",
            "reviews": 208,
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7060",
                "lng": "-9.1440"
            },
            "address": {
                "full": "Rua da Ribeira Nova 12, 1200-370 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal"
            },
            "rooms": [
                {
                    "roomType": "Loft",
                    "available": false,
                    "options": []
                }
            ],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:13.000Z"
        }
    ],
    "discoveryInput": {}
};

// Run the Actor and wait for it to finish
const run = await client.actor("rich_minds/booking-hotel-finder-ai").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 = {
    "sourceMode": "list",
    "maxDiscoveryChargeUsd": 0.5,
    "travellerBrief": "Quiet hotel for a couple, walkable to the old town, with a pool and free cancellation",
    "itemsList": [
        {
            "hotelId": "demo-1001",
            "name": "Casa do Largo Boutique Hotel",
            "url": "https://www.booking.com/hotel/pt/casa-do-largo-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Hotel",
            "stars": 4,
            "description": "Set in a restored 18th-century townhouse in Alfama, Casa do Largo Boutique Hotel offers a rooftop terrace with an outdoor swimming pool and views over the Tagus. The quiet side street is a 6-minute walk from Lisbon Cathedral.",
            "price": 356,
            "currency": "US$",
            "rating": 9.1,
            "ratingLabel": "Wonderful",
            "reviews": 1284,
            "checkIn": "From 15:00 to 23:00",
            "checkOut": "Until 12:00",
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7112",
                "lng": "-9.1312",
            },
            "address": {
                "full": "Largo do Contador-Mor 7, Alfama, 1100-194 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal",
            },
            "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1001.jpg",
            "rooms": [{
                    "roomType": "Superior Double Room",
                    "available": True,
                    "roomsLeft": 2,
                    "facilities": [
                        "Air conditioning",
                        "Free WiFi",
                        "Soundproofing",
                    ],
                    "options": [{
                            "price": 356,
                            "persons": 2,
                            "freeCancellation": True,
                            "yourChoices": [
                                "Breakfast included",
                                "Free cancellation before 24 October 2026",
                            ],
                            "hasGeniusDiscount": True,
                        }],
                }],
            "facilities": [
                {
                    "name": "Pool",
                    "facilities": [{
                            "name": "Outdoor swimming pool",
                            "additionalInfo": { "requiresAdditionalCharge": False },
                        }],
                },
                {
                    "name": "Internet",
                    "facilities": [{ "name": "Free WiFi" }],
                },
                {
                    "name": "Parking",
                    "facilities": [{
                            "name": "Public parking is possible at a location nearby (reservation is not needed) and costs EUR 18 per day.",
                            "additionalInfo": { "requiresAdditionalCharge": True },
                        }],
                },
                {
                    "name": "General",
                    "facilities": [
                        { "name": "Non-smoking rooms" },
                        { "name": "Elevator" },
                        { "name": "Soundproof rooms" },
                    ],
                },
            ],
            "categoryReviews": [
                {
                    "title": "Staff",
                    "score": 9.6,
                },
                {
                    "title": "Cleanliness",
                    "score": 9.4,
                },
                {
                    "title": "Location",
                    "score": 9.3,
                },
                {
                    "title": "Value for money",
                    "score": 8.8,
                },
                {
                    "title": "Free WiFi",
                    "score": 8.1,
                },
            ],
            "reviewSummary": {
                "summary": "Guests love the rooftop pool, the calm street and the breakfast; a few mention the steep walk up from the tram.",
                "pros": [
                    {
                        "description": "Rooftop pool with river views",
                        "numberOfMentions": 212,
                    },
                    {
                        "description": "Quiet, spotless rooms",
                        "numberOfMentions": 180,
                    },
                    {
                        "description": "Generous breakfast",
                        "numberOfMentions": 151,
                    },
                ],
                "cons": [{
                        "description": "Steep uphill walk from the tram stop",
                        "numberOfMentions": 64,
                    }],
            },
            "finePrint": "A city tax of EUR 4 per person per night is charged at the property for guests aged 13 and older, up to 7 nights.",
            "policies": [
                {
                    "title": "Children and beds",
                    "content": "Children of any age are welcome.",
                },
                {
                    "title": "Pets",
                    "content": "Pets are not allowed.",
                },
            ],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:02.000Z",
        },
        {
            "hotelId": "demo-1002",
            "name": "Hotel Miradouro da Graça",
            "url": "https://www.booking.com/hotel/pt/miradouro-da-graca-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Hotel",
            "stars": 3,
            "description": "Hotel Miradouro da Graça sits next to the Graça viewpoint and tram 28. Rooms are simple and bright; the lounge serves breakfast with a view of the castle.",
            "price": 248,
            "currency": "US$",
            "rating": 8.6,
            "ratingLabel": "Excellent",
            "reviews": 2410,
            "checkIn": "From 14:00",
            "checkOut": "Until 11:00",
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7166",
                "lng": "-9.1310",
            },
            "address": {
                "full": "Rua da Graça 88, 1170-167 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal",
            },
            "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1002.jpg",
            "rooms": [{
                    "roomType": "Standard Double Room",
                    "available": True,
                    "roomsLeft": 5,
                    "facilities": [
                        "Air conditioning",
                        "Free WiFi",
                    ],
                    "options": [
                        {
                            "price": 248,
                            "persons": 2,
                            "freeCancellation": False,
                            "yourChoices": [
                                "Breakfast US$14 (optional)",
                                "Non-refundable",
                            ],
                        },
                        {
                            "price": 276,
                            "persons": 2,
                            "freeCancellation": True,
                            "yourChoices": [
                                "Breakfast included",
                                "Free cancellation before 25 October 2026",
                            ],
                        },
                    ],
                }],
            "facilities": [
                {
                    "name": "Internet",
                    "facilities": [{ "name": "Free WiFi" }],
                },
                {
                    "name": "Parking",
                    "facilities": [{
                            "name": "Private parking is possible on site (reservation is needed) and costs EUR 20 per day.",
                            "additionalInfo": { "requiresAdditionalCharge": True },
                        }],
                },
                {
                    "name": "General",
                    "facilities": [
                        { "name": "Air conditioning" },
                        { "name": "24-hour front desk" },
                        { "name": "Elevator" },
                    ],
                },
            ],
            "categoryReviews": [
                {
                    "title": "Staff",
                    "score": 9,
                },
                {
                    "title": "Cleanliness",
                    "score": 8.7,
                },
                {
                    "title": "Location",
                    "score": 8.9,
                },
                {
                    "title": "Value for money",
                    "score": 8.9,
                },
                {
                    "title": "Comfort",
                    "score": 8.2,
                },
            ],
            "reviewSummary": {
                "summary": "Great value near the tram with a castle view at breakfast; rooms are on the small side.",
                "pros": [
                    {
                        "description": "Next to tram 28 and the viewpoint",
                        "numberOfMentions": 301,
                    },
                    {
                        "description": "Great value for Lisbon",
                        "numberOfMentions": 188,
                    },
                ],
                "cons": [
                    {
                        "description": "Small rooms",
                        "numberOfMentions": 97,
                    },
                    {
                        "description": "Street noise on weekends",
                        "numberOfMentions": 41,
                    },
                ],
            },
            "finePrint": "A damage deposit of EUR 100 is required on arrival and refunded at check-out. Check-in after 22:00 carries a surcharge of EUR 20.",
            "policies": [{
                    "title": "Cancellation/ prepayment",
                    "content": "Cancellation and prepayment policies vary according to accommodation type.",
                }],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:05.000Z",
            "sampleMemory": {
                "price": 272,
                "firstSeenAt": "2026-09-19T07:02:11+00:00",
                "note": "sample memory — the free demo's price drop",
            },
        },
        {
            "hotelId": "demo-1003",
            "name": "Baixa Garden Suites",
            "url": "https://www.booking.com/hotel/pt/baixa-garden-suites-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Apartment",
            "stars": 4,
            "description": "Baixa Garden Suites offers apartments with a kitchenette and a shared rooftop pool, 300 metres from Rossio Square. Each suite has a washing machine.",
            "price": 298,
            "currency": "US$",
            "rating": 8.9,
            "ratingLabel": "Fabulous",
            "reviews": 640,
            "checkIn": "From 16:00 to 20:00",
            "checkOut": "Until 11:00",
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7127",
                "lng": "-9.1388",
            },
            "address": {
                "full": "Rua dos Correeiros 112, Baixa, 1100-167 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal",
            },
            "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1003.jpg",
            "rooms": [{
                    "roomType": "One-Bedroom Apartment",
                    "available": True,
                    "roomsLeft": 1,
                    "facilities": [
                        "Kitchenette",
                        "Washing machine",
                        "Air conditioning",
                    ],
                    "options": [{
                            "price": 298,
                            "persons": 2,
                            "freeCancellation": True,
                            "yourChoices": [
                                "Free cancellation before 23 October 2026",
                                "No prepayment needed",
                            ],
                        }],
                }],
            "facilities": [
                {
                    "name": "Pool",
                    "facilities": [
                        { "name": "Rooftop pool" },
                        { "name": "Outdoor swimming pool" },
                    ],
                },
                {
                    "name": "Kitchen",
                    "facilities": [
                        { "name": "Kitchenette" },
                        { "name": "Washing machine" },
                    ],
                },
                {
                    "name": "Internet",
                    "facilities": [{ "name": "Free WiFi" }],
                },
                {
                    "name": "Parking",
                    "facilities": [{
                            "name": "Public parking is possible at a location nearby and costs EUR 25 per day.",
                            "additionalInfo": { "requiresAdditionalCharge": True },
                        }],
                },
            ],
            "categoryReviews": [
                {
                    "title": "Staff",
                    "score": 8.8,
                },
                {
                    "title": "Cleanliness",
                    "score": 9.1,
                },
                {
                    "title": "Location",
                    "score": 9.6,
                },
                {
                    "title": "Value for money",
                    "score": 8.6,
                },
            ],
            "reviewSummary": {
                "summary": "Central apartments with a pool; check-in closes at 20:00.",
                "pros": [
                    {
                        "description": "Unbeatable central location",
                        "numberOfMentions": 140,
                    },
                    {
                        "description": "Kitchenette and washing machine",
                        "numberOfMentions": 66,
                    },
                ],
                "cons": [{
                        "description": "Early check-in cut-off",
                        "numberOfMentions": 38,
                    }],
            },
            "finePrint": "Guests arriving after 20:00 must contact the property in advance; late check-in carries an extra charge of EUR 30. This property only accepts cash for the city tax.",
            "policies": [{
                    "title": "Parties",
                    "content": "Parties/events are not allowed.",
                }],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:07.000Z",
        },
        {
            "hotelId": "demo-1004",
            "name": "Avenida Liberdade Grand",
            "url": "https://www.booking.com/hotel/pt/avenida-liberdade-grand-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Hotel",
            "stars": 5,
            "description": "A five-star hotel on Avenida da Liberdade with an indoor pool, spa and fitness centre. Valet parking is available.",
            "price": 780,
            "currency": "US$",
            "rating": 9,
            "ratingLabel": "Wonderful",
            "reviews": 3120,
            "checkIn": "From 15:00",
            "checkOut": "Until 12:00",
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7201",
                "lng": "-9.1460",
            },
            "address": {
                "full": "Avenida da Liberdade 185, 1250-141 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal",
            },
            "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1004.jpg",
            "rooms": [{
                    "roomType": "Deluxe King Room",
                    "available": True,
                    "facilities": [
                        "Air conditioning",
                        "Free WiFi",
                        "Bathtub",
                    ],
                    "options": [{
                            "price": 780,
                            "persons": 2,
                            "freeCancellation": True,
                            "yourChoices": [
                                "Breakfast included",
                                "Free cancellation before 24 October 2026",
                            ],
                        }],
                }],
            "facilities": [
                {
                    "name": "Pool",
                    "facilities": [{ "name": "Indoor swimming pool" }],
                },
                {
                    "name": "Wellness",
                    "facilities": [
                        {
                            "name": "Spa",
                            "additionalInfo": { "requiresAdditionalCharge": True },
                        },
                        { "name": "Fitness centre" },
                    ],
                },
                {
                    "name": "Parking",
                    "facilities": [{
                            "name": "Valet parking",
                            "additionalInfo": { "requiresAdditionalCharge": True },
                        }],
                },
                {
                    "name": "Internet",
                    "facilities": [{ "name": "Free WiFi" }],
                },
            ],
            "categoryReviews": [
                {
                    "title": "Staff",
                    "score": 9.4,
                },
                {
                    "title": "Cleanliness",
                    "score": 9.3,
                },
                {
                    "title": "Location",
                    "score": 9.1,
                },
                {
                    "title": "Value for money",
                    "score": 8,
                },
            ],
            "reviewSummary": {
                "summary": "Luxury on the avenue with an excellent spa; pricey for Lisbon.",
                "pros": [
                    {
                        "description": "Excellent spa and indoor pool",
                        "numberOfMentions": 260,
                    },
                    {
                        "description": "Attentive staff",
                        "numberOfMentions": 233,
                    },
                ],
                "cons": [{
                        "description": "Expensive extras",
                        "numberOfMentions": 88,
                    }],
            },
            "finePrint": "A resort fee of EUR 25 per room per night applies. A credit card pre-authorisation is taken at check-in.",
            "policies": [{
                    "title": "Pets",
                    "content": "Pets are allowed on request. Charges may apply.",
                }],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:09.000Z",
        },
        {
            "hotelId": "demo-1005",
            "name": "Rossio Budget Hostel",
            "url": "https://www.booking.com/hotel/pt/rossio-budget-hostel-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Hostel",
            "stars": 1,
            "description": "Dorms and private rooms on Rossio Square.",
            "price": 96,
            "currency": "US$",
            "rating": 7.6,
            "ratingLabel": "Good",
            "reviews": 512,
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7141",
                "lng": "-9.1398",
            },
            "address": {
                "full": "Praça Dom Pedro IV 40, 1100-200 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal",
            },
            "rooms": [{
                    "roomType": "Private Double Room",
                    "available": True,
                    "options": [{
                            "price": 96,
                            "persons": 2,
                            "freeCancellation": False,
                            "yourChoices": ["Non-refundable"],
                        }],
                }],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:11.000Z",
        },
        {
            "hotelId": "demo-1006",
            "name": "Tejo Riverside Lofts",
            "url": "https://www.booking.com/hotel/pt/tejo-riverside-lofts-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
            "type": "Apartment",
            "stars": 4,
            "description": "Loft apartments on the riverfront in Cais do Sodré.",
            "currency": "US$",
            "rating": 9.3,
            "ratingLabel": "Superb",
            "reviews": 208,
            "checkInDate": "2026-10-26",
            "checkOutDate": "2026-10-28",
            "location": {
                "lat": "38.7060",
                "lng": "-9.1440",
            },
            "address": {
                "full": "Rua da Ribeira Nova 12, 1200-370 Lisbon, Portugal",
                "city": "Lisbon",
                "country": "Portugal",
            },
            "rooms": [{
                    "roomType": "Loft",
                    "available": False,
                    "options": [],
                }],
            "startUrlOrQuery": "Lisbon",
            "timeOfScrapeISO": "2026-09-26T08:14:13.000Z",
        },
    ],
    "discoveryInput": {},
}

# Run the Actor and wait for it to finish
run = client.actor("rich_minds/booking-hotel-finder-ai").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 '{
  "sourceMode": "list",
  "maxDiscoveryChargeUsd": 0.5,
  "travellerBrief": "Quiet hotel for a couple, walkable to the old town, with a pool and free cancellation",
  "itemsList": [
    {
      "hotelId": "demo-1001",
      "name": "Casa do Largo Boutique Hotel",
      "url": "https://www.booking.com/hotel/pt/casa-do-largo-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Hotel",
      "stars": 4,
      "description": "Set in a restored 18th-century townhouse in Alfama, Casa do Largo Boutique Hotel offers a rooftop terrace with an outdoor swimming pool and views over the Tagus. The quiet side street is a 6-minute walk from Lisbon Cathedral.",
      "price": 356,
      "currency": "US$",
      "rating": 9.1,
      "ratingLabel": "Wonderful",
      "reviews": 1284,
      "checkIn": "From 15:00 to 23:00",
      "checkOut": "Until 12:00",
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7112",
        "lng": "-9.1312"
      },
      "address": {
        "full": "Largo do Contador-Mor 7, Alfama, 1100-194 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1001.jpg",
      "rooms": [
        {
          "roomType": "Superior Double Room",
          "available": true,
          "roomsLeft": 2,
          "facilities": [
            "Air conditioning",
            "Free WiFi",
            "Soundproofing"
          ],
          "options": [
            {
              "price": 356,
              "persons": 2,
              "freeCancellation": true,
              "yourChoices": [
                "Breakfast included",
                "Free cancellation before 24 October 2026"
              ],
              "hasGeniusDiscount": true
            }
          ]
        }
      ],
      "facilities": [
        {
          "name": "Pool",
          "facilities": [
            {
              "name": "Outdoor swimming pool",
              "additionalInfo": {
                "requiresAdditionalCharge": false
              }
            }
          ]
        },
        {
          "name": "Internet",
          "facilities": [
            {
              "name": "Free WiFi"
            }
          ]
        },
        {
          "name": "Parking",
          "facilities": [
            {
              "name": "Public parking is possible at a location nearby (reservation is not needed) and costs EUR 18 per day.",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            }
          ]
        },
        {
          "name": "General",
          "facilities": [
            {
              "name": "Non-smoking rooms"
            },
            {
              "name": "Elevator"
            },
            {
              "name": "Soundproof rooms"
            }
          ]
        }
      ],
      "categoryReviews": [
        {
          "title": "Staff",
          "score": 9.6
        },
        {
          "title": "Cleanliness",
          "score": 9.4
        },
        {
          "title": "Location",
          "score": 9.3
        },
        {
          "title": "Value for money",
          "score": 8.8
        },
        {
          "title": "Free WiFi",
          "score": 8.1
        }
      ],
      "reviewSummary": {
        "summary": "Guests love the rooftop pool, the calm street and the breakfast; a few mention the steep walk up from the tram.",
        "pros": [
          {
            "description": "Rooftop pool with river views",
            "numberOfMentions": 212
          },
          {
            "description": "Quiet, spotless rooms",
            "numberOfMentions": 180
          },
          {
            "description": "Generous breakfast",
            "numberOfMentions": 151
          }
        ],
        "cons": [
          {
            "description": "Steep uphill walk from the tram stop",
            "numberOfMentions": 64
          }
        ]
      },
      "finePrint": "A city tax of EUR 4 per person per night is charged at the property for guests aged 13 and older, up to 7 nights.",
      "policies": [
        {
          "title": "Children and beds",
          "content": "Children of any age are welcome."
        },
        {
          "title": "Pets",
          "content": "Pets are not allowed."
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:02.000Z"
    },
    {
      "hotelId": "demo-1002",
      "name": "Hotel Miradouro da Graça",
      "url": "https://www.booking.com/hotel/pt/miradouro-da-graca-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Hotel",
      "stars": 3,
      "description": "Hotel Miradouro da Graça sits next to the Graça viewpoint and tram 28. Rooms are simple and bright; the lounge serves breakfast with a view of the castle.",
      "price": 248,
      "currency": "US$",
      "rating": 8.6,
      "ratingLabel": "Excellent",
      "reviews": 2410,
      "checkIn": "From 14:00",
      "checkOut": "Until 11:00",
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7166",
        "lng": "-9.1310"
      },
      "address": {
        "full": "Rua da Graça 88, 1170-167 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1002.jpg",
      "rooms": [
        {
          "roomType": "Standard Double Room",
          "available": true,
          "roomsLeft": 5,
          "facilities": [
            "Air conditioning",
            "Free WiFi"
          ],
          "options": [
            {
              "price": 248,
              "persons": 2,
              "freeCancellation": false,
              "yourChoices": [
                "Breakfast US$14 (optional)",
                "Non-refundable"
              ]
            },
            {
              "price": 276,
              "persons": 2,
              "freeCancellation": true,
              "yourChoices": [
                "Breakfast included",
                "Free cancellation before 25 October 2026"
              ]
            }
          ]
        }
      ],
      "facilities": [
        {
          "name": "Internet",
          "facilities": [
            {
              "name": "Free WiFi"
            }
          ]
        },
        {
          "name": "Parking",
          "facilities": [
            {
              "name": "Private parking is possible on site (reservation is needed) and costs EUR 20 per day.",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            }
          ]
        },
        {
          "name": "General",
          "facilities": [
            {
              "name": "Air conditioning"
            },
            {
              "name": "24-hour front desk"
            },
            {
              "name": "Elevator"
            }
          ]
        }
      ],
      "categoryReviews": [
        {
          "title": "Staff",
          "score": 9
        },
        {
          "title": "Cleanliness",
          "score": 8.7
        },
        {
          "title": "Location",
          "score": 8.9
        },
        {
          "title": "Value for money",
          "score": 8.9
        },
        {
          "title": "Comfort",
          "score": 8.2
        }
      ],
      "reviewSummary": {
        "summary": "Great value near the tram with a castle view at breakfast; rooms are on the small side.",
        "pros": [
          {
            "description": "Next to tram 28 and the viewpoint",
            "numberOfMentions": 301
          },
          {
            "description": "Great value for Lisbon",
            "numberOfMentions": 188
          }
        ],
        "cons": [
          {
            "description": "Small rooms",
            "numberOfMentions": 97
          },
          {
            "description": "Street noise on weekends",
            "numberOfMentions": 41
          }
        ]
      },
      "finePrint": "A damage deposit of EUR 100 is required on arrival and refunded at check-out. Check-in after 22:00 carries a surcharge of EUR 20.",
      "policies": [
        {
          "title": "Cancellation/ prepayment",
          "content": "Cancellation and prepayment policies vary according to accommodation type."
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:05.000Z",
      "sampleMemory": {
        "price": 272,
        "firstSeenAt": "2026-09-19T07:02:11+00:00",
        "note": "sample memory — the free demo'\''s price drop"
      }
    },
    {
      "hotelId": "demo-1003",
      "name": "Baixa Garden Suites",
      "url": "https://www.booking.com/hotel/pt/baixa-garden-suites-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Apartment",
      "stars": 4,
      "description": "Baixa Garden Suites offers apartments with a kitchenette and a shared rooftop pool, 300 metres from Rossio Square. Each suite has a washing machine.",
      "price": 298,
      "currency": "US$",
      "rating": 8.9,
      "ratingLabel": "Fabulous",
      "reviews": 640,
      "checkIn": "From 16:00 to 20:00",
      "checkOut": "Until 11:00",
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7127",
        "lng": "-9.1388"
      },
      "address": {
        "full": "Rua dos Correeiros 112, Baixa, 1100-167 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1003.jpg",
      "rooms": [
        {
          "roomType": "One-Bedroom Apartment",
          "available": true,
          "roomsLeft": 1,
          "facilities": [
            "Kitchenette",
            "Washing machine",
            "Air conditioning"
          ],
          "options": [
            {
              "price": 298,
              "persons": 2,
              "freeCancellation": true,
              "yourChoices": [
                "Free cancellation before 23 October 2026",
                "No prepayment needed"
              ]
            }
          ]
        }
      ],
      "facilities": [
        {
          "name": "Pool",
          "facilities": [
            {
              "name": "Rooftop pool"
            },
            {
              "name": "Outdoor swimming pool"
            }
          ]
        },
        {
          "name": "Kitchen",
          "facilities": [
            {
              "name": "Kitchenette"
            },
            {
              "name": "Washing machine"
            }
          ]
        },
        {
          "name": "Internet",
          "facilities": [
            {
              "name": "Free WiFi"
            }
          ]
        },
        {
          "name": "Parking",
          "facilities": [
            {
              "name": "Public parking is possible at a location nearby and costs EUR 25 per day.",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            }
          ]
        }
      ],
      "categoryReviews": [
        {
          "title": "Staff",
          "score": 8.8
        },
        {
          "title": "Cleanliness",
          "score": 9.1
        },
        {
          "title": "Location",
          "score": 9.6
        },
        {
          "title": "Value for money",
          "score": 8.6
        }
      ],
      "reviewSummary": {
        "summary": "Central apartments with a pool; check-in closes at 20:00.",
        "pros": [
          {
            "description": "Unbeatable central location",
            "numberOfMentions": 140
          },
          {
            "description": "Kitchenette and washing machine",
            "numberOfMentions": 66
          }
        ],
        "cons": [
          {
            "description": "Early check-in cut-off",
            "numberOfMentions": 38
          }
        ]
      },
      "finePrint": "Guests arriving after 20:00 must contact the property in advance; late check-in carries an extra charge of EUR 30. This property only accepts cash for the city tax.",
      "policies": [
        {
          "title": "Parties",
          "content": "Parties/events are not allowed."
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:07.000Z"
    },
    {
      "hotelId": "demo-1004",
      "name": "Avenida Liberdade Grand",
      "url": "https://www.booking.com/hotel/pt/avenida-liberdade-grand-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Hotel",
      "stars": 5,
      "description": "A five-star hotel on Avenida da Liberdade with an indoor pool, spa and fitness centre. Valet parking is available.",
      "price": 780,
      "currency": "US$",
      "rating": 9,
      "ratingLabel": "Wonderful",
      "reviews": 3120,
      "checkIn": "From 15:00",
      "checkOut": "Until 12:00",
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7201",
        "lng": "-9.1460"
      },
      "address": {
        "full": "Avenida da Liberdade 185, 1250-141 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "image": "https://cf.bstatic.com/xdata/images/hotel/max1024x768/demo-1004.jpg",
      "rooms": [
        {
          "roomType": "Deluxe King Room",
          "available": true,
          "facilities": [
            "Air conditioning",
            "Free WiFi",
            "Bathtub"
          ],
          "options": [
            {
              "price": 780,
              "persons": 2,
              "freeCancellation": true,
              "yourChoices": [
                "Breakfast included",
                "Free cancellation before 24 October 2026"
              ]
            }
          ]
        }
      ],
      "facilities": [
        {
          "name": "Pool",
          "facilities": [
            {
              "name": "Indoor swimming pool"
            }
          ]
        },
        {
          "name": "Wellness",
          "facilities": [
            {
              "name": "Spa",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            },
            {
              "name": "Fitness centre"
            }
          ]
        },
        {
          "name": "Parking",
          "facilities": [
            {
              "name": "Valet parking",
              "additionalInfo": {
                "requiresAdditionalCharge": true
              }
            }
          ]
        },
        {
          "name": "Internet",
          "facilities": [
            {
              "name": "Free WiFi"
            }
          ]
        }
      ],
      "categoryReviews": [
        {
          "title": "Staff",
          "score": 9.4
        },
        {
          "title": "Cleanliness",
          "score": 9.3
        },
        {
          "title": "Location",
          "score": 9.1
        },
        {
          "title": "Value for money",
          "score": 8
        }
      ],
      "reviewSummary": {
        "summary": "Luxury on the avenue with an excellent spa; pricey for Lisbon.",
        "pros": [
          {
            "description": "Excellent spa and indoor pool",
            "numberOfMentions": 260
          },
          {
            "description": "Attentive staff",
            "numberOfMentions": 233
          }
        ],
        "cons": [
          {
            "description": "Expensive extras",
            "numberOfMentions": 88
          }
        ]
      },
      "finePrint": "A resort fee of EUR 25 per room per night applies. A credit card pre-authorisation is taken at check-in.",
      "policies": [
        {
          "title": "Pets",
          "content": "Pets are allowed on request. Charges may apply."
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:09.000Z"
    },
    {
      "hotelId": "demo-1005",
      "name": "Rossio Budget Hostel",
      "url": "https://www.booking.com/hotel/pt/rossio-budget-hostel-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Hostel",
      "stars": 1,
      "description": "Dorms and private rooms on Rossio Square.",
      "price": 96,
      "currency": "US$",
      "rating": 7.6,
      "ratingLabel": "Good",
      "reviews": 512,
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7141",
        "lng": "-9.1398"
      },
      "address": {
        "full": "Praça Dom Pedro IV 40, 1100-200 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "rooms": [
        {
          "roomType": "Private Double Room",
          "available": true,
          "options": [
            {
              "price": 96,
              "persons": 2,
              "freeCancellation": false,
              "yourChoices": [
                "Non-refundable"
              ]
            }
          ]
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:11.000Z"
    },
    {
      "hotelId": "demo-1006",
      "name": "Tejo Riverside Lofts",
      "url": "https://www.booking.com/hotel/pt/tejo-riverside-lofts-demo.html?checkin=2026-10-26&checkout=2026-10-28&group_adults=2",
      "type": "Apartment",
      "stars": 4,
      "description": "Loft apartments on the riverfront in Cais do Sodré.",
      "currency": "US$",
      "rating": 9.3,
      "ratingLabel": "Superb",
      "reviews": 208,
      "checkInDate": "2026-10-26",
      "checkOutDate": "2026-10-28",
      "location": {
        "lat": "38.7060",
        "lng": "-9.1440"
      },
      "address": {
        "full": "Rua da Ribeira Nova 12, 1200-370 Lisbon, Portugal",
        "city": "Lisbon",
        "country": "Portugal"
      },
      "rooms": [
        {
          "roomType": "Loft",
          "available": false,
          "options": []
        }
      ],
      "startUrlOrQuery": "Lisbon",
      "timeOfScrapeISO": "2026-09-26T08:14:13.000Z"
    }
  ],
  "discoveryInput": {}
}' |
apify call rich_minds/booking-hotel-finder-ai --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,rich_minds/booking-hotel-finder-ai"
        }
    }
}
```

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/ekQVU8ZNTX5Vg5eEe/builds/Q7DFDszOdudUxtx14/openapi.json