Skip to main content
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 .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.
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”.

1. Set Up Prerequisites

Generate your API key on Platform, then export it:
The Python example below uses requests (pip install requests).

2. Make Your First Hotels API Request

Send where to stay as location 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, in currency.
  • min_rating, hotel_classes, free_cancellation: keep only properties that meet them.
  • sort: relevance (default), price or rating.
  • currency: the currency of prices and price filters. Defaults to USD.
  • advanced_settings.max_results: up to 40 (default 20).
See Best Practices for every request field.

Sample Response

The API returns a JSON response with the following structure. The results array below is shortened to one property. Fields that are not known for a property, such as its star class, are left out.
See Result Fields for how to read each field.

Next Steps