Skip to main content

Hotels Catalog

The Content API provides several hotel endpoints: list/get hotels, get by base codes, and filter hotel codes. Responses include geo enrichment (canonical city, country, region, closest destinations) when available.

Endpoints​

1. List or get hotels​

POST /content/hotels/v1/hotels

Use scope (preferred) or query for filters. When you send connectionCode, the provider is resolved automatically; send header X-Environment: test or prod as needed.

Get specific hotels:

{
  "scope": {
    "hotelCodes": ["12345", "67890"],
    "maxSize": 100
  }
}

List by destination:

{
  "scope": {
    "connectionCode": "CONN_1",
    "destinationCodes": ["BCN"],
    "maxSize": 100
  }
}

Pagination: Use the token from the response in the next request; tokens are valid for 4 minutes and tied to the same criteria.

2. Get hotels by base codes​

POST /content/hotels/v1/hotels/by-base-codes

Returns hotel content for a list of Bundleport base codes (from mapping). Use when your app is keyed by base code (e.g. multi-provider comparison).

{
  "baseCodes": ["BASE_001", "BASE_002"],
  "preferredContentSource": "VET",
  "includeAllSources": false
}

Response: one object per base code with primary (preferred or first available) and optional sources (per provider) when includeAllSources is true.

3. Filter hotel codes​

POST /content/hotels/v1/hotels/filter

Returns hotel codes (base and/or provider) matching filters. Use before availability search to reduce the set of hotels to query. Prefer connectionCodes (array); providerCode is deprecated.

{
  "connectionCodes": ["CONN_1"],
  "filters": {
    "canonicalCityId": "uuid-of-place",
    "categories": ["3STAR", "4STAR", "5STAR"],
    "boardCodes": ["AI", "BB"]
  },
  "returnHotelCodes": ["base", "provider"],
  "pageSize": 1000,
  "cursor": null
}

Supports keyset pagination via cursor and nextCursor.

Response structure (hotel object)​

Arrays such as descriptions, boardCodes, amenities, media, closestDestinations are always present (empty array when none). location and contact are always present but may be null.

Basic and content:

  • code – Hotel identifier (provider-specific; use in search)
  • hotelName, descriptions, category, boardCodes, mandatoryFee, rooms, amenities, media
  • location – Address, city, state, countryCode, countryName, postalCode, latitude, longitude
  • contact – Phone, email, website, fax

Provider and media:

  • providerCode, connectionCodes, providerHotelCode
  • imageBaseUrl / imageURL – Base URL to prepend to media URLs (from provider metadata); omit or empty means use media URL as-is

Geo enrichment (when available):

  • countryCode, countryName – Canonical country (ISO 3166-1 alpha-2 and human-readable name)
  • canonicalCityPlaceId – Place UUID of canonical city
  • cityGeonameId, distanceToCenterKm, cityTimezone
  • region, regionPlaceId, regionGeonameId – e.g. "Costa Brava"
  • closestDestinations – [{ "destinationCode": "...", "destinationName": "..." }] (e.g. city and region names)
  • locationPath – Breadcrumb (e.g. "Madrid, Community of Madrid, Spain")
  • destinationCode – Primary destination (first in closestDestinations)

Optional POI distances: distanceToBeachKm, distanceToAirportKm, distanceToTrainStationKm, nearestAirportIata, nearestBeachPlaceId, nearestAirportPlaceId, nearestTrainStationPlaceId, cityPois

Example response (minimal)​

{
  "auditData": { "processTime": 42 },
  "errors": [],
  "warnings": [],
  "hotels": {
    "hotels": [
      {
        "code": "12345",
        "hotelName": "Example Hotel Barcelona",
        "descriptions": [{ "text": "A beautiful hotel in the heart of Barcelona", "language": "en" }],
        "location": {
          "city": "Barcelona",
          "countryCode": "ES",
          "countryName": "Spain",
          "latitude": 41.3851,
          "longitude": 2.1734
        },
        "amenities": [{ "code": "WIFI", "name": "Free WiFi" }],
        "media": [{ "url": "https://example.com/hotel-image.jpg", "mediaType": "IMAGE", "isPrimary": true }],
        "boardCodes": ["RO", "BB", "HB"],
        "mandatoryFee": [],
        "rooms": [],
        "providerCode": "VET",
        "connectionCodes": ["CONN_1"],
        "countryName": "Spain",
        "canonicalCityPlaceId": "uuid-city-barcelona",
        "closestDestinations": [
          { "destinationCode": "uuid-city", "destinationName": "Barcelona" },
          { "destinationCode": "uuid-region", "destinationName": "Catalonia" }
        ],
        "locationPath": "Barcelona, Catalonia, Spain"
      }
    ],
    "count": 1,
    "token": null
  }
}

Pagination (list hotels)​

let token = null;
let allHotels = [];

do {
  const result = await getHotels({
    scope: { maxSize: 1000 },
    token,
  });
  allHotels.push(...result.hotels.hotels);
  token = result.hotels.token;
} while (token);

Next Steps​