Search hotels
Find hotels by destination and/or text, with an indicative per-room-night price when a stay is given.
destination is a place_name with its countryCode, a place or locality by placeId from an earlier answer, a point, or a country. A name several places bear answers destination_ambiguous with candidates: ask the user, then search the chosen placeId. text matches hotel names, brands and areas word for word. Indicative prices are estimates and not bookable: get_hotel_offers returns what the user pays. A search too broad to answer is refused with search_too_broad and its localities: pass one back as { kind: "locality", placeId }, never by name. The answer states the scope, the counts and notes; a next page is the cursor and, optionally, limit.
search_hotels · Read-only · CLI: fortrip hotels search
Input
destinationobjectWhere to search. A first page needs this or text.
destinationwhen kind: "place_name"A place named in words, with its country.
destination.namestringrequiredThe place name, in any language, e.g. Tokyo or 东京.1–128 chars
destination.countryCodestringrequiredISO 3166-1 alpha-2 country the place is in, e.g. JP.matches ^[A-Z]{2}$
destination.radiusMetersintegerSearch radius around the destination in meters, 1 to 80000. Left out, the service picks one.1–80000
destinationwhen kind: "place"A place id from an earlier response.
destination.placeIdstringrequiredplaceId from an earlier response.matches ^plc_\d{1,12}$
destination.radiusMetersintegerSearch radius around the destination in meters, 1 to 80000. Left out, the service picks one.1–80000
destinationwhen kind: "point"A point on the map.
destination.locationobjectrequiredThe point, WGS84.
destination.location.latnumberrequiredLatitude, WGS84.-90–90
destination.location.lngnumberrequiredLongitude, WGS84.-180–180
destination.radiusMetersintegerSearch radius around the destination in meters, 1 to 80000. Left out, the service picks one.1–80000
destinationwhen kind: "country"A whole country.
destination.countryCodestringrequiredISO 3166-1 alpha-2 country, e.g. JP.matches ^[A-Z]{2}$
destinationwhen kind: "locality"A locality (hub) listed in an earlier search response.
destination.placeIdstringrequiredplaceId of the locality.matches ^plc_\d{1,12}$
destination.radiusMetersintegerSearch radius around the destination in meters, 1 to 80000. Left out, the service picks one.1–80000
textstringHotel name, brand or area to match, 1 to 128 characters. A first page needs this or destination.1–128 chars
stayobjectDates and party. Needed for indicative prices. Search uses only the dates when the rooms differ.
stay.checkInstringrequiredCheck-in date in the hotel's calendar, yyyy-MM-dd.
stay.checkOutstringrequiredCheck-out date in the hotel's calendar, yyyy-MM-dd. Stays are 1 to 15 nights; a longer one answers stay_unsupported (max_nights), and past 30 nights invalid_request: ask the user whether to split it into consecutive stays.
stay.roomsobject[]requiredThe rooms wanted, 1 to 8, each with its party; offers and orders need every room the same.1–8 items
stay.rooms[].adultsintegerrequiredAdults in this room.1–8
stay.rooms[].childrenAgesinteger[]requiredAge of each child in this room, 0 to 17. An empty list means no children.≤ 4 items · each 0–17
pricing"indicative" | "none"indicative adds an approximate price per hotel and needs a stay; none skips prices. Default: indicative with a stay, otherwise none.
filtersobjectFilters every hotel in the answer must pass.
filters.starsobjectStar rating range. Unrated hotels are left out whenever it is set.
filters.stars.minnumberLowest star rating, 1 to 5 in steps of 0.5.1–5
filters.stars.maxnumberHighest star rating, 1 to 5 in steps of 0.5.1–5
filters.amenities("parking" | "wifi" | "laundry" | "restaurant" | "room_service" | "bar" | "non_smoking" | "business_center" | "pool" | "airport_shuttle" | "spa" | "gym" | "accessible" | "ev_charging" | "air_conditioning" | "pets_allowed" | "kitchen" | "other")[]Amenities every hotel must list. Only some codes can filter; asking for one that cannot is answered with the list that can.1–9 items
filters.priceobjectPrice limit. Needs indicative pricing, so a stay.
filters.price.maxPerRoomNightobjectrequiredHighest price per room per night, in USD.
filters.price.maxPerRoomNight.amountstringrequiredDecimal string such as 132.40, never a number.matches ^\d+(\.\d+)?$
filters.price.maxPerRoomNight.currency"USD"requiredAlways USD in a request.
sort"distance" | "relevance" | "stars_desc" | "price_asc" | "price_desc"Result order. distance needs a destination, relevance needs text, price_asc and price_desc need indicative pricing. Default: relevance with text, otherwise distance.
limitintegerHotels per page, 1 to 50. Default 20.1–50
cursorstringnextCursor from the previous response. A next page is the cursor and, optionally, limit; nothing else.≥ 1 chars
locale"en" | "zh"Language for names and text in the response: en or zh.
displayCurrency"USD" | "CNY"Currency to show prices in, USD or CNY. It never changes what is charged: payment is in USD.
Output
structuredContent is the Search result object. content[0] is the answer as compact text, and content[1] is the presentation hint: how to show hotels to the user. Errors are described in the overview.