Hotelscan APIhotelscan.ai ↗
Access hotel details, room availability, guest reviews, flexible date pricing, and destination suggestions from hotelscan.com via 7 structured endpoints.
What is the Hotelscan API?
The Hotelscan API gives developers access to 7 endpoints covering hotel search, room availability, guest reviews, flexible date pricing, and destination discovery from hotelscan.com. Starting with get_autocomplete_suggestions, you can resolve a city or hotel name to structured IDs, then chain those IDs into endpoints for room configurations, cancellation policies, and multi-source review aggregates — all returning structured JSON.
curl -X GET 'https://api.parse.bot/scraper/e9948ea1-eeaf-4018-8997-fd134e61ab9f/get_autocomplete_suggestions?query=Paris' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace hotelscan-ai-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: HotelScan SDK — search destinations, drill into hotels, compare pricing."""
from parse_apis.hotelscan_api import HotelScan, ReviewSort, HotelNotFound
client = HotelScan()
# Search for destinations/hotels by name — typed field access on results.
for suggestion in client.suggestions.search(query="Paris", limit=5):
print(suggestion.name, suggestion.type, suggestion.country_code)
# Drill into a specific hotel by ID (constructible).
hotel = client.hotel(hotel_id="227955")
# Get reviews — sorted newest first, capped at 3.
for review in hotel.reviews.list(sort=ReviewSort.DATE_DESC, limit=3):
print(review.name, review.rating, review.submit_date)
# Check room availability and pricing for specific dates.
room = hotel.rooms.list(date_from="2026-07-01", date_to="2026-07-03", destination_id="139497", limit=1).first()
if room:
print(room.name, room.room_id)
# Browse similar hotels in the area with pricing.
for similar in hotel.similar.list(destination_id="139497", date_from="2026-07-01", date_to="2026-07-03", limit=3):
print(similar.hotel_name, similar.stars, similar.price, similar.rating)
# Price calendar — find cheapest dates over a range.
for entry in hotel.prices.list(date_from="2026-07-01", date_to="2026-07-30", limit=5):
print(entry.date, entry.price, entry.is_past_date)
# Typed error handling for missing hotel.
try:
bad_hotel = client.hotels.get(hotel_id="9999999999")
print(bad_hotel.name)
except HotelNotFound as exc:
print(f"Hotel not found: {exc}")
# Featured destinations from the homepage.
for dest in client.destinations.list(limit=3):
print(dest.title, dest.button_label)
print("exercised: suggestions.search / hotel.reviews.list / hotel.rooms.list / hotel.similar.list / hotel.prices.list / hotels.get / destinations.list")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.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search query for destination or hotel name (e.g. 'Paris', 'Hilton New York'). |
{
"type": "object",
"fields": {
"items": "array of suggestion objects with id, name, type, additionalInfo, countryCode, imageUrl",
"hasResults": "boolean indicating whether any results were found"
},
"sample": {
"data": {
"items": [
{
"id": "139497",
"name": "Paris",
"type": "City",
"imageUrl": "https://res.cloudinary.com/lastminute-contenthub/image/upload/c_lfill,w_100,h_100,f_auto,q_auto:eco/v1/DAM/Artwork/SEM Pages/Dynamic template hero/paris-spring.jpg",
"countryCode": "FR",
"additionalInfo": "France"
}
],
"hasResults": true
},
"status": "success"
}
}About the Hotelscan API
Hotel Search and Static Details
get_autocomplete_suggestions accepts a free-text query (city name, region, or hotel name) and returns an array of suggestion objects, each with an id, name, type, countryCode, and imageUrl. The returned id values feed directly into every other endpoint. get_hotel_details uses a hotel_id and optional date_from/date_to to return both a static block — covering name, address, amenities, category, coordinates, images, hotelOpinion, descriptionMap, and serviceMap — and a pricing object when dates are supplied.
Room Availability and Pricing
get_hotel_rooms requires hotel_id, date_from, and date_to, and optionally a destination_id for accurate pricing. It returns a selectedHotel object containing a rooms array where each entry includes the room name, amenities, images, and configurations — the configurations hold per-booking pricing and cancellation policy details. The response also surfaces a currency code and a pricingId for the session. get_flexible_dates_prices covers a broader date window, returning a products array of daily price entries with date, price, and availability info, plus range-level minPrice and maxPrice.
Reviews and Similar Hotels
get_hotel_reviews returns a data object containing a reviews array (with reviewer names, ratings, and text), totalReviewsCount, displayedReviewsCount, and sources indicating which review providers contributed. Optional sort (supports date_desc), limit, and offset parameters allow basic pagination. get_similar_hotels returns comparable properties with fields including hotel_name, stars, rating, reviews_num, hotel_address, price, and internal_id_hotel — the last of which can be fed back into detail or review endpoints.
Destination Discovery
get_location_destinations requires no inputs and returns the cardData array from hotelscan.com's featured destinations feed. Each card carries a title, image, buttonLabel (which displays a price), and an anchor with link metadata. A feedName field and hasMoreData boolean round out the response.
The Hotelscan API is a managed, monitored endpoint for hotelscan.ai — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hotelscan.ai changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official hotelscan.ai API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Build a hotel search widget that resolves typed city or property names to IDs using get_autocomplete_suggestions before fetching prices.
- Display a price calendar for flexible travelers by querying get_flexible_dates_prices across a 30-day window to show cheapest available nights.
- Aggregate guest sentiment by pulling multi-source reviews via get_hotel_reviews sorted by most recent date.
- Compare room types and cancellation policies side-by-side using the configurations array from get_hotel_rooms.
- Populate a 'similar hotels' recommendation panel with star ratings, guest scores, and starting prices from get_similar_hotels.
- Generate destination landing pages with featured cards, display prices, and imagery from get_location_destinations.
- Cache and display static hotel metadata (amenities, coordinates, images, descriptions) using get_hotel_details without requiring date inputs.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.