Google Hotels

Return a full multi-OTA price comparison plus rich metadata for any hotel and date range worldwide. Submit a job by Google Place ID (recommended) or hotel name + city, then poll for the result.

Base URL: https://api.scrapeguys.com · Auth: X-API-Key: gsk_… with the gmaps scope · See the Overview.

Submit a job

Provide either a place_id (recommended — deterministic) or a hotel_name. When searching by name (no place_id), city is also required. A place_id-only request is valid; if both are given, place_id is used first with name+city as fallback. Place ID mode exists because name matching is the least reliable way to identify a hotel — here is why, and what to key on instead. Guides covers the data-quality problems that sit around these endpoints.

Why Place ID beats name matching, and how to store and refresh IDs: matching the same hotel across OTAs.

Children. Google prices a child by age — on one test property a 5-year-old and a 12-year-old came back at different prices on the same OTA. A request with children is priced by Google Travel for the whole party (adults plus each child's age), never from an adults-only price: on a Place-ID scrape the result carries party_pricing_source (travel_rpc for Google's price call, entity when that call failed and the hotel's Travel page was used instead). If neither answers, that scrape reports an error and the pipeline falls back to another Google surface that carries the party — an adults-only price is never returned for a party with children. Expect fewer OTAs than for adults only — only OTAs with a room for the party list it — and an empty pricing when no room fits (on v2, pricing_status: "none"). The poll response echoes children_ages, so the party every price is for is explicit; children echoes the resolved count.

Poll for results

Poll the poll_url every ~2 seconds until status is completed or failed. Statuses: pending → processing → completed | failed.

Response schema

A completed job returns the job envelope with a result object. Top-level fields: id, status, api_version, hotel_name, city, place_id, check_in, check_out, adults, children, children_ages, result, error_message, created_at, started_at, completed_at, duration_seconds, bandwidth_kb.

Fields — pricing[] (per OTA)

Fields — hotel_metadata

name, hotel_class (stars), user_rating, review_count, description, address, neighborhood, phone, website, latitude, longitude, check_in_time, check_out_time, amenities[], free_breakfast, images[].

free_breakfast (bool / null) is the property's claim of free breakfast, taken from its amenities; null when Google listed no amenities. It describes the hotel, not any individual rate — use per-offer breakfast_included / board to compare what a price includes.

Errors — on submit: 400 (validation: neither place_id nor hotel_name, a place_id containing characters outside A–Z a–z 0–9 _ -, name search without city, a past or over-a-year-out check_in, a stay over 30 nights, children and children_ages disagreeing), 401 (missing, unknown or deactivated key), 403 (key lacks the gmaps scope), 429 (per-minute limit, or daily / monthly quota exhausted). On poll: 404 (unknown id, another client's job, or an OTA price job — those poll on /ota-price/), 401, 403.

Children

Unlike every OTA endpoint, a bare children count is accepted here — Google's own guest picker defaults an unspecified child to age 12. Send children_ages instead when you know the ages, e.g. "children_ages": [5, 9] (0–17 each, max 6 — the list length is the child count, and it overrides children): Google prices a 5-year-old and a 9-year-old differently on the same OTA.

A party with children is never read off the adults-only price. The place-lookup call this endpoint otherwise prices from has no child field at all, so once a child is in the party the job is priced through Google Travel instead — its own price RPC first, the hotel's own listing page if that fails. Expect fewer OTAs than for adults only (not every one lists family occupancy), and on API v2 a pricing_status: "none" alongside the empty pricing when no room fits the party. The resolved children_ages is always echoed back on every poll (it isn't in the 202 submit response — see Submit a job) — so the party a price is for is never implicit.

Batch scraping

Scrape up to 20 hotels that share the same check-in/check-out in one call. Each hotel becomes its own job.

Batch limits: hotels must hold 1–20 entries (400 otherwise — "Maximum 20 hotels per batch request."), and each needs a place_id or a hotel_name + city. Each place_id is cleaned and validated exactly as in a single submit. batch/results takes 1–20 IDs (400 "Provide 1-20 job_ids."); malformed IDs are skipped without error, IDs that are unknown, belong to another client or are OTA price jobs are simply absent from results (results come back newest first, not in request order — match on id), and a request where none parse is a 400 ("No valid job IDs provided."). Both batch endpoints need the gmaps scope.

API versions

Pass an optional X-API-Version header (1 or 2; default 2 — send X-API-Version: 1 to stay on the v1 pipeline; the examples on this page show v1 jobs). The chosen version is echoed back as api_version. Unrecognized values fall back to the default silently — they do not error. The header is read on /scrape/ and /batch/ only.

Fields — pricing_status (v2 only)

An empty pricing: [] is ambiguous on its own — it can mean the hotel genuinely has no offers, or that we couldn't confirm one way or the other. pricing_status disambiguates it. The field is additive: ignore it and v2 behaves exactly like before.

When pricing_status isn't ok, pricing_status_reason qualifies it:

Place ID lookup

Find the Google Place ID we hold for a hotel, from a full name, a partial name or a few keywords — so the next request can go by place_id. It searches the hotels we already hold and costs 0 units.

Auth: X-API-Key: gsk_… with the gmaps scope.

hotel_name and city echo your request as sent. matches lists every candidate in the city whose name resembles your query, best first. Each carries its own stored hotel_name, a score (0–1), coordinates, and match: "exact" or "fuzzy". An exact match (case, punctuation and spacing ignored) is always matches[0]. Spelling variants are tolerated, so Hotel Amaya finds a stored The Amayaa, and accented names such as Résidence Alpina match exactly.

ota_ids holds the OTA property ids we hold for the candidate, keyed by OTA. An OTA's entry is included only when your key also holds that OTA's scope; otherwise it is omitted, and a key with no OTA scopes gets {}.

Errors — 400 (hotel_name or city missing or blank: "`hotel_name` and `city` are both required."; a value too long; or max_matches outside 1–50), 401, 403 (key lacks the gmaps scope), 404 ({"error": "No Place ID is stored for this hotel_name and city."}). A name with candidates but no exact match returns 200 with place_id: null; check matches, not just the status.

Next: Agoda →