> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dev.gojinko.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Hotel AI search

> Search hotels from the traveler's own words over REST: send one sentence, answer the questions it asks, refine with follow-ups, and book a result.

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.

> [!WARNING]
>
> Hotel AI search is in preview. The API may change.

## How it differs from hotel search

| | [`POST /v1/hotel_search`](https://docs.dev.gojinko.com/api/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](https://docs.dev.gojinko.com/guides/hotel-booking.md#search-by-intent).

## The flow

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Jinko
  App->>Jinko: POST /v1/hotel_ai_search {text, timezone}
  alt something is missing
    Jinko-->>App: 200 input_required + question
    App->>Jinko: POST /v1/hotel_ai_search {text: answer, context_id}
  end
  alt the search ends within 20 s
    Jinko-->>App: 200 completed + hotels
  else the search takes longer
    Jinko-->>App: 202 working + Location
    App->>Jinko: GET /v1/hotel_ai_search/tasks/{task_id}
    Jinko-->>App: 200 completed + hotels
  end
  App->>Jinko: POST /v1/trip {add_item: {trip_item_token}}
  App->>Jinko: POST /v1/checkout {trip_id}
```

1. **Send the sentence.** One call with `text` and the traveler's `timezone`.
2. **Answer questions.** An `input_required` answer carries a question; send the traveler's answer with the same `context_id`. See [Conversations](https://docs.dev.gojinko.com/ai/hotel-search/conversations.md).
3. **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](https://docs.dev.gojinko.com/ai/hotel-search/waiting-for-results.md).
4. **Refine.** "with a pool", "make it Porto instead", "show more": each follow-up goes in the same conversation.
5. **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:

```bash theme={null}
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`:

```bash theme={null}
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:

```json theme={null}
{
  "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](https://docs.dev.gojinko.com/ai/hotel-search/conversations.md#conversations-and-tasks). |
| `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](https://docs.dev.gojinko.com/ai/hotel-search/waiting-for-results.md).

## 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](https://docs.dev.gojinko.com/ai/hotel-search/statuses-and-errors.md). |
| `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`](https://docs.dev.gojinko.com/api/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](https://docs.dev.gojinko.com/ai/hotel-search/conversations.md#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.

```bash theme={null}
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](https://docs.dev.gojinko.com/guides/hotel-booking.md) for rooms, rates and cancellation terms, and [Trips and checkout](https://docs.dev.gojinko.com/guides/trips-and-checkout.md) for the rest of the booking.

## Next

* [Conversations](https://docs.dev.gojinko.com/ai/hotel-search/conversations.md): questions, follow-ups, corrections and expiry.
* [Waiting for results](https://docs.dev.gojinko.com/ai/hotel-search/waiting-for-results.md): `202`, reading the task, streaming, cancel and retries.
* [Statuses and errors](https://docs.dev.gojinko.com/ai/hotel-search/statuses-and-errors.md): every status, failure code and HTTP status.
* API reference: [`POST /v1/hotel_ai_search`](https://docs.dev.gojinko.com/api/hotel-ai-search).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.