{"openapi":"3.0.3","info":{"title":"BostonVacay Connector API","version":"2.2.1","description":"Read-only API for BostonVacay (bostonvacay.com), operated by Cloudalien Technologies LLC: a curated directory of Boston, Massachusetts businesses, plus live Viator tours. Booking links are the path to book with the provider named in each link (for example Expedia, Hotels.com, Viator or Klook). Links marked affiliate:true and sponsored:true are affiliate links: Cloudalien Technologies LLC (operator of BostonVacay) may earn a commission if a user books through them, at no extra cost to the user. Listings are not paid placements, and results are never ranked or filtered by commission or affiliate status. Prices, availability and booking terms are set and confirmed by the provider. Docs: https://bostonvacay-connector.michael-b38.workers.dev/docs","contact":{"name":"BostonVacay (operated by Cloudalien Technologies LLC)","email":"michael@cloudalien.com","url":"https://www.bostonvacay.com"},"x-operator":"Cloudalien Technologies LLC","x-tool-classification":"All operations are Read (no writes, no sensitive writes).","termsOfService":"https://bostonvacay-connector.michael-b38.workers.dev/terms"},"servers":[{"url":"https://bostonvacay-connector.michael-b38.workers.dev"}],"paths":{"/v1/health":{"get":{"operationId":"health","summary":"Service health","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"version":{"type":"string"},"time":{"type":"string","format":"date-time"}}}}}}}}},"/v1/categories":{"get":{"operationId":"listCategories","summary":"List categories with listing counts (cached 24 h)","responses":{"200":{"description":"Categories","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"total":{"type":"integer"},"categories":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","nullable":true},"name":{"type":"string"},"description":{"type":"string"},"listing_count":{"type":"integer"}}}}}}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/filters":{"get":{"operationId":"listFilters","summary":"Areas, price tiers, amenities and tags usable as filters","responses":{"200":{"description":"Filters","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listings/search":{"get":{"operationId":"searchListings","summary":"Search listings (read-only). Booking links marked affiliate are affiliate links.","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Keywords"},{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Category name or id"},{"name":"area","in":"query","required":false,"schema":{"type":"string"},"description":"Area/neighborhood"},{"name":"price_tier","in":"query","required":false,"schema":{"type":"string","enum":["budget","moderate","upscale","luxury"]},"description":"budget|moderate|upscale|luxury"},{"name":"amenities","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated amenity keys: ski_in_ski_out, walk_to_lifts, pool, hot_tub, spa, fitness_center, pet_friendly, parking, shuttle, family_friendly, breakfast, kitchen, rooftop, river_view, outdoor_seating, apres_ski, live_music, free_entry, michelin, wheelchair_accessible"},{"name":"tag","in":"query","required":false,"schema":{"type":"string"},"description":"Exact tag"},{"name":"near_lat","in":"query","required":false,"schema":{"type":"number"},"description":"Latitude"},{"name":"near_lng","in":"query","required":false,"schema":{"type":"number"},"description":"Longitude"},{"name":"near_listing_id","in":"query","required":false,"schema":{"type":"string"},"description":"Listing id to measure distance from"},{"name":"radius_km","in":"query","required":false,"schema":{"type":"number"},"description":"Max distance in km"},{"name":"has_booking_link","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only listings with a booking link"},{"name":"check_in","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD"},{"name":"check_out","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD"},{"name":"adults","in":"query","required":false,"schema":{"type":"integer","default":2},"description":"1-14"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","distance","name"]},"description":"relevance|distance|name"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":10,"minimum":1,"maximum":50},"description":"1-50"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1,"minimum":1},"description":"Page"}],"responses":{"200":{"description":"Matching listings (cached 1 h)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"site":{"type":"string"},"total":{"type":"integer","description":"Listings matching all filters"},"page":{"type":"integer"},"per_page":{"type":"integer"},"returned":{"type":"integer"},"has_more":{"type":"boolean"},"match":{"type":"string","nullable":true},"notes":{"type":"array","items":{"type":"string"}},"affiliate_disclosure":{"type":"string"},"data_fetched_at":{"type":"string","format":"date-time"},"listings":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/listings/{id}":{"get":{"operationId":"getListing","summary":"Full listing details","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"check_in","in":"query","required":false,"schema":{"type":"string"},"description":"YYYY-MM-DD"},{"name":"check_out","in":"query","required":false,"schema":{"type":"string"},"description":"YYYY-MM-DD"},{"name":"adults","in":"query","required":false,"schema":{"type":"integer"},"description":"1-14"}],"responses":{"200":{"description":"Listing","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"affiliate_disclosure":{"type":"string"},"data_fetched_at":{"type":"string"},"listing":{"$ref":"#/components/schemas/Listing"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/tours/search":{"get":{"operationId":"searchTours","summary":"Live Viator tours and activities in Boston, Massachusetts (affiliate booking links)","parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"},"description":"Keywords"},{"name":"start_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD"},{"name":"end_date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"YYYY-MM-DD"},{"name":"max_price","in":"query","required":false,"schema":{"type":"number"},"description":"Max price"},{"name":"min_rating","in":"query","required":false,"schema":{"type":"number"},"description":"0-5"},{"name":"free_cancellation","in":"query","required":false,"schema":{"type":"boolean"},"description":"Only free-cancellation products"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["relevance","rating","price_low","price_high","featured"]},"description":"relevance (default with q)|rating (default without q)|price_low|price_high|featured (Viator's own order)"},{"name":"currency","in":"query","required":false,"schema":{"type":"string","default":"USD"},"description":"USD|EUR|GBP|CAD|AUD|THB"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":5},"description":"1-20"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","default":1},"description":"Page"}],"responses":{"200":{"description":"Tours with live prices (cached 15 min)","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"total":{"type":"integer"},"prices_checked_at":{"type":"string","format":"date-time"},"affiliate_disclosure":{"type":"string"},"tours":{"type":"array","items":{"type":"object","properties":{"product_code":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"from_price":{"type":"number"},"currency":{"type":"string"},"price_basis":{"type":"string"},"rating":{"type":"number","nullable":true},"review_count":{"type":"integer"},"duration_minutes":{"type":"integer","nullable":true},"free_cancellation":{"type":"boolean"},"image":{"type":"string","nullable":true},"image_credit":{"type":"string"},"booking_url":{"type":"string"},"affiliate":{"type":"boolean"}}}}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Listing":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"url":{"type":"string","description":"Listing page on bostonvacay.com","nullable":true},"category":{"type":"string","nullable":true},"area":{"type":"string","nullable":true},"price_tier":{"type":"string","nullable":true},"amenities":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"}},"description":{"type":"string","description":"Plain text"},"address":{"type":"string","nullable":true},"lat":{"type":"number","nullable":true},"lon":{"type":"number","nullable":true},"phone":{"type":"string","nullable":true},"website":{"type":"string","nullable":true},"booking_link":{"type":"string","description":"First affiliate booking link, if any","nullable":true},"booking":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"string"},"label":{"type":"string"},"url":{"type":"string"},"affiliate":{"type":"boolean"}}}},"photos":{"type":"array","items":{"type":"string"}},"photo_details":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"caption":{"type":"string","nullable":true},"credit":{"type":"string"},"source":{"type":"string"}}}},"distance_km":{"type":"number"},"category_id":{"type":"string","nullable":true},"summary":{"type":"string","nullable":true},"description_truncated":{"type":"boolean"},"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"zip":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"links":{"type":"array","items":{"type":"object","properties":{"kind":{"type":"string"},"label":{"type":"string"},"url":{"type":"string"},"site":{"type":["string","null"],"description":"Destination of the link: a booking brand or the business's own domain."},"affiliate":{"type":"boolean"},"sponsored":{"type":"boolean"}}}},"hours":{"type":"array","nullable":true,"items":{"type":"object","properties":{"day":{"type":"string"},"hours":{"type":"string"}}}},"image_main":{"type":"string","nullable":true},"photo_count":{"type":"integer"},"distance_mi":{"type":"number"},"faq":{"type":"array","nullable":true,"items":{"type":"object","properties":{"q":{"type":"string"},"a":{"type":"string"}}}},"facts":{"type":"object","nullable":true,"additionalProperties":{"type":"string"}}}},"Error":{"type":"object","properties":{"status":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"},"detail":{"type":"string"}}}}}}