SearchRequest

Request payload for availability search

criteria objectrequired

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]

settings objectrequired

Common settings for all requests

requestIdstring

Unique request identifier for tracking

Example: req-123456789

connectionCodesstring[]required

List of provider connection codes to query

Possible values: >= 1

Example: ["testb-conn-1876","testb-conn-1877"]

auditTransactionsboolean

When true, responses may include auditData.transactions with supplier-level traces for debugging. Use sparingly in production; redact sensitive data in logs.

Default value: false

timeoutinteger<int32>

Client timeout hint in milliseconds; platform and supplier minimums may still apply (especially for book). For availability it is also clamped to the server maximum (60000 by default), and the clamped value is the budget forwarded to the connections, so a larger figure is silently reduced rather than honoured. No schema-level default is declared on purpose: this object is shared by every operation and the effective fallback is per-operation (availability uses 10000, book is considerably higher). Omit the field to take the server's fallback for the operation you are calling rather than sending one that would cut a longer operation short.

testModeboolean

When true, enables non-production / sandbox-oriented behaviour where supported for the connection.

Default value: false

debugData object

Additional debug data

property name*any

Additional debug data

SearchRequest

{
  "criteria": {
    "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"
    }
  },
  "settings": {
    "requestId": "req-123456789",
    "connectionCodes": [
      "testb-conn-1876",
      "testb-conn-1877"
    ],
    "auditTransactions": false,
    "timeout": 0,
    "testMode": false,
    "debugData": {}
  }
}