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
The Hotels API finds hotels and vacation rentals in a location for a date range.
Each result includes a link to the property, the nightly and total price, every offer that meets
your filters, the star class, a rating tier, the address and coordinates, photos, amenities,
and check-in and check-out times.
Use the Hotels API when an agent or application needs to find, compare or recommend places to
stay: “a 4-star hotel near Union Square for three nights in December”, “a family
apartment in Kyoto under ¥20,000 a night”, or “hotels near the Eiffel Tower with free
cancellation”.
.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.1. Set Up Prerequisites
Generate your API key on Platform, then export it:requests (pip install requests).
2. Make Your First Hotels API Request
Send where to stay aslocation and the stay as check_in_date and check_out_date.
Guests default to 2 adults in 1 room.
Sample Request
The samples use fixed stay dates. The API rejects a check-in date that has passed, so replace them with future dates before you run them.Request Options
adults,children_ages,rooms: who is staying. Each room needs an adult.property_types:hotel,vacation_rental, or both (default).min_price,max_price: nightly price before taxes and fees, incurrency.min_rating,hotel_classes,free_cancellation: keep only properties that meet them.sort:relevance(default),priceorrating.currency: the currency of prices and price filters. Defaults toUSD.advanced_settings.max_results: up to 40 (default 20).
Sample Response
The API returns a JSON response with the following structure. Theresults array below is
shortened to one property. Fields that are not known for a
property, such as its star class, are left out.
Next Steps
- Best Practices: every request field, and how to write locations and filters
- Pricing: per-request cost
- Rate Limits: default quotas per product