---
title: "Semantic hotel search"
method: POST
path: "/api/actions/search-semantic"
---

# Semantic hotel search

`POST /api/actions/search-semantic`

Advanced semantic search using natural language queries to find hotels matching traveler intent, mood, and preferences. Returns hotels with relevance scores and semantic attributes.

## Request body

- SemanticSearchRequest
  - `query` string, required — Natural language search query (e.g., 'romantic getaway in Paris with spa', 'family-friendly beach resort in Bali')
  - `limit` integer — Maximum number of results to return
  - `includeRates` boolean — Include real-time pricing when dates are provided
  - `checkin` string, date — Check-in date (YYYY-MM-DD)
  - `checkout` string, date — Check-out date (YYYY-MM-DD)
  - `adults` integer — Number of adults
  - `children` integer[] — Ages of children
  - `currency` string — Currency code for pricing
  - `language` string — Language code for results
  - `guestNationality` string — ISO 3166-1 alpha-2 country code of guest nationality

## Response `200`

Semantic search results with relevance scores

- SemanticSearchResponse
  - `items` SemanticHotel[]
    - `id` string
    - `name` string
    - `stars` integer
    - `rating` number
    - `address` string
    - `city` string
    - `country` string
    - `latitude` number
    - `longitude` number
    - `thumbnail` string
    - `relevanceScore` number — Semantic relevance score (0-100)
    - `semanticAttributes` object — Extracted semantic attributes matching the query
    - `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` string
    - `semanticAnalysis` object
      - `mood` string
      - `travelType` string
      - `amenities` string[]

## 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)