Gondola Partner Search API

openapi: 3.2.0
info:
  title: Gondola Partner Search API
  version: 1.0.0
  description: 'Search hotels and observed rates for approved partners. Read the integration guide for examples, location fields, result statuses, and limits. Select **Authorize** and enter your Gondola bearer token to try a request.


    Search by location: a city or hotel name, coordinates, a viewport, a region, hotel chains, or themes. Check-in must be from today through 365 days from today, and stays can be 1–30 nights. Without dates, the API searches the next 30 one-night stays. Rates represent two adults without children.


    Each hotel/date status is `available`, `missing_content`, `missing_rate`, or `unavailable`. A replica observation can differ from a simultaneous Gondola deals-page rate. Each service machine allows 100 requests per second per partner token. Retry `429` after `Retry-After`; retry `503` later.'
servers:
- url: https://api.gondola.ai
tags:
- name: partner-search
paths:
  /v3/search:
    post:
      tags:
      - partner-search
      operationId: v3_search_post
      security:
      - PartnerBearer: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerSearchRequest'
      responses:
        '200':
          description: Search result, including individual gaps
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerSearchResponse'
        '401':
          description: Partner credential rejected
        '413':
          description: Request body exceeds the 1 MB limit
        '429':
          description: Partner request limit reached
          headers:
            Retry-After:
              description: Seconds until retry
              schema:
                type: integer
        '422':
          description: Correct the request
        '503':
          description: Replica unavailable; retry later
      summary: V3 search post
      x-summary-source: derived
components:
  schemas:
    StayTag:
      type: string
      enum:
      - Great Points Deal
      - Great Cash Deal
      - Recommended for You
      - Highly Rated
      - Maximum Earnings
      - Frequent Stays
      - Closest to Location
      - Recently Renovated
    PointsAmount:
      type: object
      description: An amount of points
      properties:
        value:
          type: number
        cash_equivalent:
          $ref: '#/components/schemas/CurrencyAmount'
        conversion_rate:
          description: The conversion rate from points to cash, expressed as cents/pt
          type: number
    Tag:
      type: object
      description: Tag information
      properties:
        stay_tag:
          $ref: '#/components/schemas/StayTag'
        tag_reason:
          type: string
      required:
      - stay_tag
      - tag_reason
    RoomView:
      type: string
      enum:
      - Bay
      - Beach
      - Canal
      - City
      - Courtyard
      - Desert
      - Garden
      - Golf
      - Harbor
      - Hill
      - Lagoon
      - Lake
      - Park
      - Partial lake
      - Marina
      - Mountain
      - Ocean
      - Partial ocean
      - Pool
      - Resort
      - River
      - Sea
      - Partial sea
      - Water
      - Valley
      - Vineyard
    RatingForCategory:
      title: Rating for Category
      description: A category rating
      type: object
      properties:
        category:
          type: string
          description: Name of the category
        rating:
          type: number
          format: float
    Coordinates:
      title: Coordinates
      description: Latitude and longitude
      type: object
      properties:
        latitude:
          type: number
        longitude:
          type: number
      required:
      - latitude
      - longitude
      additionalProperties: false
    StaySummary:
      title: Stay Summary
      description: A stay summary - used in conjunction with a hotel summary
      type: object
      properties:
        checkin:
          type: string
          format: date
        checkout:
          type: string
          format: date
        checkin_str:
          type: string
        checkout_str:
          type: string
        nights:
          type: integer
        lowest_rate:
          description: Lowest total room rate
          type: number
          format: float
        lowest_rate_currency:
          description: Currency of lowest rate and nightly rate
          type: string
        nightly_rate:
          description: Average nightly rate for the lowest rate
          type: number
          format: float
        best_rate:
          description: Lowest total room rate - whether refundable or non-refundable
          $ref: '#/components/schemas/CurrencyAmount'
        best_nightly_rate:
          description: Average nightly rate for the lowest rate
          $ref: '#/components/schemas/CurrencyAmount'
        lowest_refundable_rate:
          description: Lowest total room rate - the best of refundable rates
          $ref: '#/components/schemas/CurrencyAmount'
        refundable_nightly_rate:
          description: Average nightly rate for the lowest refundable rate
          $ref: '#/components/schemas/CurrencyAmount'
        lowest_non_refundable_rate:
          description: Lowest total room rate - the best of non-refundable rates
          $ref: '#/components/schemas/CurrencyAmount'
        non_refundable_nightly_rate:
          description: Average nightly rate for the lowest non-refundable rate
          $ref: '#/components/schemas/CurrencyAmount'
        lowest_suite_rate:
          description: Lowest total suite room rate
          $ref: '#/components/schemas/CurrencyAmount'
        suite_nightly_rate:
          description: Average nightly rate for the lowest suite rate
          $ref: '#/components/schemas/CurrencyAmount'
        better_rooms_available:
          description: 'True when the search check-in is within 14 days and Travelport inventory shows rooms at higher tiers than the base room category. Factual signal based on current availability, not a prediction.

            '
          type:
          - boolean
          - 'null'
        lowest_rates_by_filter:
          description: 'Lowest rates keyed by filter type. Only populated for filters with matching rooms. Room type keys: suite, studio, standard. Bed type keys: 1_king, 1_queen, 2_queens, 2_double_beds.

            '
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FilterRate'
        lowest_points:
          description: Lowest points for any room at hotel for the search range
          type: integer
        lowest_nightly_points:
          description: Average nightly points for the lowest points rate
          type: integer
        lowest_points_amount:
          $ref: '#/components/schemas/PointsAmount'
        proximity:
          description: Distance from search location in m
          type: number
          format: float
        points_percentile:
          description: The percentile of the points deal
          type: number
        point_redemption_value:
          description: The number of cents per pt
          type: number
        cash_percentile:
          description: The percentile of the cash deal
          type: number
        cash_deal_score:
          description: The score of the deal. A value between 0 and 10, where 10 is a great deal.
          type: number
        points_deal_score:
          description: The score of the deal. A value between 0 and 10, where 10 is a great deal.
          type: number
        nights_free:
          description: The number of free nights for the points deal
          type: integer
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    FilterRate:
      type: object
      description: Lowest rate for a room/bed type filter, with optional room metadata
      properties:
        total:
          $ref: '#/components/schemas/CurrencyAmount'
        nightly:
          description: Average nightly rate for this filter, when displayable
          $ref: '#/components/schemas/CurrencyAmount'
        room_name:
          type: string
          description: Name/description of the room with the lowest rate for this filter
        image_url:
          type: string
          description: URL of an image of the room with the lowest rate for this filter
        area_sq_ft:
          type: integer
          description: Room area in square feet, if available
      required:
      - total
      - nightly
    HotelChain:
      title: Hotel Chain
      description: A hotel chain
      type: string
      enum:
      - Marriott
      - Hilton
      - Hyatt
      - IHG
      - Wyndham
      - Choice
      - Accor
      - Best Western
    CurrencyAmount:
      type: object
      description: An amount of money
      properties:
        value:
          type: number
        currency:
          type: string
        localized_amount:
          $ref: '#/components/schemas/LocalizedCurrencyAmount'
      required:
      - value
      - currency
    PartnerHotelSummary:
      type: object
      description: The non-personalized fields of search v3 HotelSummary in the same flat shape as deals results.
      properties:
        vervotech_property_id:
          type: integer
        provider_property_id:
          type: integer
        property_name:
          type: string
        property_address:
          type: string
        city_name:
          type: string
        country_code:
          type: string
        chain_name:
          type: string
          example: Marriott
        brand_name:
          type: string
          example: The Ritz-Carlton
        supplier_id:
          type: string
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        description:
          type: string
        year_built:
          type: integer
        year_last_renovated:
          type: integer
        stars:
          description: Number of stars
          type: number
          format: float
        average_guest_rating:
          description: Average guest rating
          type: number
          format: float
        review_count:
          description: The number of reviews for the property
          type: number
          format: integer
        category_ratings:
          description: Average ratings across various review categories, e.g. cleanliness, service, etc
          type: array
          items:
            $ref: '#/components/schemas/RatingForCategory'
        hero_image:
          description: URL of hero image
          type: string
        loyalty_program:
          description: Name of loyalty program
          type: string
        checkin_time:
          type: string
        checkout_time:
          type: string
        amenities:
          type: array
          items:
            $ref: '#/components/schemas/HotelAmenity'
        full_amenities:
          type: array
          items:
            $ref: '#/components/schemas/HotelAmenity'
        notable_amenities:
          description: Small, ordered set of decision-useful amenities for hotel detail pages.
          type: array
          items:
            type: string
        images:
          type: array
          items:
            $ref: '#/components/schemas/HotelImage'
        external_reviews:
          type: array
          items:
            $ref: '#/components/schemas/ExternalReview'
        hotel_themes:
          type: array
          items:
            $ref: '#/components/schemas/HotelTheme'
        rooms:
          type: array
          items:
            $ref: '#/components/schemas/RoomInfo'
        desirability_index:
          type: number
          description: A score representing the desirability of the hotel, based on various factors.
        is_all_inclusive:
          type: boolean
          description: Whether a stay here includes meals, drinks, and activities.
        is_adults_only:
          type: boolean
          description: Whether the property is adults-only.
        checkin:
          type: string
          format: date
        checkout:
          type: string
          format: date
        checkin_str:
          type: string
        checkout_str:
          type: string
        nights:
          type: integer
        lowest_rate:
          description: Lowest total room rate
          type: number
          format: float
        lowest_rate_currency:
          description: Currency of lowest rate and nightly rate
          type: string
        nightly_rate:
          description: Average nightly rate for the lowest rate
          type: number
          format: float
        best_rate:
          description: Lowest total room rate - whether refundable or non-refundable
          $ref: '#/components/schemas/CurrencyAmount'
        best_nightly_rate:
          description: Average nightly rate for the lowest rate
          $ref: '#/components/schemas/CurrencyAmount'
        lowest_refundable_rate:
          description: Lowest total room rate - the best of refundable rates
          $ref: '#/components/schemas/CurrencyAmount'
        refundable_nightly_rate:
          description: Average nightly rate for the lowest refundable rate
          $ref: '#/components/schemas/CurrencyAmount'
        lowest_non_refundable_rate:
          description: Lowest total room rate - the best of non-refundable rates
          $ref: '#/components/schemas/CurrencyAmount'
        non_refundable_nightly_rate:
          description: Average nightly rate for the lowest non-refundable rate
          $ref: '#/components/schemas/CurrencyAmount'
        lowest_suite_rate:
          description: Lowest total suite room rate
          $ref: '#/components/schemas/CurrencyAmount'
        suite_nightly_rate:
          description: Average nightly rate for the lowest suite rate
          $ref: '#/components/schemas/CurrencyAmount'
        better_rooms_available:
          description: 'True when the search check-in is within 14 days and Travelport inventory shows rooms at higher tiers than the base room category. Factual signal based on current availability, not a prediction.

            '
          type:
          - boolean
          - 'null'
        lowest_rates_by_filter:
          description: 'Lowest rates keyed by filter type. Only populated for filters with matching rooms. Room type keys: suite, studio, standard. Bed type keys: 1_king, 1_queen, 2_queens, 2_double_beds.

            '
          type: object
          additionalProperties:
            $ref: '#/components/schemas/FilterRate'
        lowest_points:
          description: Lowest points for any room at hotel for the search range
          type: integer
        lowest_nightly_points:
          description: Average nightly points for the lowest points rate
          type: integer
        lowest_points_amount:
          $ref: '#/components/schemas/PointsAmount'
        proximity:
          description: Distance from search location in m
          type: number
          format: float
        points_percentile:
          description: The percentile of the points deal
          type: number
        point_redemption_value:
          description: The number of cents per pt
          type: number
        cash_percentile:
          description: The percentile of the cash deal
          type: number
        cash_deal_score:
          description: The score of the deal. A value between 0 and 10, where 10 is a great deal.
          type: number
        points_deal_score:
          description: The score of the deal. A value between 0 and 10, where 10 is a great deal.
          type: number
        nights_free:
          description: The number of free nights for the points deal
          type: integer
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    RoomLayoutType:
      type: string
      enum:
      - Standard
      - Suite
      - Studio
    RoomQualifier:
      type: string
      enum:
      - Standard
      - Deluxe
      - Presidential
      - Executive
      - Penthouse
      - Bridal
      - Honeymoon
      - Junior
      - Mini
      - Premium
      - Premier
      - Superior
      - Terrace
      - Sky Terrace
      - Residential
      - Carnegie
      - Edwardian
    SearchLocationType:
      description: The type of search location
      type: string
      enum:
      - region
      - specific location
    SearchFilters:
      type: object
      description: Filters for a search request
      properties:
        ratings:
          type: array
          items:
            type: integer
          description: A list of ratings to filter by
        min_points_percentile:
          type: number
          description: The minimum percentile of the points deal
        max_points_percentile:
          type: number
          description: The maximum percentile of the points deal
        min_cash_percentile:
          type: number
          description: The minimum percentile of the cash deal
        max_cash_percentile:
          type: number
          description: The maximum percentile of the cash deal
        only_recommended_brands:
          type: boolean
          description: If true, only show hotels from brands that are recommended
        only_all_inclusive:
          type: boolean
          description: If true, only show all-inclusive resorts
        adults_only:
          type: boolean
          description: If true, only show adults-only properties. If false, only show family-friendly properties.
        brands:
          type: array
          items:
            type: string
          description: A list of brand names to filter results by (e.g. all-inclusive collections)
        include_airport_hotels:
          type: boolean
          description: If true, include airport hotels in the search results
        min_total_points:
          type: integer
          description: The minimum total points that the user is willing to spend
        max_total_points:
          type: integer
          description: The maximum total points that the user is willing to spend
        min_total_cash:
          type: integer
          description: The minimum total cash that the user is willing to spend
        max_total_cash:
          type: integer
          description: The maximum total cash that the user is willing to spend
        min_nightly_points:
          type: integer
          description: The minimum nightly points that the user is willing to spend
        max_nightly_points:
          type: integer
          description: The maximum nightly points that the user is willing to spend
        min_nightly_cash:
          type: integer
          description: The minimum nightly cash that the user is willing to spend
        max_nightly_cash:
          type: integer
          description: The maximum nightly cash that the user is willing to spend
        amenity_categories:
          type: array
          items:
            $ref: '#/components/schemas/AmenityCategory'
        num_rates:
          type: integer
          description: The number of rates to return
          default: 40
        sort_by:
          type: string
          description: The field to sort by
          enum:
          - redemption_rate_percentile
          - cash_percentile
          default: redemption_rate_percentile
        desirability_index:
          type: integer
          description: The desirability index to filter by
          maximum: 100
          minimum: 0
      additionalProperties: false
    RoomInfo:
      type: object
      description: Room information
      properties:
        room_name:
          type: string
        room_layout_type:
          $ref: '#/components/schemas/RoomLayoutType'
        room_qualifiers:
          type: array
          items:
            $ref: '#/components/schemas/RoomQualifier'
        bedroom_count:
          type: integer
        views:
          type: array
          items:
            $ref: '#/components/schemas/RoomView'
        service_tier:
          $ref: '#/components/schemas/RoomServiceTier'
        number_of_single_beds:
          type: integer
        number_of_twin_beds:
          type: integer
        number_of_full_beds:
          type: integer
        number_of_queen_beds:
          type: integer
        number_of_king_beds:
          type: integer
        area_sq_meter:
          type: number
        area_sq_ft:
          type: number
        accessible:
          type: boolean
        smoking:
          type: boolean
        number_of_sofa_beds:
          type: integer
        corner:
          type: boolean
        floor:
          type: string
    DateRange:
      title: Date Range
      description: A date range. To be used when searching for a stay with specific start and end dates
      type: object
      properties:
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        start_date_str:
          description: Start date in string format, e.g. 2023-10-01
          type: string
        end_date_str:
          description: End date in string format, e.g. 2023-10-02
          type: string
      required:
      - start_date
      - end_date
      additionalProperties: false
    HotelAmenity:
      title: Hotel Amenity
      description: An amenity specific to a hotel, in contrast to room amenities or rate amenities.
      type: object
      properties:
        name:
          type: string
          description: Name of the amenity
      required:
      - name
    PartnerHotelSearchResults:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/PartnerHotelSummary'
        total_result_count:
          type: integer
        available_amenities:
          type: array
          items:
            type: string
        available_image_categories:
          type: array
          items:
            type: string
        available_hotel_themes:
          type: array
          items:
            $ref: '#/components/schemas/HotelTheme'
        available_transfer_partners:
          type: array
          items:
            $ref: '#/components/schemas/TransferPartner'
        recommended_viewport:
          $ref: '#/components/schemas/Viewport'
        search_region:
          $ref: '#/components/schemas/Viewport'
      required:
      - results
      - total_result_count
      - available_amenities
      - available_image_categories
      - available_hotel_themes
    SearchDatesV2:
      title: Search Dates
      description: A set of search dates
      type: object
      properties:
        search_dates:
          type: array
          items:
            $ref: '#/components/schemas/DateRange'
        flexible_search_dates:
          type: array
          items:
            $ref: '#/components/schemas/FlexibleDateRange'
      additionalProperties: false
    Viewport:
      type: object
      properties:
        north:
          type: number
          format: float
          description: The north latitude (max)
        east:
          type: number
          format: float
          description: The east longitude (max)
        south:
          type: number
          format: float
          description: The south latitude (min)
        west:
          type: number
          format: float
          description: The west longitude (min)
      required:
      - north
      - east
      - south
      - west
      additionalProperties: false
    HotelTheme:
      title: Hotel Theme
      description: A theme for a hotel
      type: string
      enum:
      - all
      - adventure sport
      - beach
      - boutique
      - business
      - casino
      - city
      - eco-certified
      - family
      - golf
      - gondola recommended
      - historic
      - hot springs
      - luxury
      - natural
      - pet-friendly
      - romantic
      - shopping
      - ski
      - spa
      - winery
    TransferDuration:
      title: Transfer Duration
      description: The duration of a transfer
      type: string
      enum:
      - instant
      - one_day
      - two_days
      - three_days
    SearchLocationV2:
      title: Search Location
      description: Where to search. Provide at least one of name (a city or hotel name, matched as a case-insensitive substring of the hotel name and city), coordinates, search_viewport, region, chains, or themes. place_id, main_query, secondary_query, and types are Google Places fields used by Gondola's own apps and can be omitted.
      type: object
      properties:
        place_id:
          type: string
          description: The google place ID of the search location
        main_query:
          type: string
          description: The main query string, corresponds to structured_formatting.main_text
        secondary_query:
          type: string
          description: The secondary query string, corresponds to structured_formatting.secondary_text
        types:
          type: array
          items:
            type: string
          description: The google place types of the place ID - used to determine if location is a hotel or something else
        coordinates:
          $ref: '#/components/schemas/Coordinates'
        name:
          type: string
          description: A name used to search for a location.
        themes:
          type: array
          items:
            $ref: '#/components/schemas/HotelTheme'
        chains:
          type: array
          items:
            $ref: '#/components/schemas/HotelChain'
        region:
          $ref: '#/components/schemas/Region'
        search_location_type:
          $ref: '#/components/schemas/SearchLocationType'
        search_viewport:
          $ref: '#/components/schemas/Viewport'
      additionalProperties: false
    AmenityCategory:
      type: string
      enum:
      - Airport Shuttle
      - All Inclusive Packages
      - Fitness Center
      - Free Breakfast
      - Parking
      - Pet Friendly
      - Pool
      - Restaurant
      - Room Service
      - Snacks
      - Spa
    PartnerSearchRequest:
      type: object
      additionalProperties: false
      anyOf:
      - required:
        - hotel_ids
      - required:
        - search_location
      properties:
        search_location:
          $ref: '#/components/schemas/SearchLocationV2'
        search_occupants:
          $ref: '#/components/schemas/SearchOccupants'
        search_filters:
          $ref: '#/components/schemas/SearchFilters'
        search_dates:
          $ref: '#/components/schemas/SearchDatesV2'
        hotel_ids:
          type: array
          minItems: 1
          maxItems: 50
          uniqueItems: true
          items:
            type: integer
            minimum: 1
        currency:
          type: string
          default: USD
      description: 'Search by location: a city or hotel name, coordinates, a viewport, a region, hotel chains, or themes. No user context is accepted.'
    FlexibleDateRange:
      title: Flexible Date Range
      description: A flexible date range. To be used when searching for a stay of a particular number of nights within a set of dates
      type: object
      properties:
        start_date:
          type: string
          format: date
        end_date:
          type: string
          format: date
        start_date_str:
          description: Start date in string format, e.g. 2023-10-01
          type: string
        end_date_str:
          description: End date in string format, e.g. 2023-10-02
          type: string
        nights:
          type: integer
      required:
      - start_date
      - end_date
      - nights
      additionalProperties: false
    LocalizedCurrencyAmount:
      type: object
      description: A localized amount of money (no recursive localization)
      properties:
        value:
          type: number
        currency:
          type: string
      required:
      - value
      - currency
    RoomServiceTier:
      type: string
      enum:
      - Club
      - Concierge
      - Exec
      - Executive
      - Gold
      - Luxe
      - ME
      - Penthouse
      - Platinum
      - Premier
      - Premium
      - Red
      - Royal
      - Royalty
      - Signature
      - Standard
      - Superior
      - VIP
    HotelDateStatus:
      type: object
      properties:
        hotel_id:
          type: integer
        checkin:
          type: string
          format: date
        checkout:
          type: string
          format: date
        status:
          type: string
          enum:
          - available
          - missing_content
          - missing_rate
          - unavailable
        stay_summary:
          type:
          - object
          - 'null'
          allOf:
          - $ref: '#/components/schemas/StaySummary'
      required:
      - hotel_id
      - checkin
      - checkout
      - status
    Region:
      title: Geographic region
      description: A geographic region
      type: string
      enum:
      - Africa
      - Asia
      - Europe
      - North America
      - Oceania
      - South America
    TransferPartner:
      type: object
      properties:
        from_loyalty_program:
          type: string
        to_loyalty_program:
          type: string
        transfer_ratio:
          type: number
          format: float
        transfer_time:
          $ref: '#/components/schemas/TransferDuration'
      required:
      - from_loyalty_program
      - to_loyalty_program
      - transfer_ratio
    HotelImage:
      title: Hotel Image
      description: An image of a hotel and its rooms
      type: object
      properties:
        category:
          type: string
          description: Category of the image
        url:
          type: string
          description: URL of the image
      required:
      - category
      - url
    PartnerSearchResponse:
      type: object
      properties:
        search_results:
          $ref: '#/components/schemas/PartnerHotelSearchResults'
        hotel_date_statuses:
          type: array
          items:
            $ref: '#/components/schemas/HotelDateStatus'
        result_status:
          type: string
          enum:
          - complete
          - partial
          - unavailable
      required:
      - search_results
      - hotel_date_statuses
      - result_status
    SearchOccupants:
      title: Search Occupants
      description: A search occupant
      type: object
      properties:
        number_of_adults:
          type: integer
        children_ages:
          type: array
          items:
            type: integer
      required:
      - number_of_adults
      additionalProperties: false
    ExternalReview:
      type: object
      description: Curated content for a hotel
      properties:
        id:
          type: integer
        vervotech_property_id:
          type: integer
        mapped_property_name:
          type: string
        source_name:
          type: string
          description: The source of the curated content, e.g. Conde Nast
        article_name:
          type: string
          description: The name of the article
        source_link:
          type: string
          description: The link to the source of the curated content
        content:
          type: string
          description: The content of the curated article
        excerpt:
          type: string
          description: An excerpt of the content
        date_reviewed:
          type: string
          format: date
          description: The date the article was reviewed
      required:
      - id
      - vervotech_property_id
      - mapped_property_name
      - source_name
      - article_name
      - source_link
      - content
  securitySchemes:
    PartnerBearer:
      type: http
      scheme: bearer