MCP + API · kestrel/google-hotels-prices
Google Hotels Prices Scraper & API - OTA Rates, Hotel Details
Google Hotels API: hotel prices by city, hotel name or URL for your dates. One row per hotel: nightly rate, stay total, taxes, deals, availability, rating. Optional OTA rates (Booking.com, Expedia, Agoda, official site): rate parity, price comparison, price tracking. Free: address, phone, amenities.
Open Actor Download MCP config
Connect this tool
Add this URL as a remote MCP server in your client, then sign in to Apify. For a client-specific setup, use Apify's configurator.
https://mcp.apify.com?tools=call-actor,fetch-actor-details,kestrel/google-hotels-prices
Generic MCP client configuration
{
"mcpServers": {
"kestrel-google-hotels-prices": {
"url": "https://mcp.apify.com?tools=call-actor,fetch-actor-details,kestrel/google-hotels-prices"
}
}
}
Understand the output before you run
Three row types share one dataset: hotel (lowest nightly rate and stay total per hotel), offer (one booking source's rate for a hotel and stay), status (per place or property and stay; never charged).
Declared dataset fields and row types · Output locations and dataset links
Use the declared dataset schema for item fields; the output schema describes where results are stored. Optional fields may be null or absent. If an integration shows a sampled schema without an optional field, check this declaration, the Actor instructions and actual returned rows before concluding that the field is unsupported.
Inspect 70 declared output fields
| Field | Type | Meaning |
|---|---|---|
type | string | Row type: hotel, offer or status. |
query | string / null | The place search this row came from (null in property mode). |
hotel | string / null | Status rows in property mode: the hotel URL or entity token that was priced. |
check_in | string | Check-in date, YYYY-MM-DD. |
check_out | string | Check-out date, YYYY-MM-DD. |
nights | integer | Nights in the stay. |
adults | integer | Adults per room used for pricing. |
children | integer | Children per room used for pricing. |
currency | string | Currency of every price in the row (ISO code). |
rank | integer / null | Position in Google's results for the place search (null in property mode). |
name | string / null | Hotel name. |
hotel_id | string / null | Google's numeric hotel id. |
entity_id | string / null | Google Hotels entity token; reuse it in the hotels input to price this property directly. |
cid | string / null | Google Maps place id (CID). |
stars | integer / null | Hotel class, 1–5. |
class_label | string / null | Google's class label, e.g. 4-star hotel. |
rating | number / null | Google rating, 1–5. |
reviews | integer / null | Number of Google reviews. |
lat | number / null | |
lng | number / null | |
description | string / null | Google's one-line description of the hotel. |
website | string / null | Hotel website. |
types | array / null | Google place types, e.g. hostel, boutique_hotel. |
checkin_time | string / null | |
checkout_time | string / null | |
thumbnail | string / null | Thumbnail image URL. |
nightly | number / null | Lowest nightly rate (hotel rows) or this source's nightly rate (offer rows). Null = no price for the stay (sold out). |
nightly_display | string / null | Nightly rate as Google displays it, e.g. $82. |
total | number / null | Total for the whole stay. |
total_display | string / null | Stay total as Google displays it. |
deal | string / null | Google's deal note, e.g. 19% less than usual. |
source | string / null | Booking source: an OTA name, or the hotel's own name when official is true. On hotel rows: the source of the lowest rate when Google names it. |
source_id | integer / null | Google's id for the source — the key of a source (a name can appear twice: official listing and marketplace rate). |
official | boolean / null | True when the source is the hotel's official site. |
room | string / null | Room name (offerLevel rooms only). |
max_guests | integer / null | Guests the rate covers (offerLevel rooms only). |
free_cancel | boolean / null | Free cancellation available. |
free_cancel_until | string / null | Free-cancellation deadline as Google shows it, e.g. Oct 1. |
link | string / null | Google's click-through link for the source. |
partner_url | string / null | The source's own URL with the dates filled in (official sites: the booking engine). |
lowest | boolean / null | True for a source's lowest rate row. |
maps_url | string / null | Google Maps link for the hotel. |
google_url | string / null | Google Hotels page of the hotel. |
total_results | integer / null | Google's result count for the place search (capped at 15000). |
hotels | integer / null | Status rows: hotel rows produced. |
priced | integer / null | Status rows: hotels with a price (the only ones charged). |
offers | integer / null | Status rows: offer rows produced. |
duplicates | integer / null | Status rows: hotels skipped because another search already delivered them for this stay. |
offer_errors | integer / null | Status rows: hotels whose offers page failed. |
error | string / null | Status rows: error message, null when the job succeeded. |
fetched_at | string | UTC timestamp of the fetch. |
spread_km | number / null | Status rows, place mode only: median distance in km of the returned hotels from their centre. A city is single digits, a region tens. A large value means Google may not have resolved your place and answered with scattered unrelated hotels — those rows are still billed, so check this before trusting a run. |
address | string / null | Street address (includeDetails). |
phone | string / null | Phone number as Google lists it (includeDetails). |
place_id | string / null | Google Maps place ID, ChIJ… — joins to Maps and Places data (includeDetails). |
description_long | string / null | Google's long description of the property (includeDetails). |
rating_breakdown | array / null | Google rating distribution: [{stars, percent, reviews}] for 5 to 1 stars (includeDetails). |
review_aspects | array / null | Topics guests mention in reviews: [{aspect, mentions, positive, negative, score}], e.g. Service, Location, Breakfast (includeDetails). |
external_ratings | array / null | Ratings on other sites Google shows: [{source, rating, scale, reviews}], e.g. Tripadvisor, Trip.com (includeDetails). |
photos | array / null | Photo URLs from the property page (includeDetails). |
detail_errors | integer / null | Status rows, with includeDetails: hotels whose details could not be fetched (the rows are still delivered). |
total_base | number / null | Stay total before taxes and fees. total_base + taxes + fees = total_with_taxes. |
taxes | number / null | Taxes included in the stay total, as Google breaks it down. |
fees | number / null | Fees included in the stay total (service charges, resort fees), as Google breaks it down. |
deal_percent | integer / null | The number in the deal note: 19 for "19% less than usual". |
total_with_taxes | number / null | Stay total including taxes and fees, Google's all-in figure. Unlike `total` (what Google displays: base + fees without taxes from a US IP, all-in from most others) it does not depend on the proxy's country. |
amenities | array / null | Amenities the property has, by name, with notes: "Wi-Fi (free)", "Parking (extra charge)" (includeDetails). English labels. |
amenities_unavailable | array / null | Amenities Google lists as not available at the property (includeDetails). |
free_cancel_until_date | string / null | Offer rows: the free-cancellation deadline as an ISO date (2026-10-25), derived from free_cancel_until and the stay; empty when the wording cannot be read unambiguously. |
free_cancel_until_time | string / null | Offer rows: the time of day the free-cancellation deadline ends, as Google words it ("11:59 PM", "18:00"). |
Read an observed output example and its input, observation date and limits. These are historical source values, not a current quote or a promise of the same result.
Assemble a hotel price comparison
The dataset is flat: type=hotel, type=offer and type=status. Join hotel and offer rows by entity_id + check_in + check_out, keeping currencies separate. hotel_id may be null. Individual booking sources and links belong to the offer rows: source, official, nightly, total, currency, link, partner_url.
Keep includeOffers=true for booking-site comparisons. A positive maxOffersPerHotel keeps the cheapest offers and may omit the official site; a missing direct offer does not prove rate parity. Check status rows for source errors. With ten hotels and eight offers each, listed event charges are at most $0.20; use a separate run budget and report early stopping.
Start with a small sample
Use call-actor with the JSON below. The $0.25 run ceiling is separate from the Actor input and may stop the sample early. Change the target to match your request. This input validates against build 1.9.11; it is not a promise that the source has matching rows today.
{
"actor": "kestrel/google-hotels-prices",
"input": {
"queries": [
"hotels in Lisbon"
],
"checkIn": "30 days",
"checkOut": "32 days",
"adults": 2,
"currency": "USD",
"maxHotels": 3,
"includeOffers": true,
"offerLevel": "sources",
"maxOffersPerHotel": 3
},
"callOptions": {
"maxTotalChargeUsd": 0.25,
"timeout": 300
},
"waitSecs": 30
}
After completion, use get-dataset-items with storages.datasets.default.id. If still running, poll get-actor-run using the returned runId. Check status rows and errors before treating an empty dataset as no matches.
Call from Python, JavaScript or REST
Python SDK 3 example · JavaScript SDK 2 example · curl + jq example. Each uses this same small input, reads APIFY_TOKEN from your environment, sets a five-minute run timeout and exports all dataset row types as JSON Lines. The $0.25 run ceiling is separate from the Actor input and may stop the sample early. Inspect the run and source status before treating results as complete. Installation and usage.
Pricing and limits
Current listed event prices in USD. Some Actors charge for successful source checks even when no output rows match. The event descriptions below define those differences.
| Event | USD each | What is charged |
|---|---|---|
hotel | $0.004 | One hotel with its lowest nightly rate, stay total and taxes for your dates (row keys name, entity_id, hotel_id, stars, rating, reviews, lat, lng, nightly, total, taxes, fees, total_with_taxes, currency, source, check_in, check_out, google_url): $4 per 1,000 hotels. Address, phone, amenities and photos (includeDetails; keys address, phone, place_id, amenities, photos) ride on this row at no extra charge. Not charged: sold-out or unpriced hotels, duplicates, hotels your filters remove, empty or failed searches, hotel names that match nothing, status rows. No start fee; proxy and compute are included in the event price. The run stops at the maximum cost per run you set when starting it (Apify run option maxTotalChargeUsd), never above it. |
offer | $0.002 | One booking site's rate for one hotel and stay (Booking.com, Expedia, Agoda, official site…) with free-cancellation flag and link (row keys entity_id, hotel_id, name, source, official, room, nightly, total, currency, link, partner_url, free_cancel, free_cancel_until_date, max_guests, lowest, check_in, check_out): $2 per 1,000. Measured: about 18 rows per hotel (4 to 36) with offerLevel "sources", about 65 (up to 150) with "rooms". Not charged when includeOffers is false; maxOffersPerHotel caps the rows per hotel. Failed offer lookups are free. |
Contracts for agents
- Input schema and sample input
- Prepared MCP call and pricing events
- Full Actor instructions and limits
- REST API
Public contract checked 2026-11-11. Active build: 1.9.11. Refresh live details before a large or recurring run.