HotelsResponse
auditData object
Processing time in milliseconds
errors object[]
Possible values: [CLIENT, SERVER]
warnings object[]
hotels object
Paginated list of hotels with optional next-page token.
hotels object[]
Hotel identifier (provider-specific code).
Name of the hotel.
descriptions object[]
Descriptions by language; always present, empty when none.
Description text content
ISO 639-1 language code
Category code (e.g. 3STAR, 4STAR).
Meal plan codes; always present.
mandatoryFee object[]
Mandatory fees; always present.
Fee name
Fee description
Fee amount
Whether the fee is included in the price
rooms object[]
Room types; always present.
Room code
Provider-specific room code
Maximum occupancy stated by the provider.
Canonical room code from mapping_rooms when mapped.
Provider code that supplied images/texts/beds when they were inherited via cross-provider fill (same hotel base + same bundleportRoomCode). Omitted when content comes from the room's own provider.
texts object[]
Room descriptions (when includeRoomDetail is true).
Type of text (e.g., description, shortDescription)
ISO 639-1 language code
Text content
images object[]
Room images (when includeRoomDetail is true).
Image code
Image URL
Display order
Type of media
Image caption
beds object[]
Bed information (when includeRoomDetail is true).
Bed type
Number of beds
amenities object[]
Amenities; always present.
Amenity code identifier
Amenity name
Amenity name in English
Amenity type/category
Amenity description
Canonical category for display/filtering (e.g. Pool, Gym, Room amenity)
Canonical subcategory for display/filtering (e.g. Pool, Wellness, Dining, RoomEquipment)
topAmenities object[]
Top amenities (ordered by top_amenities); always present.
Amenity code identifier
Amenity name
Amenity name in English
Amenity type/category
Amenity description
Canonical category for display/filtering (e.g. Pool, Gym, Room amenity)
Canonical subcategory for display/filtering (e.g. Pool, Wellness, Dining, RoomEquipment)
media object[]
Images/videos; always present.
Absolute media URL.
Display order as delivered by the provider.
True for the first image of the hotel.
location objectnullable
Address from provider; always present, null when missing.
Primary address line.
Secondary address line (backward compatibility).
City name from address.
State or province.
ISO 3166-1 alpha-2 from address.
Human-readable country name when countryCode is set; empty when unknown.
Postal or ZIP code.
Latitude coordinate.
Longitude coordinate.
contact objectnullable
Contact info; always present, null when missing.
Phone number
Email address
Website URL
Fax number
Provider identifier; always present.
Connection codes where this hotel is available; always present.
Base URL to prepend to media URLs (from provider metadata). Omit or empty = use media URL as-is.
Alias for imageBaseUrl (e.g. by-base-codes clients).
Provider-specific hotel code.
How starRating was resolved — "official" (provider property rating) or "category" (parsed from category string).
Primary destination code (first in closestDestinations).
closestDestinations object[]
Tourist destinations near the hotel (city, region); always present, empty when none.
Stable ID (place ID or provider code) for programs.
Human-readable name; empty when missing or not displayable.
Internal quality composite (0-100) used for ordering (blends location, reviews, value and popularity). Present when a valuation exists; uses neutral defaults for missing signals, so it is NOT a guest-review score. For reviews use reviewScore.
Guest review score (0-100) from REAL external reviews only. Null/absent when the hotel
has no reviews yet ("absent" = "not rated"); never a synthetic default. For an
always-present quality signal for ordering, use ranking instead.
Number of real guest reviews backing reviewScore. Null/absent when the hotel is not rated.
City name from address; also in location.city.
Canonical country ISO 3166-1 alpha-2 (from geo enrichment).
Human-readable country name when countryCode is set; empty when unknown.
places.id (UUID) of canonical city from geo enrichment.
GeoNames ID of canonical city when available.
Distance from hotel to city center in km.
Canonical region name (e.g. Costa Brava) when city has REGION parent.
places.id (UUID) of region place.
GeoNames ID of region when available.
IANA timezone of canonical city (e.g. Europe/Madrid).
places.id of nearest beach.
cityPois object[]
POIs near canonical city center (airports, etc.).
POI, AIRPORT
Distance from city center in km.
Hierarchical breadcrumb (e.g. Madrid, Community of Madrid, Spain) from places.path.
externalIds objectnullable
Cross-reference ids for agency mapping (provider property ids, Bundleport base code).
Bundleport canonical hotel base code.
providerPropertyIds objectnullable
Provider-native property ids keyed by content source code (e.g. {"example": "129046618"}). Provider-agnostic cross-reference map for mapping against an external property reference; any source may appear.
Number of hotels in this response.
Pagination token for the next page. Include in the next request's 'token' field. Valid 4 minutes; tied to original query criteria.
{
"auditData": {
"processTime": 0
},
"errors": [
{
"code": "string",
"type": "CLIENT",
"description": "string"
}
],
"warnings": [
{
"code": "string",
"type": "string",
"description": "string"
}
],
"hotels": {
"hotels": [
{
"code": "string",
"hotelName": "string",
"descriptions": [
{
"text": "string",
"language": "string"
}
],
"category": "string",
"propertyType": "string",
"chainCode": "string",
"boardCodes": [
"string"
],
"mandatoryFee": [
{
"name": "string",
"text": "string",
"price": 0,
"included": true
}
],
"rooms": [
{
"code": "string",
"roomCode": "string",
"maxOccupancy": 0,
"bundleportRoomCode": "string",
"contentSource": "string",
"texts": [
{
"type": "string",
"languageCode": "string",
"text": "string"
}
],
"images": [
{
"code": "string",
"url": "string",
"order": 0,
"mediaType": "string",
"caption": "string"
}
],
"beds": [
{
"type": "string",
"count": 0
}
]
}
],
"amenities": [
{
"code": "string",
"name": "string",
"nameEn": "string",
"type": "string",
"description": "string",
"category": "string",
"subcategory": "string"
}
],
"topAmenities": [
{
"code": "string",
"name": "string",
"nameEn": "string",
"type": "string",
"description": "string",
"category": "string",
"subcategory": "string"
}
],
"media": [
{
"url": "string",
"orderIndex": 0,
"isPrimary": true
}
],
"location": {
"address": "string",
"line2": "string",
"city": "string",
"state": "string",
"countryCode": "string",
"countryName": "string",
"postalCode": "string",
"latitude": 0,
"longitude": 0
},
"contact": {
"phone": "string",
"email": "string",
"website": "string",
"fax": "string"
},
"providerCode": "string",
"connectionCodes": [
"string"
],
"imageBaseUrl": "string",
"imageURL": "string",
"providerHotelCode": "string",
"exclusiveDeal": true,
"starRating": 0,
"starRatingSource": "string",
"destinationCode": "string",
"closestDestinations": [
{
"destinationCode": "string",
"destinationName": "string"
}
],
"ranking": 0,
"reviewScore": 0,
"reviewCount": 0,
"createdAt": "2024-07-29T15:51:28.071Z",
"updatedAt": "2024-07-29T15:51:28.071Z",
"city": "string",
"countryCode": "string",
"countryName": "string",
"canonicalCityPlaceId": "string",
"cityGeonameId": "string",
"distanceToCenterKm": 0,
"region": "string",
"regionPlaceId": "string",
"regionGeonameId": "string",
"cityTimezone": "string",
"distanceToBeachKm": 0,
"distanceToAirportKm": 0,
"distanceToTrainStationKm": 0,
"nearestAirportIata": "string",
"nearestBeachPlaceId": "string",
"nearestAirportPlaceId": "string",
"nearestTrainStationPlaceId": "string",
"cityPois": [
{
"placeId": "string",
"type": "string",
"name": "string",
"distanceKm": 0,
"iata": "string"
}
],
"locationPath": "string",
"externalIds": {
"bundleportBaseCode": "string",
"providerPropertyIds": {
"example": "129046618"
}
}
}
],
"count": 0,
"token": "string"
}
}