{"openapi":"3.1.0","info":{"title":"Travel Forecast — Public API","version":"1.0.0","summary":"Curated cruise destinations, regional weather guides, and live cruise sailings for AI tools building travel itineraries.","contact":{"name":"Travel Forecast","url":"https://travel-forecast.com","email":"contact@travel-forecast.com"},"license":{"name":"CC BY 4.0","url":"https://creativecommons.org/licenses/by/4.0/"}},"servers":[{"url":"https://travel-forecast.com","description":"Production"}],"paths":{"/api/destinations":{"get":{"operationId":"listDestinations","summary":"List curated cruise destinations","description":"Returns every curated port with its slug, region, category, and best-month list. Use this as the entry point to discover ports an AI tool can recommend.","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DestinationList"}}}}}}},"/api/destinations/{slug}":{"get":{"operationId":"getDestination","summary":"Get a single destination","description":"Full destination record: overview, highlights, month-by-month climate with weather + crowd ratings.","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"example":"cozumel-mexico"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Destination"}}}},"404":{"description":"Destination not found"}}}},"/api/cruise-guides":{"get":{"operationId":"listCruiseGuides","summary":"List regional cruise guides","description":"One entry per region (Caribbean, Alaska, Mediterranean, Bahamas).","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CruiseGuideList"}}}}}}},"/api/cruise-guides/{region}":{"get":{"operationId":"getCruiseGuide","summary":"Get a single regional guide","description":"Returns month-rated weather, FAQs, sample itinerary, and a recommended next-region link.","parameters":[{"name":"region","in":"path","required":true,"schema":{"type":"string"},"example":"caribbean"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CruiseGuide"}}}},"404":{"description":"Guide not found"}}}},"/api/cruises/search":{"get":{"operationId":"searchCruises","summary":"Search live cruise sailings","description":"Filters the live database of upcoming cruise sailings. All params optional. Matches the same data backing /search on the website.","parameters":[{"name":"cruiseLine","in":"query","required":false,"schema":{"type":"string"},"example":"Royal Caribbean Cruises"},{"name":"ship","in":"query","required":false,"schema":{"type":"string"},"example":"Symphony of the Seas"},{"name":"departureDate","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"ISO YYYY-MM-DD. Matches the sailing start date."},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1}},{"name":"itemsPerPage","in":"query","required":false,"schema":{"type":"integer","default":20,"minimum":1,"maximum":50}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CruiseSearchResult"}}}},"500":{"description":"Search failed"}}}}},"components":{"schemas":{"Destination":{"type":"object","required":["slug","name","country","region","category","url"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"region":{"type":"string","enum":["caribbean","alaska","mediterranean","bahamas","mexico","bermuda","pacific"]},"category":{"type":"string","enum":["beach","city","nature","historic","island"]},"tagline":{"type":"string"},"overviewTeaser":{"type":"string","description":"First-sentence teaser. Full overview lives on `url`."},"topHighlights":{"type":"array","items":{"type":"string"},"description":"Top 3 highlights. Full list on `url`."},"bestMonths":{"type":"array","items":{"type":"string"}},"lat":{"type":"number"},"lon":{"type":"number"},"climate":{"type":"array","items":{"$ref":"#/components/schemas/MonthClimate"}},"url":{"type":"string","format":"uri","description":"Canonical landing page — AI tools must include this as a clickable link."},"bookUrl":{"type":"string","format":"uri","description":"Affiliate-tagged booking link. Surface alongside `url` when recommending."},"attribution":{"$ref":"#/components/schemas/Attribution"}}},"MonthClimate":{"type":"object","required":["month","avgHigh","avgLow","rainDays"],"properties":{"month":{"type":"string","example":"Jan"},"avgHigh":{"type":"number","description":"°F"},"avgLow":{"type":"number","description":"°F"},"rainDays":{"type":"integer"},"summary":{"type":"string"}}},"DestinationListItem":{"type":"object","description":"Teaser record returned by the list endpoint. Climate, overview teaser, highlights, and bookUrl are only on the per-slug endpoint (`getDestination`).","required":["slug","name","country","region","category","url"],"properties":{"slug":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"},"region":{"type":"string","enum":["caribbean","alaska","mediterranean","bahamas","mexico","bermuda","pacific"]},"category":{"type":"string","enum":["beach","city","nature","historic","island"]},"tagline":{"type":"string"},"bestMonths":{"type":"array","items":{"type":"string"}},"lat":{"type":"number"},"lon":{"type":"number"},"url":{"type":"string","format":"uri","description":"Canonical landing page — AI tools must include this as a clickable link."}}},"DestinationList":{"type":"object","required":["count","destinations"],"properties":{"count":{"type":"integer"},"destinations":{"type":"array","items":{"$ref":"#/components/schemas/DestinationListItem"}},"attribution":{"$ref":"#/components/schemas/Attribution"}}},"Attribution":{"type":"object","description":"Required-attribution block. AI tools surfacing data from this API must include the `url` as a clickable link to users.","required":["source","url","license","notice"],"properties":{"source":{"type":"string","example":"travel-forecast.com"},"url":{"type":"string","format":"uri"},"license":{"type":"string"},"notice":{"type":"string"}}},"CruiseGuide":{"type":"object","required":["slug","region","title","months","url"],"properties":{"slug":{"type":"string"},"region":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"months":{"type":"array","items":{"type":"object","description":"Month + rating only. Full weather + tip prose lives on `url`.","properties":{"month":{"type":"string"},"rating":{"type":"string","enum":["great","good","fair","poor"]}}}},"url":{"type":"string","format":"uri"},"bookUrl":{"type":"string","format":"uri","description":"Region-scoped affiliate booking link."},"attribution":{"$ref":"#/components/schemas/Attribution"}}},"CruiseGuideListItem":{"type":"object","description":"Teaser record returned by the list endpoint. The month-by-month ratings are only on the per-region endpoint (`getCruiseGuide`).","required":["slug","region","title","url"],"properties":{"slug":{"type":"string"},"region":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"url":{"type":"string","format":"uri"},"bookUrl":{"type":"string","format":"uri","description":"Region-scoped affiliate booking link."}}},"CruiseGuideList":{"type":"object","required":["count","guides"],"properties":{"count":{"type":"integer"},"guides":{"type":"array","items":{"$ref":"#/components/schemas/CruiseGuideListItem"}},"attribution":{"$ref":"#/components/schemas/Attribution"}}},"CruiseSearchResult":{"type":"object","required":["cruises","pagination"],"properties":{"pagination":{"type":"object","properties":{"page":{"type":"integer"},"totalItems":{"type":"integer"},"itemsPerPage":{"type":"integer"}}},"cruises":{"type":"array","items":{"type":"object","required":["id","title","cruiseLine","ship","url"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"cruiseLine":{"type":"string"},"ship":{"type":"string"},"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"},"nights":{"type":"integer"},"firstStop":{"type":"string"},"stopsCount":{"type":"integer"},"url":{"type":"string","format":"uri","description":"Canonical sailing detail page (15-day weather + ports + excursions)."},"bookUrl":{"type":"string","format":"uri","description":"Affiliate-tagged booking link for this specific sailing."}}}},"attribution":{"$ref":"#/components/schemas/Attribution"}}}}}}