# Hotel search with [hotels_search](../reference/hotels_search.md#serpapi_search_tools.hotels_search)

[hotels_search](../reference/hotels_search.md#serpapi_search_tools.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`](travel_explore_search.md) when the destination is still open, and [`maps_search`](maps_search.md) when the goal is local place discovery rather than date-specific lodging results.


# Quick example

``` python
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:

``` json
{
  "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](../reference/SearchResultMode.md#serpapi_search_tools.SearchResultMode.FULL) to keep supporting sections and all fields on retained results |
| `response_format` | `markdown` | Return Markdown by default, or use [SearchResultFormat.JSON](../reference/SearchResultFormat.md#serpapi_search_tools.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:

``` python
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

- [Google Hotels API](https://serpapi.com/google-hotels-api)

See [structured travel examples](examples.md) and the [trip-planning agent recipe](recipes.md).