{"openapi":"3.1.0","info":{"title":"Ultimate — Travel Discovery API","version":"1.0.0","summary":"Public, read-only travel data: lodging, things to do, food & drink, shopping, transport, and events.","description":"Open, unauthenticated read API over the wander travel dataset. No key required for these endpoints.\n\nConventions:\n- `region` filters by wander RegionID (e.g. `ca-london`, `it-rome`), NOT the public guidebook slug.\n- `continent` is a slug: `north-america`, `south-america`, `europe`, `africa`, `asia`, `oceania`, `middle-east`.\n- On the large tables, pass `mustsee=1` at worldwide scope to get curated picks instead of everything.\n- Coordinates are decimal degrees; `null` means unknown, never 0.\n\nHuman guidebooks live at /guides/<slug> (free) and /guide/<slug> (expanded).\nAgent orientation: /llms.txt. The booking / MCP / identity surface is separate and not described here yet.","contact":{"email":"agents@ultimatecity.org"},"license":{"name":"Open data — see /llms.txt"}},"servers":[{"url":"http://www.ultimatecity.org","description":"This host"}],"tags":[{"name":"Lodging","description":"Hotels, villas, glamping."},{"name":"Things to do","description":"Attractions and tours."},{"name":"Food & drink","description":"Bars and restaurants."},{"name":"Shopping","description":"Malls, markets, shops."},{"name":"Transport","description":"Airports."},{"name":"Events","description":"Dated events."},{"name":"Geo","description":"Coordinate and bounding-box search."}],"paths":{"/api/hotels":{"get":{"tags":["Lodging"],"operationId":"list_hotels","summary":"List hotels","description":"Returns hotels, optionally narrowed by `region` (RegionID) or `continent`. This table is large — at worldwide scope pass `mustsee=1` to get the curated picks instead of everything.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"},{"$ref":"#/components/parameters/MustSee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Hotel"}}}}}}}},"/api/hotels/{slug}":{"get":{"tags":["Lodging"],"operationId":"get_hotels_item","summary":"Get one hotel","description":"Fetch a single hotel by its URL slug (or name).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"URL slug or name of the hotel."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Hotel"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/villas":{"get":{"tags":["Lodging"],"operationId":"list_villas","summary":"List villas","description":"Returns villas, optionally narrowed by `region` (RegionID) or `continent`. This table is large — at worldwide scope pass `mustsee=1` to get the curated picks instead of everything.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"},{"$ref":"#/components/parameters/MustSee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Villa"}}}}}}}},"/api/villas/{slug}":{"get":{"tags":["Lodging"],"operationId":"get_villas_item","summary":"Get one villa","description":"Fetch a single villa by its URL slug (or name).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"URL slug or name of the villa."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Villa"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/glamping":{"get":{"tags":["Lodging"],"operationId":"list_glamping","summary":"List glamping","description":"Returns glamping sites, optionally narrowed by `region` (RegionID) or `continent`. This table is large — at worldwide scope pass `mustsee=1` to get the curated picks instead of everything.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"},{"$ref":"#/components/parameters/MustSee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Place"}}}}}}}},"/api/glamping/{slug}":{"get":{"tags":["Lodging"],"operationId":"get_glamping_item","summary":"Get one glamping site","description":"Fetch a single glamping site by its URL slug (or name).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"URL slug or name of the glamping site."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Place"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/attractions":{"get":{"tags":["Things to do"],"operationId":"list_attractions","summary":"List attractions","description":"Returns attractions, optionally narrowed by `region` (RegionID) or `continent`. This table is large — at worldwide scope pass `mustsee=1` to get the curated picks instead of everything.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"},{"$ref":"#/components/parameters/MustSee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Place"}}}}}}}},"/api/attractions/{slug}":{"get":{"tags":["Things to do"],"operationId":"get_attractions_item","summary":"Get one attraction","description":"Fetch a single attraction by its URL slug (or name).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"URL slug or name of the attraction."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Place"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/tours":{"get":{"tags":["Things to do"],"operationId":"list_tours","summary":"List tours","description":"Returns tours, optionally narrowed by `region` (RegionID) or `continent`. This table is large — at worldwide scope pass `mustsee=1` to get the curated picks instead of everything.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"},{"$ref":"#/components/parameters/MustSee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Tour"}}}}}}}},"/api/tours/{slug}":{"get":{"tags":["Things to do"],"operationId":"get_tours_item","summary":"Get one tour","description":"Fetch a single tour by its URL slug (or name).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"URL slug or name of the tour."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tour"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/bars":{"get":{"tags":["Food & drink"],"operationId":"list_bars","summary":"List bars","description":"Returns bars, optionally narrowed by `region` (RegionID) or `continent`. This table is large — at worldwide scope pass `mustsee=1` to get the curated picks instead of everything.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"},{"$ref":"#/components/parameters/MustSee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Place"}}}}}}}},"/api/bars/{slug}":{"get":{"tags":["Food & drink"],"operationId":"get_bars_item","summary":"Get one bar","description":"Fetch a single bar by its URL slug (or name).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"URL slug or name of the bar."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Place"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/places":{"get":{"tags":["Food & drink"],"operationId":"list_places","summary":"List places","description":"Returns restaurants, optionally narrowed by `region` (RegionID) or `continent`. This table is large — at worldwide scope pass `mustsee=1` to get the curated picks instead of everything.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"},{"$ref":"#/components/parameters/MustSee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Place"}}}}}}}},"/api/places/{slug}":{"get":{"tags":["Food & drink"],"operationId":"get_places_item","summary":"Get one restaurant","description":"Fetch a single restaurant by its URL slug (or name).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"URL slug or name of the restaurant."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Place"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/shopping":{"get":{"tags":["Shopping"],"operationId":"list_shopping","summary":"List shopping","description":"Returns shopping venues, optionally narrowed by `region` (RegionID) or `continent`. This table is large — at worldwide scope pass `mustsee=1` to get the curated picks instead of everything.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"},{"$ref":"#/components/parameters/MustSee"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Place"}}}}}}}},"/api/shopping/{slug}":{"get":{"tags":["Shopping"],"operationId":"get_shopping_item","summary":"Get one shopping venue","description":"Fetch a single shopping venue by its URL slug (or name).","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"},"description":"URL slug or name of the shopping venue."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Place"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/airports":{"get":{"tags":["Transport"],"operationId":"list_airports","summary":"List airports","description":"Returns airports, optionally narrowed by `region` (RegionID) or `continent`.","parameters":[{"$ref":"#/components/parameters/Region"},{"$ref":"#/components/parameters/Continent"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Airport"}}}}}}}},"/api/events":{"get":{"tags":["Events"],"operationId":"list_events","summary":"List events","description":"Events, optionally filtered. Pass `upcoming=1` or `past=1` to bound by date.","parameters":[{"name":"upcoming","in":"query","schema":{"type":"string","enum":["1"]},"description":"Only future events."},{"name":"past","in":"query","schema":{"type":"string","enum":["1"]},"description":"Only past events."},{"$ref":"#/components/parameters/Region"},{"name":"genre","in":"query","schema":{"type":"string"},"description":"Filter by genre/category."},{"name":"limit","in":"query","schema":{"type":"integer","default":100},"description":"Max rows."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}}}}},"/api/events/{slug}":{"get":{"tags":["Events"],"operationId":"get_event","summary":"Get one event","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Event"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/nearby":{"get":{"tags":["Geo"],"operationId":"nearby","summary":"Search points of interest near a coordinate","description":"Returns nearby POIs across the wander tables within a radius of a lat/lng.","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number"}},{"name":"radius","in":"query","schema":{"type":"integer","default":5000},"description":"Radius in metres (default 5000)."},{"name":"q","in":"query","schema":{"type":"string"},"description":"Free-text filter."},{"name":"filter","in":"query","schema":{"type":"string"},"description":"Category filter."},{"name":"regionId","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Place"}}}}}}}},"/api/hotels/nearby":{"get":{"tags":["Lodging","Geo"],"operationId":"hotels_nearby","summary":"Hotels near a coordinate","parameters":[{"name":"lat","in":"query","required":true,"schema":{"type":"number"}},{"name":"lng","in":"query","required":true,"schema":{"type":"number"}},{"name":"radius_km","in":"query","schema":{"type":"number","default":25,"maximum":500}},{"name":"limit","in":"query","schema":{"type":"integer","default":200,"maximum":1000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Hotel"}}}}}}}},"/api/hotels/bbox":{"get":{"tags":["Lodging","Geo"],"operationId":"hotels_bbox","summary":"Hotels within a bounding box","parameters":[{"name":"n","in":"query","required":true,"schema":{"type":"number"},"description":"North latitude."},{"name":"s","in":"query","required":true,"schema":{"type":"number"},"description":"South latitude."},{"name":"e","in":"query","required":true,"schema":{"type":"number"},"description":"East longitude."},{"name":"w","in":"query","required":true,"schema":{"type":"number"},"description":"West longitude."},{"name":"limit","in":"query","schema":{"type":"integer","default":500,"maximum":2000}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Hotel"}}}}}}}}},"components":{"parameters":{"Region":{"name":"region","in":"query","schema":{"type":"string"},"example":"ca-london","description":"Filter by wander RegionID (e.g. ca-london, it-rome, fr-paris)."},"Continent":{"name":"continent","in":"query","schema":{"type":"string","enum":["north-america","south-america","europe","africa","asia","oceania","middle-east"]},"description":"Filter by continent slug."},"MustSee":{"name":"mustsee","in":"query","schema":{"type":"string","enum":["1"]},"description":"Set to 1 to return only curated must-see picks (recommended at worldwide scope)."}},"schemas":{"Place":{"type":"object","description":"A point of interest (attraction, bar, restaurant, shop, glamping site).","properties":{"name":{"type":"string","description":"Unique record name (also the fallback slug)."},"display":{"type":"string","description":"Human-facing name."},"location":{"type":["string","null"]},"regionId":{"type":["string","null"],"description":"wander RegionID, e.g. ca-london, it-rome."},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"website":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"mustSee":{"type":"boolean"},"keywords":{"type":["string","null"]},"about":{"type":["string","null"]},"rating":{"type":["number","null"]},"reviews":{"type":"integer"}}},"Hotel":{"type":"object","description":"A hotel / lodging record from wander.hotels.","properties":{"name":{"type":"string","description":"Unique record name (also the fallback slug)."},"display":{"type":"string","description":"Human-facing name."},"location":{"type":["string","null"]},"regionId":{"type":["string","null"],"description":"wander RegionID, e.g. ca-london, it-rome."},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"website":{"type":["string","null"]},"phone":{"type":["string","null"]},"email":{"type":["string","null"]},"imageUrl":{"type":["string","null"]},"mustSee":{"type":"boolean"},"keywords":{"type":["string","null"]},"about":{"type":["string","null"]},"rating":{"type":["number","null"]},"reviews":{"type":"integer"},"franchise":{"type":["string","null"]},"rooms":{"type":"integer"},"category":{"type":["string","null"]},"boundarySlug":{"type":["string","null"],"description":"Booking slug when the property is bookable via Boundary."},"instagram":{"type":["string","null"]},"facebook":{"type":["string","null"]},"twitter":{"type":["string","null"]},"youtube":{"type":["string","null"]},"linkedin":{"type":["string","null"]},"tiktok":{"type":["string","null"]},"pinterest":{"type":["string","null"]}}},"Tour":{"type":"object","description":"A tour or experience from wander.tours.","properties":{"name":{"type":"string"},"slug":{"type":"string"},"display":{"type":"string"},"regionId":{"type":["string","null"]},"continent":{"type":["string","null"]},"location":{"type":["string","null"]},"category":{"type":["string","null"]},"duration":{"type":["string","null"]},"groupSize":{"type":["integer","null"]},"pricePer":{"type":["number","null"]},"rating":{"type":["number","null"]},"reviews":{"type":"integer"},"mustSee":{"type":"boolean"},"image":{"type":["string","null"]}}},"Villa":{"type":"object","description":"A private villa / vacation rental from wander.villas.","properties":{"name":{"type":"string"},"slug":{"type":"string"},"title":{"type":"string"},"location":{"type":["string","null"]},"regionId":{"type":["string","null"]},"continent":{"type":["string","null"]},"country":{"type":["string","null"]},"cityTown":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"type":{"type":["string","null"]},"bedrooms":{"type":["integer","null"]},"bathrooms":{"type":["integer","null"]},"guests":{"type":["integer","null"]},"amenities":{"type":"array","items":{"type":"string"}},"priceMin":{"type":["number","null"]},"priceMax":{"type":["number","null"]},"currency":{"type":"string"},"rating":{"type":["number","null"]},"reviews":{"type":"integer"},"mustSee":{"type":"boolean"},"luxury":{"type":"boolean"},"image":{"type":["string","null"]},"about":{"type":["string","null"]},"website":{"type":["string","null"]},"bookUrl":{"type":["string","null"]},"bookable":{"type":"boolean"},"phone":{"type":["string","null"]},"email":{"type":["string","null"]}}},"Airport":{"type":"object","description":"An airport from wander.airports.","properties":{"name":{"type":"string"},"symbol":{"type":"string","description":"IATA/ICAO or OurAirports ident."},"display":{"type":"string"},"regionId":{"type":["string","null"]},"website":{"type":["string","null"]},"phone":{"type":["string","null"]},"location":{"type":["string","null"]},"lat":{"type":["number","null"]},"lng":{"type":["number","null"]},"imageUrl":{"type":["string","null"]},"explainer":{"type":["string","null"]},"dutyFree":{"type":["string","null"]}}},"Event":{"type":"object","description":"An event from wander.events.","properties":{"name":{"type":"string"},"display":{"type":"string"},"website":{"type":["string","null"]},"regionId":{"type":["string","null"]},"startDate":{"type":["string","null"]},"endDate":{"type":["string","null"]},"genre":{"type":["string","null"]},"image":{"type":["string","null"]}}},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}}}