Travel and places · SearchApi (Google Hotels)

hotels.search

Searches Google Hotels for a destination and date range. Results carry nightly and total prices, rating, review count and amenities; details adds the description, nearby places and a booking link.

Operation: POST /v1/capabilities/hotels.search/execute
operationId: executeHotelsSearch
Typical credits: 4
Search deadline: 15 s server-side
Paging: token
Availability: ConfiguredChecked 2026-09-23 21:02 UTC

Cost basis: $0.004 per search page. Availability is reported per deployment by GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.

Request

Body of POST /v1/capabilities/hotels.search/execute, JSON, validated against the HotelsSearchRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.

Request fields of hotels.search
Field	Type	Required	Default	Constraints and description
destination	string	yes		min length 1, max length 200
check_in	string	yes		pattern ^\d{4}-\d{2}-\d{2}$ Check-in date (YYYY-MM-DD).
check_out	string	yes		pattern ^\d{4}-\d{2}-\d{2}$ Check-out date (YYYY-MM-DD).
adults	integer	no	2	min 1, max 10
children_ages	integer[]	no		max items 5 Child ages for hotels only; at most six guests including adults. Not supported for explicit vacation-rental searches.
currency	string	no	"USD"	min length 3, max length 3
max_price	number	no		min 0 Per night.
min_rating	number	no		min 0, max 5 Guest rating floor, 0-5.
amenities	string[]	no		max items 10
property_type	"hotel" \| "vacation_rental"	no
sort	"relevance" \| "lowest_price" \| "highest_rating" \| "most_reviewed"	no

Unknown keys are rejected with 400 invalid_request.

Rules the schema cannot express

Checked after schema validation; violations return 400 invalid_request with a plain message.

At least one adult; child ages 1 to 17; at most six guests for hotels and ten for vacation rentals.
children_ages is not accepted with property_type: "vacation_rental".

Examples

Weekend

curl

curl -s -X POST https://api.powerups-ai.store/v1/capabilities/hotels.search/execute \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"destination":"Lisbon","check_in":"2026-10-09","check_out":"2026-10-11","adults":2,"currency":"EUR","sort":"highest_rating"}'

No recorded response is published for this capability yet. The envelope is the ExecuteResponse component (see sessions and records); the record keys below are what the adapter emits. A first call with the example above returns search_id, the records and the charge.

Result record

Every item in results[] carries record_id and title (contract, always present) and usually url and snippet. The keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the HotelsSearchRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. See stability tiers.

Record keys of hotels.search
Key	Type	Presence
price_per_night	number	when the source has it
total_price	number	when the source has it
currency	string	when the source has it
rating	number	when the source has it
reviews	integer	when the source has it
hotel_class	string	when the source has it
type	string	when the source has it
amenities	string[]	when the source has it
location	string	when the source has it
lat	number	when the source has it
lon	number	when the source has it
requested_occupancy	object	always
occupancy_status	string	always
occupancy_note	string	when the source has it

Caveats

Server-side filters (min_rating, max_price) can leave a page empty while has_more stays true.

Follow-ups

Paging: Provider cursor; more fetches the next page from the source. Send { "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.
Update: Re-run with changed parameters (merged into the stored query); page state resets, search_id stays. Params accept any subset of the request fields (HotelsSearchUpdateParams).
Record actions:
- details: Property description, nearby places, booking link.
Detail behaviour: First details call fetches from the provider (billed as stated); repeats are cached and free. details is a fresh provider property request: $0.004; repeated calls are cached.

record action

curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
  -H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
  -d '{"record_id":"rec_…","action":"details"}'

Record detail objects of this capability are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.

Typed client

With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:

TypeScript (openapi-fetch)

const { data, error } = await client.POST("/v1/capabilities/hotels.search/execute", {
  body: {
    "destination": "Lisbon",
    "check_in": "2026-10-09",
    "check_out": "2026-10-11",
    "adults": 2,
    "currency": "EUR",
    "sort": "highest_rating"
  },
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);