SearchCriteria

Search criteria for availability

checkInstring<date-time>required

Check-in civil date encoded as UTC midnight: YYYY-MM-DDT00:00:00Z. Only the date prefix is honoured; time-of-day and offsets are ignored (2026-06-01T00:00:00+02:00 searches 1 June, not 31 May). Do not send Date.toISOString() of a local-midnight Date outside UTC — that yields the previous UTC day (e.g. 2026-05-31T22:00:00.000Z for 1 June in Europe) and cannot be recovered. Missing, empty, or unusable dates (including strings protojson cannot parse as Timestamp) return HTTP 200 with errors[] (ERR_CODE_BAD_REQUEST, ERR_TYPE_CLIENT), not 400/5XX. Check-in more than one day before today's UTC civil date, or checkOut not after checkIn, is the same client error and is not forwarded to providers. Today's and yesterday's UTC dates are always forwarded: yesterday's date is still today for a hotel west of UTC, and whether a stay is still bookable is the hotel's answer, not a calendar the aggregator can evaluate. When a time-of-day is stripped on an otherwise valid stay, the response includes a STAY_DATE_NORMALIZED warning with received and used.

Example: 2024-12-16T00:00:00Z

checkOutstring<date-time>required

Check-out civil date encoded as UTC midnight: YYYY-MM-DDT00:00:00Z. Same contract as checkIn: only the date prefix is honoured.

Example: 2024-12-18T00:00:00Z

hotelsstring[]

List of hotel codes to search. There is no destination field on availability criteria — resolve a destination via Content API (places / hotels/filter) and pass the resulting codes here.

Example: ["123","456"]

occupancies object[]required

Room occupancies

Possible values: >= 1

Array [

paxes object[]

Guests in the room (age only on search)

Array [

ageinteger<int32>required

Guest age

]

]

languagestring

Response language code (ISO 639-1)

Example: en

currencystring

Currency code (ISO 4217)

Example: USD

nationalitystring

Guest nationality code

Example: US

businessRules object

Business rules for search

businessRulesTypestring

Type of business rule

Example: CHEAPER_AMOUNT

optionsQuotainteger<int32>

Maximum number of options to return

Example: 5

exclusions object[]

Exclusion filters

Array [

typestring

Exclusion type

Example: connectionCode

keystring

Exclusion key

valuesstring[]

Exclusion values

]

additionalParams object

Additional parameters passed to the search.

Supported parameters:

• skipMarkup: When set to "true", skip margin calculation and return suggested price equal to net price. Useful for testing or when markup is handled externally. If no markup is configured for a connection and skipMarkup is false, a warning will be emitted in the response.
• skipHotelCodesMapping: When set to "true", hotel codes are sent directly to providers without mapping.

property name*string

resultFilters object

Optional post-processing filters applied after suppliers respond, before the response is returned to the client. They reduce response size and remove options that do not match your selection criteria. All fields are optional; omitting resultFilters (or sending an empty object) is a no-op.

Filters are stackable: when several are set they are evaluated in a single pass as a logical AND (refundable AND boardCodes AND cheapestOnly).

cheapestOnlyboolean

When true, keep at most one option per (connectionCode, hotelCode) group — the cheapest one according to cheapestStrategy. Use this to reduce payload size on broad searches where the UI only needs one rate per hotel.

Example: true

refundableFilterRefundableFilter (string)

Tri-state filter on the cancellation policy of each option.

• REFUNDABLE_FILTER_UNSPECIFIED (or omitted) — no filter.
• REFUNDABLE_FILTER_ONLY_REFUNDABLE — keep only options whose cancelPolicy.refundable is true.
• REFUNDABLE_FILTER_ONLY_NON_REFUNDABLE — keep only options whose cancelPolicy.refundable is false (or missing).

Possible values: [REFUNDABLE_FILTER_UNSPECIFIED, REFUNDABLE_FILTER_ONLY_REFUNDABLE, REFUNDABLE_FILTER_ONLY_NON_REFUNDABLE]

boardCodesstring[]

Whitelist of board codes (e.g. BB, HB, RO, AI). Comparison is case-insensitive (bb matches BB) against boardCode, falling back to providerBoardCode when the mapped code is empty. Empty array, null, or only-blank entries are treated as no filter. Up to 100 distinct codes are honored; extra entries are ignored defensively.

Example: ["BB","HB"]

cheapestStrategyCheapestStrategy (string)

Selects which price field is used to compare options when cheapestOnly is true.

• CHEAPEST_STRATEGY_UNSPECIFIED — same as CHEAPEST_STRATEGY_SUGGESTED (default).
• CHEAPEST_STRATEGY_SUGGESTED — compare by price.suggested (price after markup). Recommended for B2C displays where the customer-facing price drives the choice.
• CHEAPEST_STRATEGY_NET — compare by price.net (supplier net price). Useful when markup configurations vary across hotels and you want the lowest supplier cost. When the requested currency is set, options matching it are preferred over options in a different currency, regardless of nominal price. Currency comparison is case-insensitive (eur and EUR are equivalent).

Possible values: [CHEAPEST_STRATEGY_UNSPECIFIED, CHEAPEST_STRATEGY_SUGGESTED, CHEAPEST_STRATEGY_NET]

SearchCriteria

{
  "checkIn": "2024-12-16T00:00:00Z",
  "checkOut": "2024-12-18T00:00:00Z",
  "hotels": [
    "123",
    "456"
  ],
  "occupancies": [
    {
      "paxes": [
        {
          "age": 0
        }
      ]
    }
  ],
  "language": "en",
  "currency": "USD",
  "nationality": "US",
  "businessRules": {
    "businessRulesType": "CHEAPER_AMOUNT",
    "optionsQuota": 5
  },
  "exclusions": [
    {
      "type": "connectionCode",
      "key": "string",
      "values": [
        "string"
      ]
    }
  ],
  "additionalParams": {
    "skipMarkup": "true",
    "skipHotelCodesMapping": "true"
  },
  "resultFilters": {
    "cheapestOnly": true,
    "refundableFilter": "REFUNDABLE_FILTER_UNSPECIFIED",
    "boardCodes": [
      "BB",
      "HB"
    ],
    "cheapestStrategy": "CHEAPEST_STRATEGY_UNSPECIFIED"
  }
}