Hotel search with hotels_search

hotels_search searches Google Hotels for a destination and stay window. It asks for check-in and check-out dates so the results can include relevant availability and prices.

When to use it

Use it when the agent needs properties, rates, availability, amenities, or hotel comparisons for a known destination and stay window.

Choose travel_explore_search when the destination is still open, and maps_search when the goal is local place discovery rather than date-specific lodging results.

Quick example

from serpapi_search_tools import hotels_search

hotel_tool = hotels_search(
    default_params={"currency": "USD", "gl": "us"},
)
agent_tools = [hotel_tool]

An agent invocation has a structured shape:

{
  "query": "hotels in Kyoto",
  "check_in_date": "2030-08-01",
  "check_out_date": "2030-08-04",
  "adults": 2,
  "children": 1,
  "children_ages": [8]
}

Inputs the agent can provide

Field Type Required Default and constraints
query string yes Hotel name, city, region, or destination
check_in_date date string yes Future date in YYYY-MM-DD format
check_out_date date string yes YYYY-MM-DD, strictly after check-in
adults integer no 2; at least 1
children integer no 0; when greater than zero, provide one matching children_ages value per child
children_ages list of integers no Required when children > 0; exactly one age from 1 through 17 per child; use 1 for a child under one year and omit when children=0

Configure the tool

Constructor option Default Use it for
provider "auto" Detect one installed SDK or select one explicitly
default_params None Fix currency, locale, country, or supported property filters
mode compact Return the main property result section; use SearchResultMode.FULL to keep supporting sections and all fields on retained results
response_format markdown Return Markdown by default, or use SearchResultFormat.JSON for structured fields
result_limit 20 Maximum properties retained in either mode
api_key None Override environment key lookup
timeout None Set the built-in client timeout
client None Add caching, request logging, or deterministic tests
include_examples True Add a stay-search hint to the model description
name "hotels_search" Distinguish region- or policy-specific hotel tools

Useful SerpApi parameters

Keep currency and locale under application control:

from serpapi_search_tools import hotels_search

us_hotel_prices = hotels_search(
    default_params={"currency": "USD", "gl": "us", "hl": "en"},
    name="us_hotel_prices",
)

Google Hotels supports additional property type, rating, hotel class, amenities, offers, and sorting filters. Check the official reference for exact names and values. Dates and occupancy should use the typed model inputs above, not duplicate values in default_params.

What comes back

Both modes return up to result_limit properties (20 by default). Compact entries include useful property details such as names, links, coordinates, ratings, amenities, prices, rates, and a preview image. Use full mode when application code needs supporting response sections or additional property fields. Add result_limit=None to keep every returned property.

Common mistakes

  • Omitting check-in or check-out dates.
  • Using a checkout date equal to or before check-in.
  • Providing children=1 without one children_ages value.
  • Using a child age outside 1 through 17.
  • Using age 0 for a child under one year; Google Hotels represents that age as 1.
  • Leaving old example dates in production code. Send real future stay dates.
  • Assuming a displayed rate includes every fee; inspect the returned price fields and source information.

Official SerpApi documentation

See structured travel examples and the trip-planning agent recipe.