Staylist World

Use when the user wants hotel recommendations or wants hotels compared. Returns up to 20 hotels compared on the same criteria, each with area, nearest station, amenities and price where known; empty fields mean unknown, not bad. shortlist_url is a page you can share with the user comparing the top results side by side. Find hotels by city, name or preferences (query words also match amenities, e.g. "pool", "breakfast"). Cities in Staylist's catalogue return hotels that each have an approved partner booking link (Trip.com, Klook), with a score (Staylist AI score, or the Trip.com guest rating where there is none; see sample_estimate.score_source), star class, amenities, check-in/out times and nearby transport where collected, pros and cons, and a sample_estimate (a previously observed nightly price, not a quote for the dates). Other cities use a live provider with indicative prices for an explicit stay. Supply both dates or neither. One room, 1–8 adults and up to 6 children. Use get_booking_link for the traveler's link. Never send names, email addresses or payment details.

{
  "type": "object",
  "properties": {
    "city": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "country_code": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$"
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "checkin": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Calendar date in YYYY-MM-DD format; provide both dates or neither"
    },
    "checkout": {
      "$ref": "#/properties/checkin",
      "description": "Calendar date in YYYY-MM-DD format; provide both dates or neither"
    },
    "adults": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8,
      "default": 2
    },
    "children_ages": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 17
      },
      "maxItems": 6
    },
    "min_rating": {
      "type": "number",
      "minimum": 0,
      "maximum": 10
    },
    "max_price_per_night": {
      "type": "number",
      "exclusiveMinimum": 0
    },
    "stars": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 1,
        "maximum": 5
      },
      "minItems": 1,
      "maxItems": 5
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "default": 10
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Hotel details: address, star class, amenities, Staylist's AI overview (a written summary with pros, cons and who the hotel suits, where one exists), how the hotel compares with others in its city, check-in/out times, child policy, the hotel's own published policies (including whether it accepts guests from all countries, which matters for foreigners in mainland China), nearest airport/station, and booking links. No photos: people see those on the booking page; for live-provider hotels also booking-site offers for the requested dates and guests (total, room, cancellation, conditions). refundable=null means unknown. Prices are not guaranteed. Preserve dates and occupancy from the search.

{
  "type": "object",
  "properties": {
    "hotel_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Exact hotel id returned by search_hotels"
    },
    "checkin": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Calendar date in YYYY-MM-DD format; provide both dates or neither"
    },
    "checkout": {
      "$ref": "#/properties/checkin",
      "description": "Calendar date in YYYY-MM-DD format; provide both dates or neither"
    },
    "adults": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8,
      "default": 2
    },
    "children_ages": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 17
      },
      "maxItems": 6
    }
  },
  "required": [
    "hotel_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Guest reviews for one hotel from the last 24 months (up to 1,000, newest first), via Staylist's booking partner LiteAPI (Nuitée booking guests and Tripadvisor). Returns how many were 1–2 star (a score of 4 or less out of 10) and the texts of those bad reviews, so the traveler can see what went wrong for other guests before booking; with only_bad=false also the most recent reviews of any score. Quote or summarise faithfully, say how many reviews the count is out of, and do not present a few bad reviews as typical when they are a small share. Reviewer names are not included. available=false means no reviews from this source; nearby_with_reviews then lists close hotels (ids, km) whose reviews can be read instead.

{
  "type": "object",
  "properties": {
    "hotel_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Exact hotel id returned by search_hotels"
    },
    "only_bad": {
      "type": "boolean",
      "description": "Default true: only the 1–2 star reviews"
    }
  },
  "required": [
    "hotel_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Return the approved booking links for a hotel (the same links shown to people on staylist.world) plus the Staylist hotel page. Property links open the exact hotel on Trip.com or Klook, where the traveler picks dates and room; preserve these URLs unchanged. Dated offer links, when present, are sorted by total price. The traveler completes checkout on the booking site; this tool cannot book or charge anyone. Staylist may earn a commission when someone books through these links, at no extra cost to the traveler; it never changes scores or order.

{
  "type": "object",
  "properties": {
    "hotel_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500,
      "description": "Exact hotel id returned by search_hotels"
    },
    "checkin": {
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
      "description": "Calendar date in YYYY-MM-DD format; provide both dates or neither"
    },
    "checkout": {
      "$ref": "#/properties/checkin",
      "description": "Calendar date in YYYY-MM-DD format; provide both dates or neither"
    },
    "adults": {
      "type": "integer",
      "minimum": 1,
      "maximum": 8,
      "default": 2
    },
    "children_ages": {
      "type": "array",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 17
      },
      "maxItems": 6
    }
  },
  "required": [
    "hotel_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

Popular starting points with country codes. Optional; this list does not restrict which destinations can be searched. No provider search quota is used with the live provider.

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}