# Google Hotels search (SERP-compatible): `POST /v1/serp/google_hotels`

Cost: 4 credits (4 per page of results; an empty page and failed requests are free). Docs: https://scrapercompany.com/docs/reference/serp-google-hotels

Drop-in for the standard SERP API `engine=google_hotels`.

Same request names and response hierarchy (`search_parameters`,
`search_information`, `properties[]`, `brands[]`, `pagination`).
Extracted prices are exact floats rather than rounded integers, and each
property adds `prices[]` where Google attached seller rows. Filters this
source cannot honour are refused with 422 instead of being ignored.

Request body (JSON):

- `q` (string; required; min length 2, max length 200): Destination query exactly as a traveller would type it into Google Hotels, e.g. `hotels in Montreal`, `Paris`, `hotels near JFK`. Google resolves it to a place; the response reports which in `search_information.location`.
- `adults` (integer; optional; default 2; min 1, max 10): Adults in the room. Encoded as one guest entry each, the way Google's own control sends them.
- `currency` (string; optional; default USD; one of AED, ARS, AUD, BRL, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MXN, MYR, NOK, NZD, PEN, PHP, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, TWD, USD, VND, ZAR): ISO 4217 code for the returned prices. Major currencies include AED, AUD, BRL, CAD, CHF, CNY, EUR, GBP, HKD, INR, JPY, KRW, MXN, NZD, SGD, USD; all 39 supported codes are listed in the enum.
- `gl` (string; optional; default us; one of ad, ae, af, ag, ai, al, am, ao, aq, ar, as, at, au, aw, ax, az, ba, bb, bd, be, bf, bg, bh, bi, bj, bl, bm, bn, bo, bq, br, bs, bt, bv, bw, by, bz, ca, cc, cd, cf, cg, ch, ci, ck, cl, cm, cn, co, cr, cu, cv, cw, cx, cy, cz, de, dj, dk, dm, do, dz, ec, ee, eg, eh, er, es, et, fi, fj, fk, fm, fo, fr, ga, gb, gd, ge, gf, gg, gh, gi, gl, gm, gn, gp, gq, gr, gs, gt, gu, gw, gy, hk, hm, hn, hr, ht, hu, id, ie, il, im, in, io, iq, ir, is, it, je, jm, jo, jp, ke, kg, kh, ki, km, kn, kp, kr, kw, ky, kz, la, lb, lc, li, lk, lr, ls, lt, lu, lv, ly, ma, mc, md, me, mf, mg, mh, mk, ml, mm, mn, mo, mp, mq, mr, ms, mt, mu, mv, mw, mx, my, mz, na, nc, ne, nf, ng, ni, nl, no, np, nr, nu, nz, om, pa, pe, pf, pg, ph, pk, pl, pm, pn, pr, ps, pt, pw, py, qa, re, ro, rs, ru, rw, sa, sb, sc, sd, se, sg, sh, si, sj, sk, sl, sm, sn, so, sr, ss, st, sv, sx, sy, sz, tc, td, tf, tg, th, tj, tk, tl, tm, tn, to, tr, tt, tv, tw, tz, ua, ug, uk, um, us, uy, uz, va, vc, ve, vg, vi, vn, vu, wf, ws, xk, ye, yt, za, zm, zw): Two-letter Google country (market). Sets the market; the currency is requested separately.
- `hl` (string; optional; default en; pattern ^[a-z]{2,3}(-[A-Za-z]{2,4})?$): Interface language. Display strings follow it; hotel amenity names are always English.
- `sort_by` (string; optional; default relevance; one of highest_rating, lowest_price, most_reviewed, relevance): Result order, as Google's Sort by control.
- `price_min` (integer | null; optional; min 0): Minimum nightly price in `currency`.
- `price_max` (integer | null; optional; min 0): Maximum nightly price in `currency`.
- `free_cancellation` (boolean; optional; default false): Only properties Google lists with free cancellation.
- `special_offers` (boolean; optional; default false): Only properties with a special offer.
- `eco_certified` (boolean; optional; default false): Only eco-certified properties.
- `engine` (string; optional; default google_hotels; one of google_hotels): Accepted for SERP API compatibility; must be `google_hotels`.
- `property_type` (string; optional; default hotel; one of hotel, vacation_rental): `hotel` (default) is Google's own list, which Google may blend with vacation rentals; each result states its `type`. `vacation_rental` is refused with 422: Google does not honour the rentals-only category for this search, so it is refused rather than silently ignored.
- `check_in_date` (string (date); required): First night of the stay, `YYYY-MM-DD`. Also accepted as `check_in`.
- `check_out_date` (string (date); required): Departure date, after `check_in_date`; at most 30 nights. Also accepted as `check_out`.
- `children_ages` (string | array of integer | null; optional): Comma-separated child ages, 0-17 (SERP API: `2,5`).
- `rating` (integer | null; optional; one of 7, 8, 9): SERP API rating code: 7 (3.5+), 8 (4.0+), 9 (4.5+).
- `hotel_class` (string | array of integer | null; optional): Comma-separated star classes, 2-5.
- `amenities` (string | array of integer | null; optional): Comma-separated amenity ids (same ids as SERP API/SerpApi, e.g. 6 Pool, 35 Free Wi-Fi).
- `property_types` (string | array of integer | null; optional): Comma-separated property-type ids, e.g. 19 Bed and breakfasts, 14 Hostels.
- `brands` (string | array of integer | null; optional): Not supported: Google ignores brand filters on this search, so a non-empty value is refused with 422.
- `for_displaced_individuals` (boolean; optional; default false): Not supported; `true` is refused with 422.
- `bedrooms` (integer | null; optional; min 0): Vacation-rental filter. Not supported; a value above 0 is refused with 422.
- `bathrooms` (integer | null; optional; min 0): Vacation-rental filter. Not supported; a value above 0 is refused with 422.
- `bounding_box` (string | null; optional): Not supported; search by `q`.
- `next_page_token` (string | null; optional; pattern ^[A-Za-z0-9_\-+/=]{1,200}$): Opaque cursor from `pagination.next_page_token` of the previous page. Resend the same query, stay, occupancy and filters with it, exactly as with SERP API.
- `zero_retention` (boolean; optional; default false): Accepted for SERP API compatibility; search results are never persisted.

Response fields:

- `search_metadata` (object; required)
  - `search_metadata.status` (string; required; one of Success)
  - `search_metadata.created_at` (string (date-time); required): UTC, ISO-8601 with `Z`.
  - `search_metadata.request_time_taken` (number; required): Seconds.
  - `search_metadata.total_time_taken` (number; required): Seconds.
- `search_parameters` (object; required): Echo of the effective request. Optional filters appear only when set.
  - `search_parameters.engine` (string; required; one of google_hotels)
  - `search_parameters.q` (string; required)
  - `search_parameters.check_in_date` (string (date); required)
  - `search_parameters.check_out_date` (string (date); required)
  - `search_parameters.adults` (integer; required)
  - `search_parameters.children_ages` (array of integer; required): One age per child; empty when none.
  - `search_parameters.currency` (string; required): Requested currency, upper-case.
  - `search_parameters.gl` (string; required): Market country code, lower-case.
  - `search_parameters.hl` (string; required)
  - `search_parameters.sort_by` (string; required; one of relevance, lowest_price, highest_rating, most_reviewed)
  - `search_parameters.price_min` (integer; optional): Present only when set in the request.
  - `search_parameters.price_max` (integer; optional): Present only when set in the request.
  - `search_parameters.min_rating` (number; optional): 3.5, 4.0 or 4.5. Present only when set in the request. Converted from the `rating` code (7, 8, 9).
  - `search_parameters.hotel_class` (array of integer; optional): Present only when set in the request.
  - `search_parameters.amenities` (array of integer; optional): Present only when set in the request.
  - `search_parameters.property_types` (array of integer; optional): Present only when set in the request.
  - `search_parameters.free_cancellation` (boolean; optional): Present only when true.
  - `search_parameters.special_offers` (boolean; optional): Present only when true.
  - `search_parameters.eco_certified` (boolean; optional): Present only when true.
  - `search_parameters.next_page_token` (string; optional): Page token this page was fetched with. Present only when one was sent.
  - `search_parameters.property_type` (string; required; one of hotel): Always `hotel`.
- `search_information` (object; required)
  - `search_information.total_results` (integer | null; required): Total properties Google reports for the search.
  - `search_information.location` (string | null; required): Place Google resolved `q` to.
  - `search_information.currency_matches_request` (boolean; required): False when Google returned a currency other than the one requested.
- `properties` (array of object; required): About 20 per page.
  - `properties[].type` (string; required; one of hotel, vacation_rental): Google blends vacation rentals into the default list; this says which each result is.
  - `properties[].property_token` (string; required): Google property token; pass it to `/v1/serp/google_hotels_property` or `/v1/calendar`.
  - `properties[].data_id` (string; optional): Google Maps data id (`0x...:0x...`).
  - `properties[].name` (string; required)
  - `properties[].link` (string; optional): The property's own website.
  - `properties[].description` (string; optional)
  - `properties[].gps_coordinates` (object; optional)
  - `properties[].city` (string; optional): The place Google resolved `q` to (same as `search_information.location`), not a per-property city.
  - `properties[].country` (string; optional): ISO 3166-1 alpha-2 country code.
  - `properties[].check_in_time` (string; optional): As displayed, e.g. `3:00 PM`.
  - `properties[].check_out_time` (string; optional)
  - `properties[].price_per_night` (object; optional): Present only when the stay total is known.
  - `properties[].total_price` (object; optional): Present only when the stay total is known.
  - `properties[].deal` (string; optional): Deal text, e.g. `27% less than usual`.
  - `properties[].deal_description` (string; optional): Badge Google renders: `Deal`, `Great Deal`, `Great Price`, or another label.
  - `properties[].nearby_places` (array of object; required)
  - `properties[].hotel_class` (string; optional): As displayed, e.g. `4-star hotel`.
  - `properties[].extracted_hotel_class` (integer; optional): Star class, 1-5.
  - `properties[].rating` (number; optional): Guest rating out of 5.
  - `properties[].reviews` (integer; optional)
  - `properties[].reviews_histogram` (object; optional): Review count per star rating, keyed `1`-`5`.
  - `properties[].location_rating` (number; optional): Overall location score, out of 5.
  - `properties[].proximity_to_things_to_do_rating` (number; optional): Score for proximity to things to do, out of 5.
  - `properties[].proximity_to_restaurants_rating` (number; optional): Score for proximity to restaurants, out of 5.
  - `properties[].proximity_to_transit_rating` (number; optional): Score for proximity to public transit, out of 5.
  - `properties[].airport_access_rating` (number; optional): Score for airport access, out of 5.
  - `properties[].reviews_breakdown` (array of object; required): Empty when Google gave none.
  - `properties[].amenities` (array of string; required): Hotel amenity names are always English; rentals use Google's own labels.
  - `properties[].excluded_amenities` (array of string; optional): Amenities a rental states it lacks, e.g. `No balcony`.
  - `properties[].essential_info` (array of string; optional): Rental basics such as `Entire apartment` or `Sleeps 2`.
  - `properties[].images` (array of object; required)
  - `properties[].thumbnail` (string; optional)
  - `properties[].prices` (array of object; optional): Seller rows Google attached to the card (an addition to the standard SERP API shape); mostly vacation rentals.
  - `properties[].currency` (string; optional): ISO 4217 code of every price on the property.
- `brands` (array of object; required)
  - `brands[].id` (integer; required): Google brand id.
  - `brands[].title` (string; required): Brand name; empty string when Google did not name it.
  - `brands[].children` (array of object; required): Sub-brands.
- `pagination` (object; required): Pages overlap by a few results (page 2 starts before page 1 ends); de-duplicate by `property_token`.
  - `pagination.records_from` (integer | null; required): 1-based position of the first result on this page.
  - `pagination.records_to` (integer | null; required): 1-based position of the last result on this page.
  - `pagination.next_page_token` (string | null; required): Send it back (as `page_token` on `/v1/hotels/search`, `next_page_token` on `/v1/serp/google_hotels`) with the same query, stay, party and filters for the next page. Null on the last page.

Base URL: `https://api.scrapercompany.com`. Auth: send your key in the `x-api-key` header. A failed request (4xx or 5xx) or an empty result costs 0 credits.

- [Full API reference as one Markdown file](https://scrapercompany.com/llms-full.txt)
- [OpenAPI spec](https://scrapercompany.com/openapi.json)
