Data Types

Reference for all data structures returned by the MCP tools.

Hotel

The core hotel object returned in every search/fetch response.

{
  id: string                    // Unique hotel identifier
  name: string                  // Hotel display name
  url: string                   // Direct Vio booking page URL
  propertyDescription?: string  // Hotel description
  roomsDescription?: string     // Rooms overview text
  phone?: string                // Contact number
  isPartialMatch?: boolean      // True if hotel matches only SOME filters (see below)
  isAnchorHotel?: boolean       // True for the anchor hotel in similarity search
  typicalPriceRange?: {         // Historical price range
    min: number
    max: number
  }
}

isPartialMatch

When filters are applied, the server returns the best matches first. If there aren't enough hotels matching all filters, additional hotels that match only some filters are included with isPartialMatch: true. Hotels without this flag (or with false) match all requested filters exactly.

Use this to visually distinguish partial matches in your UI — for example, showing a note like "doesn't match all your filters" or ranking them below exact matches.

Location

Included when include contains "location".

{
  address: string               // Full address
  displayName: string           // City/area name
  latitude: number | null
  longitude: number | null
  timezone?: string             // IANA timezone
  areaDescription?: string      // Description of the surrounding area
  attractionsDescription?: string
  nearbyAttractions?: [{
    name: string
    distanceKm: number
    distanceMiles: number
  }]
}

Rating

Included when include contains "rating".

{
  overall: number               // 0-10 scale
  reviewCount: number | null
  guestType?: {                 // Ratings by guest type
    business?: number
    couples?: number
    families?: number
    groups?: number
    solo?: number
  }
  detailed?: {                  // Category breakdown
    cleanliness?: number
    dining?: number
    facilities?: number
    location?: number
    pricing?: number
    rooms?: number
    service?: number
  }
}

Classification

Included when include contains "classification".

{
  starRating: number | null     // 0-5 scale
  propertyType?: {
    id: string
    name: string                // "Hotel", "Apartment", "Resort", etc.
  }
  themes?: [{id: string, name: string}]
  sentiments?: [{id: string, name: string}]
  nationalRatingsDescription?: string
}

Facilities

Included when include contains "facility".

{
  items: [{
    id: string
    name: string                // Localized facility name
  }]
  amenities?: string            // General amenities text
  business?: string             // Business facilities text
  dining?: string               // Dining facilities text
}

Media

Included when include contains "media".

{
  images: string[]              // CDN-optimized image URLs (WebP)
  imagesAvailable: number       // Total images available
}

Offers

Included when include contains "offer". The contents depend on offers.mode:

• top_offers (default) and cheapest return a curated selection in ranking order.
• all returns available offers from Vio and external providers, cheapest first (sorted by rate.displayPrice). Offer links open the hotel's page on Vio, where users select a deal. roomsComplete: false indicates that room rates may be incomplete.

{
  items: [{
    id: string
    url: string                 // In "all" mode, opens the hotel's page on Vio to select a deal
    currency: string            // ISO 4217
    rate: {
      base?: number             // Room rate
      taxes?: number            // Tax amount
      hotelFees?: number        // Additional fees
      displayPrice?: number     // The price to display (total incl. fees, excl. taxes where applicable)
    }
    cancellationPenalties?: [{
      amount?: number
      currency?: string
      start?: string            // ISO date
      end?: string
    }]
    package?: {
      amenities?: string[]      // e.g., ["Breakfast included"]
    }
    // package and occupancy may be omitted on some offers: absence means
    // unknown, not "not included".
    availableRooms?: number
    providerCode?: string       // e.g., "booking.com"
    providerName?: string       // e.g., "Booking.com"
    roomId?: string
    roomName?: string
    tags?: string[]             // Special feature/pricing tags (see Offer Tags below)
    occupancy?: {
      adults: number
      children?: number[]       // Ages
    }
  }]
  availableCount?: number       // Count of the returned offer list
  cheapestRate?: {              // Always the cheapest of the returned list
    base?: number
    taxes?: number
    hotelFees?: number
    displayPrice?: number
  }
}

The summary fields always describe the returned list: they never disagree with items. anchorRate and roomsReference appear in the curated modes only.

Offer tags

The tags array indicates special features or pricing positions for an offer:

Tag	Description
cheapest_offer	The cheapest available offer for this hotel
top_offer	A top-rated offer based on value and quality
exclusive	An exclusive offer only available through Vio
exclusive_cheapest_offer	The cheapest offer and exclusive to Vio
anchor_price	The reference price from the anchor hotel in similarity searches
price_drop	Price has recently dropped compared to historical rates
preferred_rate	A preferred/negotiated rate
charge_later	Pay at the hotel, no upfront charge required
deal_freeze	Price has been frozen/locked for a limited time

Use these tags to highlight deals, show badges, or prioritize offers in your UI.

Rooms

Included when include contains "room".

{
  id: string
  name: string
  description?: string
  maxOccupancy?: number
  amenities?: string[]          // e.g., ["Air conditioning", "Mini bar"]
  bedTypes?: [{
    id?: string
    name?: string               // e.g., "King bed", "Twin beds"
  }]
  images?: string[]             // Room-specific images
  area?: {
    squareMeters?: number
    squareFeet?: number
  }
  smokingOptionsAvailable?: boolean
}

Rooms describe the property's room types: they carry no rates. Every bookable rate lives in offers.items. Request offers.mode: "all" for room rates and external-provider offers. Use roomId/roomName, when available, to show offers per room.

Reviews

Included when include contains "review".

{
  totalAvailable: number
  averageRating: number | null
  perRatingBreakdown: {         // Count per rating score
    [rating: string]: number
  }
  items: [{
    date?: string               // ISO date
    name?: string               // Reviewer name
    score?: number              // 1-10
    text?: string               // Review text
    language?: string           // ISO 639-1
    source?: string             // Review source
    checkIn?: string
    checkOut?: string
  }]
}

Insights

Included when include contains "insight". AI-generated review summaries.

{
  overall: string               // Overall AI summary
  categories: [{
    category: string            // "Facilities", "Cleanliness", "Rooms",
                                // "Service", "Location", "Food"
    title: string               // Short title
    summary: string             // Category-specific summary
  }]
}

Analytics

Included when include contains "analytic". Price intelligence data.

{
  averagePrice?: number
  timeRangeDays?: number
  comparisonToSimilar?: {
    differencePercentage: number // Negative = cheaper than similar
    assessment: "cheaper" | "same" | "expensive"
  }
  history?: [{
    timestamp: string
    price: number
  }]
  similarHotelsHistory?: [{
    timestamp: string
    price: number
  }]
}

Policies

Included when include contains "policy".

{
  checkIn?: {
    beginTime?: string
    endTime?: string
    minAge?: number
    instructions?: string
    specialInstructions?: string
  }
  checkOut?: {
    time?: string
  }
  fees?: {
    mandatory?: string
    optional?: string
  }
  feesDescription?: string
  policiesDescription?: string
  knowBeforeYouGo?: string
  deposit?: {
    amount?: number
    currency?: string
    description?: string
  }
  generalPolicies?: string
}

FAQ

Included when include contains "faq".

{
  question: string
  answer: string
  label?: string                // Category label
}

Availability entry

Returned by search_hotels_availability.

{
  hotelId: string
  checkIn: string               // ISO date
  cheapestRate?: {
    base?: number
    taxes?: number
    hotelFees?: number
    displayPrice?: number       // Tax/fee-inclusive price per the user's country
  }
  offerCount?: number           // Number of available offers
}