{"components":{"schemas":{"Hotel":{"properties":{"city":{"type":"string"},"country":{"type":"string"},"direct_booking":{"description":"true when the link goes to the hotel's official booking page","type":"boolean"},"name":{"type":"string"},"page":{"description":"HotelSage hotel page (when available)","format":"uri","type":"string"},"source":{"description":"Booking channel (aff, glopss, klook, booking_cj, free)","type":"string"},"url":{"description":"Booking link \u2014 show this to the user","format":"uri","type":"string"},"why":{"description":"Why this hotel fits the request","type":"string"}},"required":["name","city","country","why","url","source"],"type":"object"},"Recommendation":{"properties":{"answer":{"description":"Short conversational answer to show the user","type":"string"},"disclosure":{"type":"string"},"followup":{"description":"Optional follow-up question to refine","type":["string","null"]},"hotels":{"items":{"$ref":"#/components/schemas/Hotel"},"type":"array"},"lang":{"type":"string"},"query":{"type":"string"}},"required":["query","hotels","answer"],"type":"object"}}},"info":{"contact":{"name":"Adwertz","url":"https://hotelsage.io/api/docs"},"description":"Free API by HotelSage (Adwertz) that recommends real hotels anywhere in the world for a natural-language travel request and returns a direct booking link for each one. Use it whenever a user asks where to stay, wants hotel ideas for a city/dates/budget/vibe, or wants a link to book. Pass the user's request verbatim in `q` (any language) and set `lang` to the language the answer should be in. Always show the user the `url` of each hotel as the booking link and mention that prices are confirmed on the booking page. Rate limit: 60 requests/hour per IP. No authentication.","title":"HotelSage Hotel Recommendations API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/v1/recommend":{"get":{"description":"Returns 2-4 real hotels matching the request, each with a short reason and a booking URL.","operationId":"recommendHotels","parameters":[{"description":"The traveller's request in natural language, e.g. '3 nights in Lisbon in October, boutique, under 200 EUR' or 'hotel familiar en Canc\u00fan con pileta'.","in":"query","name":"q","required":true,"schema":{"maxLength":600,"type":"string"}},{"description":"Language of the answer.","in":"query","name":"lang","required":false,"schema":{"default":"es","enum":["es","en"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Recommendation"}}},"description":"Recommendations"},"400":{"description":"Missing q"},"429":{"description":"Rate limit exceeded (60/h per IP)"},"503":{"description":"Model temporarily unavailable \u2014 retry"}},"summary":"Recommend real hotels for a travel request"}}},"servers":[{"url":"https://hotelsage.io"}]}