> ## 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 Quickstart

> Find hotels and vacation rentals for a stay with 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.

The **Hotels API** finds hotels and vacation rentals in a location for a date range.
Each result includes a link to the property, the nightly and total price, every offer that meets
your filters, the star class, a rating tier, the address and coordinates, photos, amenities,
and check-in and check-out times.

Use the Hotels API when an agent or application needs to find, compare or recommend places to
stay: "a 4-star hotel near Union Square for three nights in December", "a family
apartment in Kyoto under ¥20,000 a night", or "hotels near the Eiffel Tower with free
cancellation".

## 1. Set Up Prerequisites

Generate your API key on [Platform](https://platform.parallel.ai), then export it:

```bash theme={"system"}
export PARALLEL_API_KEY="PARALLEL_API_KEY"
```

The Python example below uses `requests` (`pip install requests`).

## 2. Make Your First Hotels API Request

Send where to stay as `location` and the stay as `check_in_date` and `check_out_date`.
Guests default to 2 adults in 1 room.

### Sample Request

The samples use fixed stay dates. The API rejects a check-in date that has passed, so replace
them with future dates before you run them.

```bash cURL theme={"system"}
curl https://api.parallel.ai/v1/hotels/search \
  -H "Content-Type: application/json" \
  -H "x-api-key: $PARALLEL_API_KEY" \
  -d '{
    "location": "Union Square, San Francisco",
    "check_in_date": "2026-12-10",
    "check_out_date": "2026-12-13",
    "property_types": ["hotel"],
    "advanced_settings": {"max_results": 5}
  }'
```

```python Python theme={"system"}
import os

import requests

response = requests.post(
    "https://api.parallel.ai/v1/hotels/search",
    headers={"x-api-key": os.environ["PARALLEL_API_KEY"]},
    json={
        "location": "Union Square, San Francisco",
        "check_in_date": "2026-12-10",
        "check_out_date": "2026-12-13",
        "property_types": ["hotel"],
        "advanced_settings": {"max_results": 5},
    },
    timeout=60,
)
response.raise_for_status()

for hotel in response.json()["results"]:
    price = hotel.get("price_per_night")
    nightly = f"{price:.0f} {hotel['currency']}/night" if price else "no price"
    print(f"{hotel['name']} ({nightly}): {hotel['url']}")
    for offer in hotel["offers"]:
        seller = offer.get("seller", "unknown seller")
        print(f"  {seller}: {offer.get('price_per_night')} {offer['currency']}")
```

```typescript TypeScript theme={"system"}
async function main() {
    const response = await fetch("https://api.parallel.ai/v1/hotels/search", {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            "x-api-key": process.env.PARALLEL_API_KEY!,
        },
        body: JSON.stringify({
            location: "Union Square, San Francisco",
            check_in_date: "2026-12-10",
            check_out_date: "2026-12-13",
            property_types: ["hotel"],
            advanced_settings: { max_results: 5 },
        }),
    });
    if (!response.ok) {
        throw new Error(`Hotels API request failed: ${response.status} ${await response.text()}`);
    }

    const { results } = await response.json();
    for (const hotel of results) {
        const nightly = hotel.price_per_night
            ? `${hotel.price_per_night} ${hotel.currency}/night`
            : "no price";
        console.log(`${hotel.name} (${nightly}): ${hotel.url}`);
        for (const offer of hotel.offers) {
            console.log(`  ${offer.seller ?? "unknown seller"}: ${offer.price_per_night} ${offer.currency}`);
        }
    }
}

main().catch(console.error);
```

### Request Options

* `adults`, `children_ages`, `rooms`: who is staying. Each room needs an adult.
* `property_types`: `hotel`, `vacation_rental`, or both (default).
* `min_price`, `max_price`: nightly price before taxes and fees, in `currency`.
* `min_rating`, `hotel_classes`, `free_cancellation`: keep only properties that meet them.
* `sort`: `relevance` (default), `price` or `rating`.
* `currency`: the currency of prices and price filters. Defaults to `USD`.
* `advanced_settings.max_results`: up to 40 (default 20).

See [Best Practices](https://docs.parallel.ai/hotel-search/best-practices.md) for every request field.

### Sample Response

The API returns a JSON response with the following structure. The `results` array below is
shortened to one property. Fields that are not known for a
property, such as its star class, are left out.

```json theme={"system"}
{
  "search_id": "search_f936a91a59f8992f41b003cf771c702f",
  "session_id": "session_f936a91a59f8992f41b003cf771c702f",
  "results": [
    {
      "url": "https://www.axiomhotel.com/",
      "url_kind": "property_website",
      "name": "Axiom Hotel",
      "property_type": "hotel",
      "address": "28 Cyril Magnin Street, Union Square, San Francisco",
      "latitude": 37.7849078,
      "longitude": -122.40804820000001,
      "hotel_class": 4,
      "rating": "great",
      "price_per_night": 163.29,
      "total_price": 594.88,
      "currency": "USD",
      "free_cancellation": true,
      "offers": [
        {
          "seller": "Booking.com",
          "url": "https://www.booking.com/hotel/us/axiom.html?checkin=2026-12-10&checkout=2026-12-13&group_adults=2&no_rooms=1&group_children=0&lang=en-us&selected_currency=USD",
          "price_per_night": 163.29,
          "total_price": 594.88,
          "currency": "USD"
        },
        {
          "price_per_night": 179.0,
          "total_price": 536.0,
          "currency": "USD"
        },
        {
          "seller": "Airbnb",
          "url": "https://www.airbnb.com/rooms/1108091761465812573?check_in=2026-12-10&check_out=2026-12-13&adults=2",
          "price_per_night": 200.67,
          "total_price": 726.0,
          "currency": "USD",
          "free_cancellation": true
        }
      ],
      "images": [
        "https://cf.bstatic.com/xdata/images/hotel/square600/76263893.jpg?k=a8b7d19d16aba95e9e442cbc4a1a40df87c31b366d6fbd7add99f54de42885f3&o="
      ],
      "amenities": ["Breakfast ($)", "Free Wi-Fi", "Parking ($)", "Air conditioning", "Pet-friendly", "Fitness center", "Bar", "Restaurant", "Room service", "Accessible", "Business center", "Smoke-free property"],
      "check_in_time": "3:00 PM",
      "check_out_time": "12:00 PM"
    }
  ],
  "usage": [{"name": "sku_search", "count": 1}]
}
```

See [Result Fields](https://docs.parallel.ai/hotel-search/best-practices.md#result-fields) for how to read each field.

## Next Steps

* **[Best Practices](https://docs.parallel.ai/hotel-search/best-practices.md)**: every request field, and how to write locations and filters
* **[Pricing](https://docs.parallel.ai/getting-started/pricing.md#hotels-api)**: per-request cost
* **[Rate Limits](https://docs.parallel.ai/getting-started/rate-limits.md)**: default quotas per product
