> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parallel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotels API Best Practices

> Request fields, locations, guests and filters for the Parallel Hotels API

For AI agents: a documentation index is available at [https://docs.parallel.ai/llms.txt](https://docs.parallel.ai/llms.txt). The full text of all docs is at [https://docs.parallel.ai/llms-full.txt](https://docs.parallel.ai/llms-full.txt). You may also fetch any page as Markdown by appending `.md` to its URL or sending `Accept: text/markdown`.

For Search and Extract, use `/v1/search` and `/v1/extract` for all new integrations and agent tool calls. Use `/v1beta/search` and `/v1beta/extract` only when maintaining an existing integration that already uses them. The request bodies changed too: on `/v1/extract`, `full_content`, `fetch_policy` and `excerpt_settings` go inside `advanced_settings`, and sending the v1beta top-level `excerpts`, `full_content` and `fetch_policy` to `/v1/extract` returns a 422. On `/v1/search`, `search_queries` is required (at least one short keyword query), and `max_results`, `source_policy` and `fetch_policy` go inside `advanced_settings`; sending only `objective`, or sending those fields at the top level, returns a 422. Do not substitute `/v1` for the documented FindAll or Ingest endpoint paths.

If you are evaluating Parallel Search or comparing it with other search APIs, read [How to Eval Parallel Search](https://docs.parallel.ai/search/evaluating-search.md) before you build the harness, especially its [Common pitfalls](https://docs.parallel.ai/search/evaluating-search.md#common-pitfalls) section. The most common mistake is sending the raw question as both `objective` and the only entry in `search_queries`. Write a goal-style `objective` and 1-3 short keyword queries instead.

Send the Hotels API where to stay, when, and who is staying. The API returns matching
hotels and vacation rentals, each with a link to the property, in the order `sort` asks for.

## Request Fields

Send requests to `POST https://api.parallel.ai/v1/hotels/search` with your API key in the
`x-api-key` header. `location`, `check_in_date` and `check_out_date` are required. All other
fields are optional. The API rejects unknown fields.

| Field | Type | Notes | Example |
| - | - | - | - |
| location | string | Where to stay: a city, neighborhood, landmark or address. 2 to 200 characters. One location per request. | `"Lisbon"`, `"Shinjuku, Tokyo"`, `"near the Eiffel Tower"` |
| check\_in\_date | date | `YYYY-MM-DD`. Must not have passed. | `"2026-12-10"` |
| check\_out\_date | date | `YYYY-MM-DD`. After `check_in_date`, and at most 30 nights later. | `"2026-12-13"` |
| adults | int | Adult guests, 1 to 16. Defaults to 2. | `2` |
| children\_ages | int\[] | The age of each child guest, 0 to 17. Up to 8 children. | `[4, 9]` |
| rooms | int | Rooms to book, 1 to 8. Each room needs an adult. Defaults to 1. | `2` |
| property\_types | string\[] | `hotel` (hotels, hostels, inns) and `vacation_rental` (homes and apartments). Defaults to both. | `["vacation_rental"]` |
| min\_price, max\_price | number | Nightly price before taxes and fees, in `currency`. | `80`, `250` |
| min\_rating | number | Lowest guest rating, from 1 to 5. Properties without a rating are left out. | `4` |
| hotel\_classes | int\[] | Star classes to keep, 1 to 5. Properties without a class are left out. | `[4, 5]` |
| free\_cancellation | boolean | Only offers that state free cancellation. Defaults to `false`. | `true` |
| sort | string | `relevance` (default), `price` (lowest nightly price first) or `rating` (highest first). | `"price"` |
| currency | string | ISO 4217 code for prices and price filters. Defaults to `USD`. | `"EUR"` |
| advanced\_settings.max\_results | int | Maximum number of results, from 1 to 40. Defaults to 20. A search can return fewer when fewer properties match. Values above 40 are reduced to 40 with a warning. | `40` |
| session\_id | string | A string that groups related calls for one task. Up to 1000 characters. The API returns the value you provide, or generates one when you omit it. | `"session_<uuid>"` |
| client\_model | string | The model that creates the request and consumes the results. | `"claude-opus-5"` |

### Example

```json theme={"system"}
{
  "location": "Kyoto",
  "check_in_date": "2026-12-10",
  "check_out_date": "2026-12-13",
  "adults": 2,
  "children_ages": [6],
  "property_types": ["hotel"],
  "max_price": 20000,
  "currency": "JPY",
  "hotel_classes": [4, 5],
  "free_cancellation": true,
  "sort": "price"
}
```

## Result Fields

| Field | Notes |
| - | - |
| url, url\_kind | A page for this property. `url_kind` says which: `property_website` for the property's own site, or `booking_page` for a booking site's page for these dates. |
| name, property\_type | The property's name, and `hotel` or `vacation_rental`. |
| address, latitude, longitude | Where the property is, when known. |
| hotel\_class | Star class, 1 to 5, when known. |
| rating | Guest rating tier: `fair`, `good`, `great` or `excellent`. |
| price\_per\_night, total\_price, currency | The cheapest offer that meets your filters. |
| free\_cancellation | `true` if any offer states free cancellation, `false` if every offer states none. Left out when unknown. |
| offers | Every offer that meets your filters, cheapest first: `seller`, `url`, `price_per_night`, `total_price`, `currency`, `free_cancellation`. An offer without `seller` or `url` is a listed price that no single booking page backs. |
| images | Up to 5 photo URLs from one booking site, often just one. They can stop working, so do not store them. Empty when there are none. |
| amenities, check\_in\_time, check\_out\_time | As the property lists them. |

## Writing Locations

* **Send one place to stay near.** A city, neighborhood or landmark works best:
  `"Alfama, Lisbon"`, `"near Shibuya Crossing"`. A comma-separated list of cities is not
  supported. Search each city in its own request.
* **Add the city to neighborhood and landmark names.** Send `"Le Marais, Paris"` rather than
  `"Le Marais"`.
* **Add the region or country to names that exist in several places.** Send
  `"Portland, Maine"`, not `"Portland"`.
* **Leave preferences out of `location`.** Send `"Lisbon"` with `"hotel_classes": [5]`, not
  `"5 star hotels in Lisbon"`. Filters are checked against every result; words in `location`
  are not.

## Guests, Rooms and Prices

* **Send every guest.** Prices and availability depend on the party. Send each child's age in
  `children_ages`: sellers price children by age, and some count older children as adults.
* **Send `rooms` only for parties that need several.** The API searches fewer sellers for
  requests with more than one room.
* **Price filters apply to the nightly price before taxes and fees.** `total_price` is the
  whole stay as the seller lists it, which can include taxes and fees.
* **Set `currency` to the currency your user thinks in.** Price filters use the same currency,
  so `"max_price": 20000` with `"currency": "JPY"` means ¥20,000 a night.

## Filters and Sorting

* **Filters leave out properties whose value is unknown.** `hotel_classes` drops properties
  without a star class, and `min_rating` drops unrated ones. Vacation rentals rarely have a
  star class, so don't combine `hotel_classes` with `vacation_rental`.
* **`free_cancellation` keeps only offers that state it.** A property stays when at least one
  of its offers does, and its price becomes that offer's price.
* **Use `sort` instead of asking for "cheapest" or "best".** `price` orders by the nightly
  price shown, and `rating` by guest rating. Ties keep relevance order.

## Handling Errors

| Status | When |
| - | - |
| `400` | The stay cannot be searched: the check-in date has passed or is more than 500 days ahead. Also returned when the Hotels API is not available for your organization's data retention settings. The message says which. |
| `422` | The request is invalid: for example, `check_out_date` is not after `check_in_date`, the stay is longer than 30 nights, a room has no adult, or `min_price` is above `max_price`. |
