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
FieldTypeMeaning
typestringRow type: hotel, offer or status.
querystring / nullThe place search this row came from (null in property mode).
hotelstring / nullStatus rows in property mode: the hotel URL or entity token that was priced.
check_instringCheck-in date, YYYY-MM-DD.
check_outstringCheck-out date, YYYY-MM-DD.
nightsintegerNights in the stay.
adultsintegerAdults per room used for pricing.
childrenintegerChildren per room used for pricing.
currencystringCurrency of every price in the row (ISO code).
rankinteger / nullPosition in Google's results for the place search (null in property mode).
namestring / nullHotel name.
hotel_idstring / nullGoogle's numeric hotel id.
entity_idstring / nullGoogle Hotels entity token; reuse it in the hotels input to price this property directly.
cidstring / nullGoogle Maps place id (CID).
starsinteger / nullHotel class, 1–5.
class_labelstring / nullGoogle's class label, e.g. 4-star hotel.
ratingnumber / nullGoogle rating, 1–5.
reviewsinteger / nullNumber of Google reviews.
latnumber / null
lngnumber / null
descriptionstring / nullGoogle's one-line description of the hotel.
websitestring / nullHotel website.
typesarray / nullGoogle place types, e.g. hostel, boutique_hotel.
checkin_timestring / null
checkout_timestring / null
thumbnailstring / nullThumbnail image URL.
nightlynumber / nullLowest nightly rate (hotel rows) or this source's nightly rate (offer rows). Null = no price for the stay (sold out).
nightly_displaystring / nullNightly rate as Google displays it, e.g. $82.
totalnumber / nullTotal for the whole stay.
total_displaystring / nullStay total as Google displays it.
dealstring / nullGoogle's deal note, e.g. 19% less than usual.
sourcestring / nullBooking 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_idinteger / nullGoogle's id for the source — the key of a source (a name can appear twice: official listing and marketplace rate).
officialboolean / nullTrue when the source is the hotel's official site.
roomstring / nullRoom name (offerLevel rooms only).
max_guestsinteger / nullGuests the rate covers (offerLevel rooms only).
free_cancelboolean / nullFree cancellation available.
free_cancel_untilstring / nullFree-cancellation deadline as Google shows it, e.g. Oct 1.
linkstring / nullGoogle's click-through link for the source.
partner_urlstring / nullThe source's own URL with the dates filled in (official sites: the booking engine).
lowestboolean / nullTrue for a source's lowest rate row.
maps_urlstring / nullGoogle Maps link for the hotel.
google_urlstring / nullGoogle Hotels page of the hotel.
total_resultsinteger / nullGoogle's result count for the place search (capped at 15000).
hotelsinteger / nullStatus rows: hotel rows produced.
pricedinteger / nullStatus rows: hotels with a price (the only ones charged).
offersinteger / nullStatus rows: offer rows produced.
duplicatesinteger / nullStatus rows: hotels skipped because another search already delivered them for this stay.
offer_errorsinteger / nullStatus rows: hotels whose offers page failed.
errorstring / nullStatus rows: error message, null when the job succeeded.
fetched_atstringUTC timestamp of the fetch.
spread_kmnumber / nullStatus 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.
addressstring / nullStreet address (includeDetails).
phonestring / nullPhone number as Google lists it (includeDetails).
place_idstring / nullGoogle Maps place ID, ChIJ… — joins to Maps and Places data (includeDetails).
description_longstring / nullGoogle's long description of the property (includeDetails).
rating_breakdownarray / nullGoogle rating distribution: [{stars, percent, reviews}] for 5 to 1 stars (includeDetails).
review_aspectsarray / nullTopics guests mention in reviews: [{aspect, mentions, positive, negative, score}], e.g. Service, Location, Breakfast (includeDetails).
external_ratingsarray / nullRatings on other sites Google shows: [{source, rating, scale, reviews}], e.g. Tripadvisor, Trip.com (includeDetails).
photosarray / nullPhoto URLs from the property page (includeDetails).
detail_errorsinteger / nullStatus rows, with includeDetails: hotels whose details could not be fetched (the rows are still delivered).
total_basenumber / nullStay total before taxes and fees. total_base + taxes + fees = total_with_taxes.
taxesnumber / nullTaxes included in the stay total, as Google breaks it down.
feesnumber / nullFees included in the stay total (service charges, resort fees), as Google breaks it down.
deal_percentinteger / nullThe number in the deal note: 19 for "19% less than usual".
total_with_taxesnumber / nullStay 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.
amenitiesarray / nullAmenities the property has, by name, with notes: "Wi-Fi (free)", "Parking (extra charge)" (includeDetails). English labels.
amenities_unavailablearray / nullAmenities Google lists as not available at the property (includeDetails).
free_cancel_until_datestring / nullOffer 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_timestring / nullOffer 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.

EventUSD eachWhat is charged
hotel$0.004One 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.002One 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

Public contract checked 2026-11-11. Active build: 1.9.11. Refresh live details before a large or recurring run.