# Hotelscan — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://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. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-hotelscan-ai-api-33caef6a/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## 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.paywithlocus.com/api/wrapped/parse-hotelscan-ai-api-33caef6a/get_autocomplete_suggestions \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-hotelscan-ai-api-33caef6a/get_flexible_dates_prices \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-hotelscan-ai-api-33caef6a/get_hotel_details \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-hotelscan-ai-api-33caef6a/get_hotel_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-hotelscan-ai-api-33caef6a/get_hotel_rooms \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-hotelscan-ai-api-33caef6a/get_location_destinations \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -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.paywithlocus.com/api/wrapped/parse-hotelscan-ai-api-33caef6a/get_similar_hotels \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date_from":"<string>","date_to":"<string>","destination_id":"<string>","hotel_id":"<string>"}'
```