Multi-operator accommodation comparator for a geographic area and a stay:
dates (required), guests and optional filters. Returns a ranked list of
properties — hotels, B&Bs, apartments, villas, hostels and more — with the
booking sites that offer each one and their live availability and
per-operator price for the requested dates. Questions about one property
found here (guest opinions, facilities, a live re-quote) are served by
`get_property_details` and `check_property_availability` with that
result's `id`.
Dates: natural-language references ("this weekend", "the weekend of
July 4", "long weekend in May") translate to concrete check_in /
check_out values at the call site; ISO dates also work.
Locale: `user_country`, `currency` and `language` carry the user's
locale, not the destination's. Prices come back in `currency` if set,
otherwise in the currency of `user_country` (US→USD, CA→CAD, GB→GBP,
euro-area→EUR), otherwise USD. Each offer is quoted by its operator in
that currency; nothing is converted. `user_country` and `language` also
localize the booking link.
Each result carries:
- `location.lat` / `location.lon`, suitable for plotting the results on
a map.
- `thumbnail_url` (first photo, or null) and `images`, capped to one
photo; `get_property_details` returns the full gallery.
- `web_url`, a link to the property page with the stay already encoded.
- `price` and `offers[]`: the live quote for the requested dates,
present only when availability was confirmed. Each offer has `ota`,
`amount` (total stay), `amount_per_night`, `currency`,
`breakfast_included`, `refundable`, `rooms_left` and `deeplink_url` —
a Blue Pillow tracked link that records the click and forwards to the
operator's booking page; it is what attributes the booking to Blue
Pillow, which a raw operator URL does not. `price` mirrors `offers[0]`,
Blue Pillow's best value for money (price weighed against breakfast,
free cancellation and operator reliability, with a small commercial
component), not necessarily the cheapest; `sort=price_asc` orders by
price alone. There is no
date-agnostic "from" price.
- `availability_status`: `available` (live quotes in `offers`),
`unavailable` (no rooms for those dates) or `unknown` (the operators
returned nothing conclusive — not evidence that the property is full).
The default `availability_mode=strict` returns only `available`
results; `include_unavailable` also returns the other two.
Reading the numbers: `amount_per_night` is per night and `amount` is the
total stay, so a quote reads clearly with its unit ("€X/night via
Booking, €Y total"). `rooms_left` signals scarcity; `refundable` and
`breakfast_included` often separate otherwise similar options.
Ratings are on a 0-5 scale (`rating`, `reviews_aggregate.score_0_5`,
review scores and `filters.min_rating`; "8 out of 10" is 4.0). Upstream
scores arrive rounded, so `rating` is coarse and reads best together with
`rating_count`. `rating`, `stars` and `rating_count` may be 0 or absent
in this list even when the property has them; `get_property_details`
returns the fuller `reviews_aggregate`. Here `reviews_aggregate` carries
`score_0_5`, `rating_count` (reviews behind the score) and
`comment_count` (review texts available) — two different magnitudes.
`include=["reviews_sample"]` adds up to 5 recent review texts per
property, useful for qualitative criteria ("great breakfast", "quiet
area"); a deeper read on one property is `get_property_details` with
`reviews_extended`.
Filters: `filters.min_rating` and `filters.price_max_eur` narrow the
results; `filters.property_types` and `filters.amenities` rank rather
than filter, so each result's `property_type` and `amenities` show what
it actually is. Property type tokens: hotel, apartment, house, villa,
bb, hostel, farmstay, holiday-home (common Italian and English synonyms
are accepted). Common amenity codes: wi-fi, parking, pool,
air-conditioning, kitchen, garden, pets-allowed, for-families,
facilities-for-disabled, non-smoking-only.
Location modes:
- `coordinates`: a known lat/lon (default radius 5 km, up to 50 km;
beyond that `bbox` or a parent destination fits better).
- `destination_id`: the opaque id from `resolve_destination`, passed
verbatim.
- `poi_id`: the opaque id of a point of interest, from
`resolve_destination` or `discover_destinations_near`.
- `bbox`: an explicit map rectangle.
A property is not a location: `get_property_details` covers a known
property.
Pagination: the `next_cursor` of a response goes into `page.cursor` for
the next page.
View input schema
{
"type": "object",
"properties": {
"api_key": {
"type": "string",
"description": "Anonymous key for this server (format 'pk_anon_…'), as returned by `get_anonymous_key`. Required by this tool; the same key works for every call."
},
"location": {
"type": "object",
"additionalProperties": false,
"required": [
"type",
"value"
],
"description": "Where to search, as a {type, value} pair. Use destination_id for a place resolved via resolve_destination, poi_id for a point of interest, coordinates for a known lat/lon, or bbox for an explicit map rectangle. A property is NOT a location — use get_property_details for a known property.",
"properties": {
"type": {
"type": "string",
"enum": [
"destination_id",
"poi_id",
"coordinates",
"bbox"
],
"description": "Selects the shape of value: destination_id and poi_id take an id string, coordinates takes {lat, lon, radius_km?}, bbox takes {nw: [lat,lon], se: [lat,lon]}. property_id is NOT supported here; use get_property_details."
},
"value": {
"description": "Shape depends on type — see each option below.",
"anyOf": [
{
"type": "string",
"description": "destination_id/poi_id: opaque id string from resolve_destination or discover_destinations_near (e.g. 'dest_590c54056664cf2c60c5c2f6'). Pass it verbatim — the 'dest_'/'poi_' prefix is accepted. NEVER pass a free-form name like 'Ancona'; the API rejects bad identifiers with 400 invalid_request."
},
{
"type": "object",
"additionalProperties": false,
"required": [
"lat",
"lon"
],
"description": "coordinates: a known point, searched within radius_km.",
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "Latitude in decimal degrees."
},
"lon": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "Longitude in decimal degrees."
},
"radius_km": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Search radius in km (default 5)."
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"nw",
"se"
],
"description": "bbox: an explicit map rectangle, given by its north-west and south-east corners.",
"properties": {
"nw": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "North-west corner as [lat, lon]."
},
"se": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2,
"description": "South-east corner as [lat, lon]."
}
}
}
]
}
}
},
"dates": {
"type": "object",
"additionalProperties": false,
"required": [
"check_in",
"check_out"
],
"description": "Check-in and check-out dates (ISO 8601, YYYY-MM-DD). Natural-language references — 'tonight', 'this weekend', 'the weekend of July 4', 'Memorial Day weekend', 'long weekend in May' — translate to concrete check_in / check_out values at the call site. The comparator only serves future stays: check_in is a date in the real-time calendar that is today or later. A reference like 'the weekend of June 2' resolves to the next occurrence after today, never a past anniversary; if the current year is unclear, confirm with the user before calling. Clock calibration: this schema was published in August 2026, so today is August 2026 OR LATER (likely later — schemas outlive their publish date). An assumed 'today' in 2024/2025 is a stale training-time clock; years before 2026 are always in the past. Past check_in values are rejected at the API boundary with a hint carrying the actual current date.",
"properties": {
"check_in": {
"type": "string",
"format": "date"
},
"check_out": {
"type": "string",
"format": "date"
}
}
},
"guests": {
"type": "object",
"additionalProperties": false,
"required": [
"adults"
],
"description": "Party composition. `adults` is required; give `children_ages` (one age per child, 0-17) rather than a child count — operators price by age. `rooms` defaults to 1; raise it when the party needs separate rooms rather than one shared.",
"properties": {
"adults": {
"type": "integer",
"minimum": 1,
"maximum": 16
},
"children_ages": {
"type": "array",
"items": {
"type": "integer",
"minimum": 0,
"maximum": 17
}
},
"rooms": {
"type": "integer",
"minimum": 1,
"maximum": 9
}
}
},
"filters": {
"type": "object",
"additionalProperties": false,
"description": "Structured narrowing applied server-side, before ranking. Prefer these over filtering the results yourself: they run across the whole inventory, not just the page you received. Qualitative criteria that do not map here (\"quiet\", \"great breakfast\") are better served by include=['reviews_sample'].",
"properties": {
"price_max_eur": {
"type": "number",
"minimum": 0
},
"min_rating": {
"type": "number",
"minimum": 0,
"maximum": 5
},
"property_types": {
"type": "array",
"description": "Preferred property types. Like `amenities`, this steers rather than excludes: the types listed here come first and a minority of other types can still appear in the page. Read each result's `property_type` when the distinction matters to the user. Canonical tokens: hotel, apartment, house, villa, bb, hostel, farmstay, holiday-home. Italian/English synonyms (agriturismo, bnb, appartamento, casa, ...) are accepted and normalized server-side.",
"items": {
"type": "string"
}
},
"amenities": {
"type": "array",
"description": "Preferred amenity codes. This ranks, it does not filter: properties declaring every code listed here come first and nothing is dropped, because upstream declarations are incomplete — an absent code is not evidence the service is missing. Read each result's `amenities` to see what is actually declared. Common: wi-fi, parking, pool, air-conditioning, kitchen, garden, pets-allowed, for-families, facilities-for-disabled, non-smoking-only.",
"items": {
"type": "string"
}
}
}
},
"sort": {
"type": "string",
"enum": [
"score_desc",
"price_asc",
"rating_desc",
"conversion_desc"
],
"description": "Result ordering. score_desc (default) is the balanced relevance ranking and suits most requests; price_asc when the user asked for the cheapest; rating_desc when they asked for the best-reviewed; conversion_desc favours what comparable travellers actually booked."
},
"page": {
"type": "object",
"additionalProperties": false,
"description": "Pagination. `limit` caps results per page (1-100). To fetch the next page pass `cursor` with the `next_cursor` value from the previous response — cursors are opaque and are never constructed by hand.",
"properties": {
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"cursor": {
"type": "string"
}
}
},
"include": {
"type": "array",
"description": "Optional enrichments, always a list — pass [\"reviews_sample\"], never the bare string. 'reviews_sample' attaches the 5 most recent individual reviews per property — use for qualitative queries (breakfast, service, ...). One extra Mongo round-trip per page; omit by default.",
"items": {
"type": "string",
"enum": [
"reviews_sample"
]
}
},
"user_country": {
"type": "string",
"pattern": "^[A-Z]{2}$",
"description": "User's country (ISO-3166 alpha-2 uppercase). Drives the booking-link locale (the landing page rendered when the user clicks `web_url`) AND, when `currency` is not set, the pricing currency (US->USD, CA->CAD, euro-area->EUR). Pass the user's own country, not the destination's. Falls back to 'US' when omitted."
},
"language": {
"type": "string",
"pattern": "^[a-z]{2}$",
"description": "User's UI language (2-letter lowercase). Drives the booking link language and any server-rendered narrative content. Pass the language the user is currently speaking. Falls back to 'en' when omitted."
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$",
"description": "Currency of the returned prices (ISO-4217, 3-letter uppercase, e.g. 'USD', 'EUR', 'GBP', 'CAD'). SET THIS (or `user_country`) to price in the user's currency — if you set NEITHER, prices default to USD, which may not be the user's. Prices come straight from the booking sources in this currency; never convert them yourself. Each offer reflects the currency its operator actually quoted."
},
"availability_mode": {
"type": "string",
"enum": [
"strict",
"include_unavailable"
],
"description": "strict (default): return ONLY properties available for the requested dates. include_unavailable: also return properties with no availability (each tagged availability_status). Use strict unless the user explicitly wants to see sold-out options."
},
"include_out_of_bounds": {
"type": "boolean",
"description": "Opt-in. When the requested area yields few available results, also return (in alternatives.out_of_bounds) properties just outside the area, within the original budget. Present these explicitly as alternatives, never mixed with primary results."
},
"include_overbudget": {
"type": "boolean",
"description": "Opt-in. When few available results fit the budget, also return (in alternatives.overbudget) available properties in the same area just above price_max_eur. Requires filters.price_max_eur."
}
},
"required": [
"location",
"dates",
"guests"
],
"additionalProperties": false
}