# Hotels — Wrapped API

> **You are on:** `https://api.beta.paywithlocus.com/api` | [llms.txt](https://beta.paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search for hotels across millions of properties, view room availability and pricing, and get detailed information about accommodations at specific destinations. Get location suggestions and discover popular travel spots to help plan your next getaway.

**Category:** Travel | **Website:** [hotels.com/](https://hotels.com/) | **Docs:** [parse.bot/marketplace/c5797080-c045-4b56-9836-584a59101dc1/hotels-com-api](https://parse.bot/marketplace/c5797080-c045-4b56-9836-584a59101dc1/hotels-com-api)

Pay-per-use API proxy for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.beta.paywithlocus.com/api/wrapped/credits/hotels-com/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## Endpoints

### Autocomplete destination

Suggest destination names as a user types a query string. Returns matching cities, airports, neighborhoods, and points of interest with their region IDs, coordinates, and types. Use the returned region ID as input to search_hotels.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search keyword for destination lookup (e.g. 'Istanbul', 'New York', 'Paris') |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hotels-com/autocomplete-destination \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```

### Get hotel details

Retrieve full details for a specific hotel property.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `property_id` | string | Yes | Hotel property ID |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hotels-com/get-hotel-details \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"property_id":"<string>"}'
```

### Get hotel rooms

Get available room types and pricing for a specific hotel.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `adults` | integer | No | Number of adults |
| `end_date` | string | Yes | Check-out date (YYYY-MM-DD) |
| `property_id` | string | Yes | Hotel property ID |
| `rooms` | integer | No | Number of rooms |
| `start_date` | string | Yes | Check-in date (YYYY-MM-DD) |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hotels-com/get-hotel-rooms \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"adults":"<integer>","end_date":"<string>","property_id":"<string>","rooms":"<integer>","start_date":"<string>"}'
```

### Get popular destinations

Retrieve a curated list of popular travel destinations with their region IDs. These IDs can be used directly with search_hotels without needing to call autocomplete_destination first.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hotels-com/get-popular-destinations \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### Search hotels

Search for hotels by destination and check-in/check-out dates. Returns up to 20 hotel listings sorted by recommendation, each with name, location, nightly and total pricing, guest rating, review summary, image URL, and a direct booking URL. The region_id is obtained from autocomplete_destination or get_popular_destinations. Dates must be in the future.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `adults` | integer | No | Number of adults per room |
| `end_date` | string | Yes | Check-out date in ISO format YYYY-MM-DD |
| `query` | string | Yes | Destination name (e.g. 'Istanbul', 'Paris, France') |
| `region_id` | string | Yes | Region ID from autocomplete_destination or get_popular_destinations (e.g. '2734' for Paris, '1639' for Istanbul) |
| `rooms` | integer | No | Number of rooms |
| `start_date` | string | Yes | Check-in date in ISO format YYYY-MM-DD |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hotels-com/search-hotels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"adults":"<integer>","end_date":"<string>","query":"<string>","region_id":"<string>","rooms":"<integer>","start_date":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://beta.paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://beta.paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://beta.paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://beta.paywithlocus.com/agent/index.md): every Locus agent page.