Use this pageChatGPT Claude Cursor · OpenAPI · MCP

SearchCriteria

Search criteria for availability

checkInstring<date-time>required

Arrival day in the hotel's local calendar, encoded as YYYY-MM-DDT00:00:00Z. The T00:00:00Z suffix is only how the date travels; it is not a UTC instant. Pick the date from the hotel's time zone, not from UTC or your own: connections compare checkIn with today at the hotel and refuse a date already past there (fix_request). That is yesterday's UTC date once the hotel's local day has ended, and today's UTC date at hotels east of UTC once theirs has rolled over (from 17:00 UTC at UTC+7). 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: west of UTC, yesterday's date can still be today at the hotel, and the aggregator does not know each hotel's time zone. 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

Departure day in the hotel's local calendar, encoded as 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. When hotelCodeProvider is set, these are ids from that catalog and are translated to base codes before coverage and fan-out. exclusions of type connectionCode use the same catalog and are translated in the same lookup so they still match after rewrite.

Example: ["123","456"]

hotelCodeProviderstring

Catalog whose hotel ids are in hotels and in exclusions of type connectionCode. When set, the aggregator translates those ids to base codes before coverage and fan-out, so any connection (for example testb-conn-1876) can be searched with another catalog's ids. Empty or omitted: hotels are treated as base codes. Only this field is read; additionalParams.hotelCodeProvider is ignored.

Incompatible with additionalParams.skipHotelCodesMapping (true / 1): the search is not forwarded and returns HTTP 200 with errors[] (ERR_CODE_BAD_REQUEST, ERR_TYPE_CLIENT). An unknown catalog or missing mapping table is the same client error. Mapping lookup failure returns HTTP 200 with errors[] (ERR_CODE_BAD_RESPONSE, ERR_TYPE_SERVICE) and does not fan out.

Example: gog

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. When hotelCodeProvider is set, type=connectionCode values are ids from that catalog and are translated to base codes in the same lookup as hotels. Unmapped values are dropped. Other exclusion types are unchanged.

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. Incompatible with criteria.hotelCodeProvider.

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"
  ],
  "hotelCodeProvider": "gog",
  "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"
  }
}