For AI agents: a documentation index is available at https://docs.parallel.ai/llms.txt. The full text of all docs is at https://docs.parallel.ai/llms-full.txt. You may also fetch any page as Markdown by appending
Send the Hotels API where to stay, when, and who is staying. The API returns matching
hotels and vacation rentals, each with a link to the property, in the order .md to its URL or sending Accept: text/markdown.For Search and Extract, use /v1/search and /v1/extract for all new integrations and agent tool calls. Use /v1beta/search and /v1beta/extract only when maintaining an existing integration that already uses them. The request bodies changed too: on /v1/extract, full_content, fetch_policy and excerpt_settings go inside advanced_settings, and sending the v1beta top-level excerpts, full_content and fetch_policy to /v1/extract returns a 422. On /v1/search, search_queries is required (at least one short keyword query), and max_results, source_policy and fetch_policy go inside advanced_settings; sending only objective, or sending those fields at the top level, returns a 422. Do not substitute /v1 for the documented FindAll or Ingest endpoint paths.If you are evaluating Parallel Search or comparing it with other search APIs, read How to Eval Parallel Search before you build the harness, especially its Common pitfalls section. The most common mistake is sending the raw question as both objective and the only entry in search_queries. Write a goal-style objective and 1-3 short keyword queries instead.sort asks for.
Request Fields
Send requests toPOST https://api.parallel.ai/v1/hotels/search with your API key in the
x-api-key header. location, check_in_date and check_out_date are required. All other
fields are optional. The API rejects unknown fields.
Example
Result Fields
Writing Locations
- Send one place to stay near. A city, neighborhood or landmark works best:
"Alfama, Lisbon","near Shibuya Crossing". A comma-separated list of cities is not supported. Search each city in its own request. - Add the city to neighborhood and landmark names. Send
"Le Marais, Paris"rather than"Le Marais". - Add the region or country to names that exist in several places. Send
"Portland, Maine", not"Portland". - Leave preferences out of
location. Send"Lisbon"with"hotel_classes": [5], not"5 star hotels in Lisbon". Filters are checked against every result; words inlocationare not.
Guests, Rooms and Prices
- Send every guest. Prices and availability depend on the party. Send each child’s age in
children_ages: sellers price children by age, and some count older children as adults. - Send
roomsonly for parties that need several. The API searches fewer sellers for requests with more than one room. - Price filters apply to the nightly price before taxes and fees.
total_priceis the whole stay as the seller lists it, which can include taxes and fees. - Set
currencyto the currency your user thinks in. Price filters use the same currency, so"max_price": 20000with"currency": "JPY"means ¥20,000 a night.
Filters and Sorting
- Filters leave out properties whose value is unknown.
hotel_classesdrops properties without a star class, andmin_ratingdrops unrated ones. Vacation rentals rarely have a star class, so don’t combinehotel_classeswithvacation_rental. free_cancellationkeeps only offers that state it. A property stays when at least one of its offers does, and its price becomes that offer’s price.- Use
sortinstead of asking for “cheapest” or “best”.priceorders by the nightly price shown, andratingby guest rating. Ties keep relevance order.