Shop_Lodging_Service_FindBestOffersRequest_v1

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/hotel-engine/json-schema/hotel-engine-v1-find-best-offers-request-schema.json",
  "title": "Shop_Lodging_Service_FindBestOffersRequest_v1",
  "x-generated": "2026-11-04",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/hotel-engine-lodgingshoppingservice-api-openapi.yml#/components/schemas/v1FindBestOffersRequest",
  "type": "object",
  "properties": {
    "criteria": {
      "$ref": "#/$defs/v1FindBestOffersRequestCriteria",
      "description": "The criteria to be used to identify and filter Properties and Offers."
    },
    "includePropertiesWithNoAvailability": {
      "type": "boolean",
      "default": "false",
      "description": "By default, only Properties that have rooms matching your criteria will be returned.\nThis differs from [LodgingShoppingService.FindBestOffersStreaming] which returns all considered properties.\nYou may wish to set this to true if you are building a shopping experience that indicates availability may differ with different criteria, such as dates, but streaming is not viable."
    },
    "sortMode": {
      "$ref": "#/$defs/v1FindBestOffersSortMode",
      "description": "The order in which the results will be returned."
    }
  },
  "$defs": {
    "shoplodgingservicev1RadiusSearch": {
      "type": "object",
      "properties": {
        "coordinates": {
          "$ref": "#/$defs/v1GeoPoint",
          "description": "Latitude and Longitude coordinates to use as the center point of the search."
        },
        "radius": {
          "$ref": "#/$defs/v1Distance",
          "title": "The size of the search area.\nDefault: 10 miles\nMinimum: 1 mile (~1.6 kilometers)\nMaximum: 50 miles (~80 kilometers)"
        }
      },
      "description": "A search area in a perfect circle around a central point.",
      "title": "Shop_Lodging_Service_RadiusSearch_v1"
    },
    "v1AnonymousAdult": {
      "type": "object",
      "description": "An adult traveler whose personal details have not yet been collected.",
      "title": "Common_AnonymousAdult_v1"
    },
    "v1AnonymousChild": {
      "type": "object",
      "properties": {
        "age": {
          "type": "integer",
          "format": "int32",
          "description": "The child's age on the date of travel.\nIf the child's birthday is during travel, use the age they will be at the end of travel."
        },
        "birthdate": {
          "type": "string",
          "title": "An ISO-8601-compliant date representing the child's birthdate.\nSee https://en.wikipedia.org/wiki/ISO_8601#Dates"
        }
      },
      "description": "A child traveler whose personal details have not yet been collected.\nA child's age is necessary to retrieve the correct prices.\nFailure to provide an accurate age may result in loss of bookings or refusal to provide service to the traveler.",
      "title": "Common_AnonymousChild_v1"
    },
    "v1AnonymousTraveler": {
      "type": "object",
      "properties": {
        "adult": {
          "$ref": "#/$defs/v1AnonymousAdult"
        },
        "child": {
          "$ref": "#/$defs/v1AnonymousChild"
        }
      },
      "description": "A traveler whose personal details have not yet been collected.",
      "title": "Common_AnonymousTraveler_v1"
    },
    "v1Distance": {
      "type": "object",
      "properties": {
        "value": {
          "type": "number",
          "format": "double",
          "description": "The distance quantity."
        },
        "unit": {
          "$ref": "#/$defs/v1DistanceUnit",
          "description": "The unit of distance measurement."
        }
      },
      "description": "The distance between two geographic points.",
      "title": "Common_Distance_v1"
    },
    "v1DistanceUnit": {
      "type": "string",
      "enum": [
        "DISTANCE_UNIT_MILE",
        "DISTANCE_UNIT_KILOMETER"
      ],
      "default": "DISTANCE_UNIT_MILE",
      "description": "The unit type for a distance measurement.\n\n - DISTANCE_UNIT_MILE: A mile in the imperial system of units.\n - DISTANCE_UNIT_KILOMETER: A kilometer in the international system of units (metric).",
      "title": "Common_DistanceUnit_v1"
    },
    "v1FindBestOffersRequestCriteria": {
      "type": "object",
      "properties": {
        "pointAndRadius": {
          "$ref": "#/$defs/shoplodgingservicev1RadiusSearch",
          "description": "Check the availability of up to `max_property_candidates` hotels nearest the center of the provided radius."
        },
        "propertyId": {
          "$ref": "#/$defs/v1PropertyIdSearch",
          "description": "Check the availability of properties as identified by the provided Engine Property IDs."
        },
        "checkInDate": {
          "type": "string",
          "title": "An ISO-8601-compliant date on which you will check in to the property.\nSee https://en.wikipedia.org/wiki/ISO_8601#Dates",
          "pattern": "^(?<year>[0-9]{4})-(?<month>(?:0[1-9])|(?:1[0-2]))-(?<day>(?:0[1-9])|(?:[1-2][0-9])|(?:3[0-1]))$"
        },
        "checkOutDate": {
          "type": "string",
          "title": "An ISO-8601-compliant date on which you will check out of the property.\nSee https://en.wikipedia.org/wiki/ISO_8601#Dates",
          "pattern": "^(?<year>[0-9]{4})-(?<month>(?:0[1-9])|(?:1[0-2]))-(?<day>(?:0[1-9])|(?:[1-2][0-9])|(?:3[0-1]))$"
        },
        "numRooms": {
          "type": "integer",
          "format": "int32",
          "default": "1",
          "title": "The number of rooms to book.\nMay not exceed 8",
          "maximum": 8.0,
          "minimum": 1.0
        },
        "currencyCode": {
          "type": "string",
          "title": "The 3-character ISO-4217 alphabetic currency code to be used to convey pricing information.\nhttps://www.iso.org/iso-4217-currency-codes.html",
          "pattern": "^[A-Z]{3}$"
        },
        "travelers": {
          "type": "array",
          "items": {
            "type": "object",
            "$ref": "#/$defs/v1AnonymousTraveler"
          },
          "description": "Describes the travelers for whom you are searching.\nChanges to the quantity or age of travelers has an impact on the Offer price.\nFailure to properly identify your travelers may incur additional charges at checkin or cancellation of the booking."
        },
        "salesChannel": {
          "$ref": "#/$defs/v1SalesChannel",
          "title": "If available, the sales channel for the customer"
        },
        "maxPropertyCandidates": {
          "type": "integer",
          "format": "int32",
          "default": "100",
          "description": "The maximum number of properties to be considered for Offers.\nProperties with no availability will count against this limit, but may not be returned if there is no availability.\nMay not exceed 250.\nThis limit is not honored when Property IDs are provided via [property_ids].",
          "maximum": 250.0,
          "minimum": 1.0
        }
      },
      "description": "Defines the base criteria used in a \"Best Offers\" search.",
      "title": "Shop_Lodging_Service_FindBestOffersRequestCriteria_v1"
    },
    "v1FindBestOffersSortMode": {
      "type": "string",
      "enum": [
        "FIND_BEST_OFFERS_SORT_MODE_UNSPECIFIED",
        "FIND_BEST_OFFERS_SORT_MODE_DISTANCE"
      ],
      "default": "FIND_BEST_OFFERS_SORT_MODE_UNSPECIFIED",
      "description": "Describes the various ways a [LodgingShoppingService.FindBestOffers] search maybe sorted.\n\n - FIND_BEST_OFFERS_SORT_MODE_UNSPECIFIED: No specific sort criteria will be used.\n - FIND_BEST_OFFERS_SORT_MODE_DISTANCE: Properties are returned in order of increasing distance.\nIn case of ties, Property names are sorted lexically.\nOnly valid when candidate properties are identified via [RadiusSearch] (`point_and_radius`).",
      "title": "Shop_Lodging_Service_FindBestOffersSortMode_v1"
    },
    "v1GeoPoint": {
      "type": "object",
      "properties": {
        "latitude": {
          "type": "number",
          "format": "double",
          "description": "The center-point latitude."
        },
        "longitude": {
          "type": "number",
          "format": "double",
          "description": "The center-point longitude."
        }
      },
      "description": "A single geographic point, defined by latitude and longitude.",
      "title": "Common_GeoPoint_v1"
    },
    "v1PropertyIdSearch": {
      "type": "object",
      "properties": {
        "propertyIds": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "title": "The list of Engine Property IDs.\nMinimum: 1\nMaximum: 250",
          "maxItems": 250.0,
          "minItems": 1.0
        }
      },
      "description": "A list of Engine Property IDs to shop for Best Offers.",
      "title": "Shop_Lodging_Service_PropertyIdSearch_v1"
    },
    "v1SalesChannel": {
      "type": "string",
      "enum": [
        "SALES_CHANNEL_UNKNOWN",
        "SALES_CHANNEL_MOBILE_NATIVE",
        "SALES_CHANNEL_MOBILE_WEB",
        "SALES_CHANNEL_WEB"
      ],
      "default": "SALES_CHANNEL_UNKNOWN",
      "description": "- SALES_CHANNEL_UNKNOWN: The sales channel cannot be determined.\n - SALES_CHANNEL_MOBILE_NATIVE: The customer is shopping via a mobile application.\n - SALES_CHANNEL_MOBILE_WEB: The customer is shopping via a mobile web browser.\n - SALES_CHANNEL_WEB: The customer is shopping via a web browser on a desktop or laptop computer.",
      "title": "Common_SalesChannel_v1"
    }
  }
}