HotelFilterRequest

Filter hotel codes by criteria. Prefer connectionCodes (list of connection codes); providerCode is deprecated but still supported for backwards compatibility. At least one of connectionCodes or providerCode must be provided.

connectionCodesstring[]

Preferred. Connection codes; each resolved to provider for filtering.

providerCodestringdeprecated

Deprecated; use connectionCodes. Provider code issued for the connection.

Example: example

filters object

Filter criteria for hotels

canonicalCityIdstring

Filter by canonical city ID

Example: city_123456

countryCodestring

Filter by country code (ISO 3166-1 alpha-2)

Example: ES

categorystring

Deprecated: Use categories instead. Single category filter (e.g., '3STAR')

categoriesstring[]

Multi-category filter. Values can be:

• Numeric: "1", "2", "3", "4", "5" (auto-converted to "1STAR", etc.)
• Full format: "1STAR", "2STAR", "3STAR", "4STAR", "4STAR_SUP", "5STAR"

Example: ["3STAR","4STAR","5STAR"]

boardCodesstring[]

Filter by board/meal plan codes. Returns hotels with ANY of these boards.

Example: ["AI","HB","BB"]

roomCodesstring[]

Filter by room codes (future use)

hotelNamestring

Partial match search on hotel name (case-insensitive)

Example: Hilton

hasMediaboolean

When true, only hotels with media; when false, only without. Omit for no filter.

amenityCodesstring[]

Hotel must have ALL of these amenity base codes.

nearby object

Geo-proximity filter

latitudenumber<double>required

Latitude coordinate

Possible values: >= -90 and <= 90

Example: 39.4699

longitudenumber<double>required

Longitude coordinate

Possible values: >= -180 and <= 180

Example: -0.3763

radiusKmnumber<double>

Search radius in kilometers (max 500km)

Possible values: >= 0 and <= 500

Default value: 50

Example: 10

codeModestring

How to interpret facet codes (categories, boardCodes, etc.):

• "base": Bundleport/canonical codes
• "provider": Provider-native codes (default)

Possible values: [base, provider]

Default value: provider

returnHotelCodesstring[]

Which hotel code types to return in the response. Can include "base", "provider", or both. When omitted, BOTH base and provider codes are returned so clients can build the mapping between them (parity with aggregator/integrations). Base codes are resolved via the provider->base mapping; when a hotel has no base mapping yet, its provider code is echoed in the base field. When both are returned, the response also includes hotelCodes.pairs[] with explicit {base, provider} objects so you don't rely on index alignment.

Possible values: [base, provider]

Default value: ["base","provider"]

pageSizeinteger

Number of results per page (max 5000)

Possible values: >= 1 and <= 5000

Default value: 1000

cursorstring

Pagination cursor (hotel code to start after)

HotelFilterRequest

{
  "connectionCodes": [
    "string"
  ],
  "filters": {
    "canonicalCityId": "city_123456",
    "countryCode": "ES",
    "category": "string",
    "categories": [
      "3STAR",
      "4STAR",
      "5STAR"
    ],
    "boardCodes": [
      "AI",
      "HB",
      "BB"
    ],
    "roomCodes": [
      "string"
    ],
    "hotelName": "Hilton",
    "hasMedia": true,
    "amenityCodes": [
      "string"
    ],
    "nearby": {
      "latitude": 39.4699,
      "longitude": -0.3763,
      "radiusKm": 10
    }
  },
  "codeMode": "provider",
  "returnHotelCodes": [
    "base"
  ],
  "pageSize": 1000,
  "cursor": "string"
}