---
title: "Search for hotels"
method: POST
path: "/api/actions/search"
---

# Search for hotels

`POST /api/actions/search`

Search for hotels using either natural language query or structured parameters. If dates are provided, returns live rates. Otherwise returns hotel metadata.

## Request body

- union
  - object — Natural language search
    - `query` string, required — Natural language search query (e.g., 'Hotels in Paris for 2 adults Dec 1-5'). Alternative to structured parameters.
    - `cityName` string — City name to search in
    - `countryCode` string — ISO 3166-1 alpha-2 country code (e.g., 'US', 'FR')
    - `checkin` string, date — Check-in date (YYYY-MM-DD). If provided with checkout, returns live rates.
    - `checkout` string, date — Check-out date (YYYY-MM-DD). If provided with checkin, returns live rates.
    - `occupancies` object[] — Guest configuration per room. Defaults to 1 adult if not provided.
      - `adults` integer, required — Number of adults in room
      - `children` integer[] — Ages of children in room
    - `currency` string — Currency code for pricing (e.g., 'USD', 'EUR', 'GBP')
    - `guestNationality` string — ISO 3166-1 alpha-2 country code of guest nationality
    - `minStars` integer — Minimum hotel star rating filter
    - `minRating` number — Minimum guest review rating (0-10)
    - `maxPrice` number — Maximum price per night filter
  - object — Structured search
    - `query` string — Natural language search query (e.g., 'Hotels in Paris for 2 adults Dec 1-5'). Alternative to structured parameters.
    - `cityName` string, required — City name to search in
    - `countryCode` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'FR')
    - `checkin` string, date — Check-in date (YYYY-MM-DD). If provided with checkout, returns live rates.
    - `checkout` string, date — Check-out date (YYYY-MM-DD). If provided with checkin, returns live rates.
    - `occupancies` object[] — Guest configuration per room. Defaults to 1 adult if not provided.
      - `adults` integer, required — Number of adults in room
      - `children` integer[] — Ages of children in room
    - `currency` string — Currency code for pricing (e.g., 'USD', 'EUR', 'GBP')
    - `guestNationality` string — ISO 3166-1 alpha-2 country code of guest nationality
    - `minStars` integer — Minimum hotel star rating filter
    - `minRating` number — Minimum guest review rating (0-10)
    - `maxPrice` number — Maximum price per night filter

## Response `200`

Search results

- SearchResponse
  - `items` Hotel[]
    - `id` string
    - `name` string
    - `stars` integer
    - `rating` number
    - `address` string
    - `city` string
    - `country` string
    - `latitude` number
    - `longitude` number
    - `thumbnail` string
    - `cheapestRate` object
      - `price` number
      - `currency` string
    - `bookingUrl` string, uri — Direct link to hotel details page with dates pre-filled
    - `galleryUrl` string, uri — Link to photo gallery and booking flow
  - `meta` object
    - `total` integer
    - `query` object
  - `facets` object

## Other responses

- `401` — Unauthorized - invalid or missing token
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/moodtrip/apis/moodtrip-actions-api.md) · [All operations](https://skmtc.net/moodtrip/apis/moodtrip-actions-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/moodtrip/moodtrip-actions-api/versions/61ea1b001dfa/schema)