Hotels APIhotels.com ↗
Search hotels by destination and dates, get room availability, retrieve property details, and discover popular destinations via the Hotels.com API.
What is the Hotels API?
The Hotels.com API gives developers access to 5 endpoints covering hotel search, room availability, property details, destination autocomplete, and popular destination lists. Starting with autocomplete_destination, you can resolve a free-text query like "Istanbul" into a structured region ID, then pass that ID directly to search_hotels to retrieve up to 20 hotel listings with nightly pricing, guest ratings, review summaries, and direct booking URLs.
curl -X GET 'https://api.parse.bot/scraper/fa8d38aa-36ba-45d4-8191-f30d2d2e3c46/autocomplete_destination?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 hotels-com-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.
from parse_apis.hotels_com_api import HotelsCom, Destination, PopularDestination, Hotel
client = HotelsCom()
# Step 1: List popular destinations to get region IDs
for dest in client.populardestinations.list():
print(dest.name, dest.id)
# Step 2: Autocomplete a destination to find its region ID
for result in client.destinations.search(query="Istanbul"):
print(result.name, result.type, result.lat, result.long)
# Step 3: Search hotels in Paris for upcoming dates
for hotel in client.hotels.search(
query="Paris",
region_id="2734",
start_date="2026-07-01",
end_date="2026-07-04",
adults=2,
rooms=1,
):
print(hotel.name, hotel.price_per_night, hotel.total_price, hotel.location)
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.
| Param | Type | Description |
|---|---|---|
| queryrequired | string | Search keyword for destination lookup (e.g. 'Istanbul', 'New York', 'Paris') |
{
"type": "object",
"fields": {
"destinations": "array of location objects each containing id, name, type, lat, long"
},
"sample": {
"data": {
"destinations": [
{
"id": "2734",
"lat": "48.853564",
"long": "2.348095",
"name": "Paris, France",
"type": "CITY"
},
{
"id": "6200422",
"lat": "48.862383",
"long": "2.339074",
"name": "Paris City Center, Paris, France",
"type": "NEIGHBORHOOD"
}
]
},
"status": "success"
}
}About the Hotels API
Searching Hotels
The search_hotels endpoint accepts a region_id (resolved via autocomplete_destination or get_popular_destinations), a destination name, check-in and check-out dates in YYYY-MM-DD format, and optional rooms and adults counts. Each result in the hotels array includes id, name, location, rating, reviews_text, price_per_night, total_price, image_url, and a url linking to the Hotels.com listing. Results are sorted by recommendation and capped at 20 properties per call.
Resolving Destinations
autocomplete_destination takes a partial query string and returns an array of location objects, each with an id, name, type (city, airport, neighborhood, or point of interest), and lat/long coordinates. The id field maps directly to the region_id parameter in search_hotels. get_popular_destinations provides a curated list of destination names and IDs with no input required, useful for bootstrapping destination pickers without a user query.
Property-Level Data
Once you have a hotel id from search results, get_hotel_details returns a full property detail object. get_hotel_rooms accepts the same property_id along with check-in/check-out dates and optional occupancy parameters, returning an array of available room types with associated pricing. Both endpoints return a status field alongside the data payload.
The Hotels API is a managed, monitored endpoint for hotels.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when hotels.com 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 hotels.com 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 price comparison tool using search_hotels nightly rates and total_price fields across multiple destinations.
- Power a destination autocomplete input with region IDs from autocomplete_destination for accurate hotel search results.
- Display a curated 'popular destinations' widget using get_popular_destinations without requiring user input.
- Show per-room pricing and availability for a selected property using get_hotel_rooms with specific check-in/check-out dates.
- Aggregate guest ratings and reviews_text from search_hotels results to rank hotels by traveler sentiment.
- Deep-link users directly to Hotels.com booking pages using the url field returned in hotel listings.
- Seed a travel app's destination database with region IDs and coordinates from autocomplete_destination results.
| 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.