# Hotelscan — 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 and compare hotels with detailed guest reviews, room availability, and pricing information across flexible dates. Find similar properties, get autocomplete suggestions for locations, and access comprehensive hotel details all in one place.

**Category:** Travel | **Website:** [hotelscan.ai/](https://hotelscan.ai/) | **Docs:** [parse.bot/marketplace/33caef6a-0ff6-47fc-83dc-536a77c7215c/hotelscan-ai-api](https://parse.bot/marketplace/33caef6a-0ff6-47fc-83dc-536a77c7215c/hotelscan-ai-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/hotelscan/`
**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

### Get autocomplete suggestions

Search for destination or hotel suggestions by name. Returns matching cities, regions, and hotels with their IDs and metadata. Use city IDs as destination_id in other endpoints, and hotel IDs as hotel_id. Results include type (City, Hotel, Tag) to distinguish entity kinds.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Search query for destination or hotel name (e.g. 'Paris', 'Hilton New York'). |

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

### Get flexible dates prices

Get price calendar showing the cheapest prices for a hotel across a date range. Returns daily price entries for 2-night stays starting on each date, plus overall min/max prices for the range.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date_from` | string | Yes | Start date of the price range in YYYY-MM-DD format. |
| `date_to` | string | Yes | End date of the price range in YYYY-MM-DD format. |
| `hotel_id` | string | Yes | Hotel ID (e.g. '227955'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hotelscan/get-flexible-dates-prices \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"date_from":"<string>","date_to":"<string>","hotel_id":"<string>"}'
```

### Get hotel details

Get static hotel information including name, address, amenities, star category, coordinates, ratings, images, check-in/check-out info, descriptions, and service listings. Optionally pass dates and destination_id to also retrieve a pricing session.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date_from` | string | No | Check-in date in YYYY-MM-DD format. |
| `date_to` | string | No | Check-out date in YYYY-MM-DD format. |
| `destination_id` | string | No | Destination/city ID from get_autocomplete_suggestions (e.g. '139497'). |
| `hotel_id` | string | Yes | Hotel ID from get_autocomplete_suggestions (e.g. '227955'). |

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

### Get hotel reviews

Get guest reviews for a specific hotel. Returns reviews from multiple sources (Expedia, Hotels.com) with ratings, reviewer names, dates, and text. Supports pagination via offset/limit.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `hotel_id` | string | Yes | Hotel ID from get_autocomplete_suggestions or get_similar_hotels (e.g. '227955'). |
| `limit` | integer | No | Maximum number of reviews to return. |
| `offset` | integer | No | Pagination offset. |
| `sort` | string | No | Sort order for reviews. |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hotelscan/get-hotel-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"hotel_id":"<string>","limit":"<integer>","offset":"<integer>","sort":"<string>"}'
```

### Get hotel rooms

Get available room types and pricing for a hotel on specific dates. Returns room names, amenities, images, and pricing configurations including cancellation policies, meal plans, and supplier details. Requires hotel_id and date range; destination_id recommended for accurate pricing.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date_from` | string | Yes | Check-in date in YYYY-MM-DD format. |
| `date_to` | string | Yes | Check-out date in YYYY-MM-DD format. |
| `destination_id` | string | No | Destination/city ID from get_autocomplete_suggestions (e.g. '139497'). Recommended for accurate pricing. |
| `hotel_id` | string | Yes | Hotel ID (e.g. '227955'). |

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

### Get location destinations

Get popular featured hotel destinations from the homepage. Returns destination cards with city titles, images, starting prices, and links. No parameters required.

**Estimated cost:** Metered

_No parameters required._

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

### Get similar hotels

Get recommended similar hotels for a given hotel. Returns hotel name, star rating, guest rating, price, facilities, location, and gallery images. Requires destination_id and dates to return results with pricing.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date_from` | string | No | Check-in date in YYYY-MM-DD format. Recommended for pricing in results. |
| `date_to` | string | No | Check-out date in YYYY-MM-DD format. Recommended for pricing in results. |
| `destination_id` | string | No | Destination/city ID from get_autocomplete_suggestions (e.g. '139497'). Recommended for results. |
| `hotel_id` | string | Yes | Hotel ID (e.g. '227955'). |

```bash
curl -X POST https://api.beta.paywithlocus.com/api/wrapped/credits/hotelscan/get-similar-hotels \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"date_from":"<string>","date_to":"<string>","destination_id":"<string>","hotel_id":"<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.