PartnerSearchRequest

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/gondola-ai/json-schema/gondola-ai-partner-search-request-schema.json",
  "title": "PartnerSearchRequest",
  "description": "Search by location: a city or hotel name, coordinates, a viewport, a region, hotel chains, or themes. No user context is accepted.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/gondola-ai-openapi.json#/components/schemas/PartnerSearchRequest",
  "type": "object",
  "additionalProperties": false,
  "anyOf": [
    {
      "required": [
        "hotel_ids"
      ]
    },
    {
      "required": [
        "search_location"
      ]
    }
  ],
  "properties": {
    "search_location": {
      "$ref": "#/$defs/SearchLocationV2"
    },
    "search_occupants": {
      "$ref": "#/$defs/SearchOccupants"
    },
    "search_filters": {
      "$ref": "#/$defs/SearchFilters"
    },
    "search_dates": {
      "$ref": "#/$defs/SearchDatesV2"
    },
    "hotel_ids": {
      "type": "array",
      "minItems": 1,
      "maxItems": 50,
      "uniqueItems": true,
      "items": {
        "type": "integer",
        "minimum": 1
      }
    },
    "currency": {
      "type": "string",
      "default": "USD"
    }
  },
  "$defs": {
    "AmenityCategory": {
      "type": "string",
      "enum": [
        "Airport Shuttle",
        "All Inclusive Packages",
        "Fitness Center",
        "Free Breakfast",
        "Parking",
        "Pet Friendly",
        "Pool",
        "Restaurant",
        "Room Service",
        "Snacks",
        "Spa"
      ]
    },
    "Coordinates": {
      "title": "Coordinates",
      "description": "Latitude and longitude",
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number"
        },
        "longitude": {
          "type": "number"
        }
      },
      "required": [
        "latitude",
        "longitude"
      ],
      "additionalProperties": false
    },
    "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
    },
    "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
    },
    "HotelChain": {
      "title": "Hotel Chain",
      "description": "A hotel chain",
      "type": "string",
      "enum": [
        "Marriott",
        "Hilton",
        "Hyatt",
        "IHG",
        "Wyndham",
        "Choice",
        "Accor",
        "Best Western"
      ]
    },
    "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"
      ]
    },
    "Region": {
      "title": "Geographic region",
      "description": "A geographic region",
      "type": "string",
      "enum": [
        "Africa",
        "Asia",
        "Europe",
        "North America",
        "Oceania",
        "South America"
      ]
    },
    "SearchDatesV2": {
      "title": "Search Dates",
      "description": "A set of search dates",
      "type": "object",
      "properties": {
        "search_dates": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/DateRange"
          }
        },
        "flexible_search_dates": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/FlexibleDateRange"
          }
        }
      },
      "additionalProperties": false
    },
    "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": "#/$defs/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
    },
    "SearchLocationType": {
      "description": "The type of search location",
      "type": "string",
      "enum": [
        "region",
        "specific location"
      ]
    },
    "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": "#/$defs/Coordinates"
        },
        "name": {
          "type": "string",
          "description": "A name used to search for a location."
        },
        "themes": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/HotelTheme"
          }
        },
        "chains": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/HotelChain"
          }
        },
        "region": {
          "$ref": "#/$defs/Region"
        },
        "search_location_type": {
          "$ref": "#/$defs/SearchLocationType"
        },
        "search_viewport": {
          "$ref": "#/$defs/Viewport"
        }
      },
      "additionalProperties": false
    },
    "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
    },
    "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
    }
  }
}