Hotel AI search

Hotel AI search takes the traveler’s request as written, for example “find me an hotel for my wife birthday near the beach 1h away from San francisco driving next weekend”, and answers with the hotels that match and a reply to show. A place described by its distance from a city, like the beaches within an hour’s drive of San Francisco, is searched as the areas that fit. When something is missing, the answer asks for it. The traveler can then refine the search in the same conversation.

Hotel AI search is in preview. The API may change.

How it differs from hotel search

	`POST /v1/hotel_search`	`POST /v1/hotel_ai_search`
Input	Structured fields: destination, dates, occupancy, filters.	The traveler’s sentence, as `text`.
Missing information	`422` for a missing required field.	A question to show the traveler (`status: "input_required"`).
Follow-ups	Each call stands alone.	A conversation (`context_id`) keeps what was said, so “with a pool” refines the last search.
Results	Hotels with offers.	The same hotel and offer objects, plus `message`, `criteria` and `notes`.
Booking	`trip_item_token` → trip → checkout.	The same.

hotel_search can also rank by the traveler’s wording; see Search by intent.

The flow

Send the sentence. One call with text and the traveler’s timezone.
Answer questions. An input_required answer carries a question; send the traveler’s answer with the same context_id. See Conversations.
Get the hotels. Most searches answer 200 within 20 seconds. A longer one answers 202; read the task until it ends, or stream it. See Waiting for results.
Refine. “with a pool”, “make it Porto instead”, “show more”: each follow-up goes in the same conversation.
Book. Add an offer’s trip_item_token to a trip and check out, as for any hotel.

Quickstart

Hotel AI search is served on production only, at https://api.gojinko.com, with a production API key; the sandbox does not serve it. The request is the traveler’s own words, as they typed them:

curl https://api.gojinko.com/v1/hotel_ai_search \
  --header "X-API-Key: $JINKO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "text": "find me an hotel for my wife birthday near the beach 1h away from San francisco driving next weekend",
    "timezone": "America/Los_Angeles"
  }'

The search is still running after 20 seconds, so the call answers 202 with the task to read (Location, Retry-After: 2) and the early reply in message: Searching hotels in San Francisco for Oct 31 – Nov 1 (1 night, 2 adults, 1 room). Results are on the way. Read the task until status is no longer working:

curl https://api.gojinko.com/v1/hotel_ai_search/tasks/atk_mvtxc0ev86b6eba18717ed1e \
  --header "X-API-Key: $JINKO_API_KEY"

The answer, with one hotel and one offer kept. “Next weekend” became October 31 to November 1, “my wife” two adults, and the beaches within an hour’s drive of San Francisco the areas searched:

{
  "context_id": "ctx_mvtxc0er7e2a605ae8496ce4",
  "task_id": "atk_mvtxc0ev86b6eba18717ed1e",
  "status": "completed",
  "message": "Found 20 hotels in 6 areas (Half Moon Bay, Pacifica, Stinson Beach, Bolinas, Muir Beach, Pescadero and 1 more) for Oct 31 – Nov 1 (1 night, 2 adults, 1 room), sorted by how well they fit: suitable for a birthday celebration, near the beach. More are available.",
  "criteria": {
    "intent": {
      "user_intent": "near the beach, 1 hour away from San Francisco driving, for wife's birthday"
    },
    "checkin": "2026-10-31",
    "checkout": "2026-11-01",
    "city_name": "San Francisco",
    "occupancies": [
      {
        "adults": 2,
        "children_ages": []
      }
    ],
    "country_code": "US"
  },
  "notes": [],
  "hotels": [
    {
      "hotel_id": "lp63728",
      "name": "Casablanca Inn on The Beach",
      "address": "101 Main Street",
      "city": "Santa Cruz",
      "country": "us",
      "star_rating": 4,
      "rating": 8,
      "review_count": 2646,
      "latitude": 36.963462829589844,
      "longitude": -122.02234649658203,
      "distance_km": 1.3175047503989186,
      "match_score": 67,
      "offers": [
        {
          "trip_item_token": "htl_7bbcee8530cc1d33",
          "board_type": "RO",
          "board_name": "Room Only",
          "total_amount": 185.96,
          "currency": "USD",
          "is_refundable": false,
          "payment_types": [
            "pay_now"
          ],
          "room_rates": [
            {
              "room_id": "1459983307",
              "room_name": "Newly Renovated 2 Queens, Street View",
              "occupancy": {
                "adults": 2
              },
              "board_type": "RO",
              "is_refundable": false
            }
          ]
        }
      ]
    }
  ],
  "has_more": true,
  "charge": {
    "turn": 1,
    "llm_usd": 0.026658,
    "api_usd": 0.168,
    "total_usd": 0.194658,
    "currency": "USD"
  }
}

The request

Field	Required	Meaning
`text`	Yes	The traveler’s message, 1 to 2000 characters: a request, an answer to a question, or a follow-up.
`timezone`	Yes	The traveler’s IANA time zone, such as `Europe/Paris`. Relative dates (“next weekend”, “tonight”) are computed in it.
`context_id`	No	The conversation to continue, from an earlier answer. Omit it to start a new one.
`task_id`	No	The task of that conversation the message answers. Usually omitted; see Conversations.
`currency`	No	The currency of the prices, ISO 4217 (`EUR`).
`guest_nationality`	No	The guests’ nationality, ISO 3166-1 alpha-2 (`FR`). It can change the rates offered.

Optional headers: Prefer: wait=N to change the 20-second wait, Accept: text/event-stream to stream, and Idempotency-Key to retry safely. See Waiting for results.

The answer

Field	Meaning
`context_id`	The conversation. Send it with the traveler’s next message.
`task_id`	This search. Use it to read, stream or cancel it.
`status`	`working`, `input_required`, `completed`, `failed` or `canceled`. See Statuses and errors.
`message`	The reply to show the traveler, in English. It says what was searched and which filters applied.
`question`	With `input_required`: what is missing, one of `destination`, `checkin_checkout`, `children_ages`, `guests`, `checkout`.
`criteria`	What was searched, in the `hotel_search` request fields, plus `board_types` and `refundable_only`, the rate filters applied.
`notes`	Assumptions and changes, such as conditions kept from before. See Notes.
`hotels`	The hotels, in the same format as `hotel_search`. Each offer only has rates that meet `board_types` and `refundable_only`. A budget holds a hotel by its cheapest rate, so a hotel can also show rates above it.
`has_more`	More hotels match; the traveler can ask for more in the same conversation.
`reference`	`true` when the hotels are a one-night price reference shown while the check-out date is asked.
`error`	With `failed`: `code` and `message`.
`superseded_by`	With `canceled`: the task that replaced this one.

What the search understands

The traveler says	In `criteria`	What comes back
A city: “in Lisbon”	`city_name`, `country_code`	Hotels in the city.
A landmark, district or station: “near the Louvre”	`query`, such as `"Louvre, Paris, FR"`, in place of `city_name`	Hotels around that point; the reply says `within N km of`.
One hotel by its name: “Is the Hoxton Shoreditch available 14–16 Nov for two?”	`query` with the hotel’s name	The reply says first whether that hotel has rooms for the stay; with rooms that meet the other conditions it comes first in `hotels`, followed by the hotels around it. `notes` says the same (`requested_hotel`).
Dates: “from Nov 20 to 22”, “next weekend”, “3 nights from Friday”	`checkin`, `checkout`	Offers for the stay.
Days of the week in a period: “a long weekend in early December”, “a weekend in March”, “arriving on a Friday in May”	`checkin`, `checkout`	Offers for the first stay that fits: a long weekend starts on a Thursday or Friday for 3 nights, a weekend on a Saturday for 1 night. `notes` says so (`first_stay_of_period`). A period alone (“3 nights in December”) asks for the dates.
Guests and rooms: “2 adults and a child of 5”, “2 rooms”	`occupancies`, one entry per room, with `children_ages`	Offers for these guests and rooms. Each room needs one adult.
Star rating: “4-star”, “3 to 4 stars”	`min_star_rating`, `max_star_rating`	Only hotels in that range. Star ratings are whole numbers: “3.5 stars or better” is searched as 4 stars or more, and `notes` says so (`star_rating_whole`).
Guest rating: “rated 8 or more”	`min_rating` (0 to 10)	Only hotels rated at least that.
Budget: “under €200 a night”, “€600 in total”	`max_budget_per_night`	Only hotels whose cheapest rate is within the budget, per night and room. Such a hotel keeps its other rates, and `notes` says so when some are above the budget (`budget_by_cheapest_rate`). A total budget is applied per night and room, and `notes` says so.
Meals: “with breakfast”, “half board”, “room only”	`board_types`	Only rates with one of these boards.
Cancellation: “refundable”	`refundable_only: true`	Only refundable rates.
Facilities: “with a pool and parking”	`facility_ids`	Only hotels with every facility named.
Property type: “an apartment”, “a resort”	`hotel_type_ids`	Only hotels of that type.
Brand: “a Hilton”	`chain_ids`	Only hotels of that brand.
Preferences without a fixed value: “quiet”, “romantic”, “near the beach”	Not a filter	The order of the hotels; the reply then says `sorted by how well they fit: …`.

Requests in English, French and Chinese are understood. message is always in English; translate it in your app if your traveler reads another language.

Book a result

A result is booked like any hotel offer: add its trip_item_token to a trip, add the travelers and contact, then check out.

curl https://api.gojinko.com/v1/trip \
  --header "X-API-Key: $JINKO_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"add_item": {"trip_item_token": "htl_d7018711c5d84b0a"}}'

total_amount is the price of the offer for the whole stay, in currency. Offers of a reference: true answer cover one night only. See Hotels for rooms, rates and cancellation terms, and Trips and checkout for the rest of the booking.

Conversations: questions, follow-ups, corrections and expiry.
Waiting for results: 202, reading the task, streaming, cancel and retries.
Statuses and errors: every status, failure code and HTTP status.
API reference: POST /v1/hotel_ai_search.

Getting started

Guides

AI

Marketing claim

Authentication

Connect

Developer Platform

Concepts

How it differs from hotel search

The flow

Quickstart

The request

The answer

What the search understands

Book a result

Next

​How it differs from hotel search

​The flow

​Quickstart

​The request

​The answer

​What the search understands

​Book a result

​Next

How it differs from hotel search

The flow

Quickstart

The request

The answer

What the search understands

Book a result

Next