# Destination search: `POST /v1/hotels/search`

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

One page (~20) of the properties Google Hotels lists for a destination.

Each property carries its `property_token` (feed it to `/v1/calendar` or
`/v1/offers`), rating, class, amenities, images, coordinates, deal signal
and the lowest price for the stay, itemised into base, taxes, fees and
total with provenance. Vacation rentals add their seller rows. Page on with
`pagination.next_page_token`, resending the same body.

Prices reflect the point of sale the request was served from;
`meta` and `warnings` say which market that was.

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.
- `check_in` (string (date); required): First night of the stay, `YYYY-MM-DD`. Also accepted as `check_in_date`.
- `check_out` (string (date); required): Departure date, after `check_in`; at most 30 nights. Also accepted as `check_out_date`.
- `children_ages` (array of integer; optional; default []; max items 8): One age (0-17) per child. Google prices on each age; the response is rejected if Google priced a different party.
- `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.
- `min_rating` (number | null; optional; one of 3.5, 4, 4.5): Minimum guest rating: 3.5, 4.0 or 4.5.
- `hotel_class` (array of integer; optional; default []; max items 4): Star classes to include, 2-5.
- `amenities` (array of integer; optional; default []; max items 19): Amenity filter ids: 1 Free parking, 3 Parking, 4 Indoor pool, 5 Outdoor pool, 6 Pool, 7 Fitness center, 8 Restaurant, 9 Free breakfast, 10 Spa, 11 Beach access, 12 Child-friendly, 15 Bar, 19 Pet-friendly, 22 Room service, 35 Free Wi-Fi, 40 Air-conditioned, 52 All-inclusive available, 53 Wheelchair accessible, 61 EV charger.
- `property_types` (array of integer; optional; default []; max items 13): Property-type filter ids: 12 Beach hotels, 13 Boutique hotels, 14 Hostels, 15 Inns, 16 Motels, 17 Resorts, 18 Spa hotels, 19 Bed and breakfasts, 20 Other, 21 Apartment hotels, 22 Minshuku, 23 Japanese-style business hotels, 24 Ryokan.

Response fields:

- `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)
  - `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.
  - `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_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.location_data_id` (string | null; required): Google's place id for `location`.
  - `search_information.nights` (integer; required)
  - `search_information.returned` (integer; required): Properties on this page.
  - `search_information.priced` (integer; required): Properties on this page with a known stay total.
  - `search_information.requested_currency` (string; required)
  - `search_information.returned_currency` (string | null; required): Currency the prices came back in; `MIXED` when properties differ; null when no property carried a currency.
  - `search_information.currency_matches_request` (boolean; required): False when Google returned another currency (also reported in `warnings`).
  - `search_information.requested_market` (string; required): `gl`, upper-cased.
  - `search_information.available_property_types` (array of object; required): Property-type filters Google offers for this destination.
- `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/calendar` or `/v1/offers`.
  - `properties[].name` (string; required)
  - `properties[].data_id` (string | null; required): Google Maps data id (`0x...:0x...`).
  - `properties[].description` (string | null; required)
  - `properties[].link` (string | null; required): The property's own website, when Google lists one.
  - `properties[].gps_coordinates` (object | null; required)
  - `properties[].country` (string | null; required): ISO 3166-1 alpha-2 country code.
  - `properties[].check_in_time` (string | null; required): As displayed, e.g. `3:00 PM`.
  - `properties[].check_out_time` (string | null; required): As displayed, e.g. `11:00 AM`.
  - `properties[].hotel_class` (string | null; required): As displayed, e.g. `4-star hotel`.
  - `properties[].extracted_hotel_class` (integer | null; required): Star class, 1-5.
  - `properties[].rating` (number | null; required): Guest rating out of 5.
  - `properties[].reviews` (integer | null; required): Number of reviews.
  - `properties[].reviews_histogram` (object | null; required): Review count per star rating, keyed `1`-`5` (only the stars Google reported). Null when Google gave none.
  - `properties[].location_rating` (number | null; required): Overall location score, out of 5. Null when Google has no score.
  - `properties[].proximity_to_things_to_do_rating` (number | null; required): Score for proximity to things to do, out of 5. Null when Google has no score.
  - `properties[].proximity_to_restaurants_rating` (number | null; required): Score for proximity to restaurants, out of 5. Null when Google has no score.
  - `properties[].proximity_to_transit_rating` (number | null; required): Score for proximity to public transit, out of 5. Null when Google has no score.
  - `properties[].airport_access_rating` (number | null; required): Score for airport access, out of 5. Null when Google has no score.
  - `properties[].reviews_breakdown` (array of object; required): Review topics with mention counts; empty when Google gave none.
  - `properties[].amenities` (array of string; required): Amenity names. Hotel amenity names are always English; rentals use Google's own labels.
  - `properties[].amenity_codes` (array of array of integer; required): Raw `[flag, code]` pairs from the card. Codes are not the `amenities` filter ids; codes without a known name appear only here. The flag does not mark an amenity as absent.
  - `properties[].excluded_amenities` (array of string; required): Amenities a rental states it lacks, e.g. `No balcony`; usually empty for hotels.
  - `properties[].essential_info` (array of string; required): Rental basics such as `Entire apartment` or `Sleeps 2`; usually empty for hotels.
  - `properties[].thumbnail` (string | null; required)
  - `properties[].images` (array of object; required)
  - `properties[].nearby_places` (array of object; required)
  - `properties[].deal` (string | null; required): Deal text, e.g. `27% less than usual` or `Great price for a 4-star hotel`. Null when there is no deal.
  - `properties[].deal_description` (string | null; required): Badge Google renders: `Deal`, `Great Deal`, `Great Price`, or another label.
  - `properties[].deal_kind` (string | null; required): `below_usual_price`, `great_price`, or `code_<n>` for a deal type not yet mapped. Null when there is no deal.
  - `properties[].rate` (object | null; required): Lowest price for the stay. Null when the card carried no price, or Google priced other dates and the price was removed (see `warnings`).
  - `properties[].sources` (array of object; required): Seller rows Google attached to the card; mostly vacation rentals, usually empty for hotels.
  - `properties[].provenance` (object | null; required): Provenance of `rate`; null unless `rate.total` is known.
- `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.
- `warnings` (array of string; required): Notices about this page: prices removed because Google priced other dates, a currency other than the one requested, results outside a requested `hotel_class`, `min_rating` or `price_max`, or prices not verified for the requested market.
- `meta` (object; required)
  - `meta.elapsed_s` (number; required): Seconds spent fetching from Google.
  - `meta.skipped_records` (integer; required): Result cards that could not be read and were left out.

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)
