KOOB API Documentation

Appearance

Hotel Search and availability ​

In order to book hotels, you need to go through 5 steps:

Hotel Search (v1) ​

Hotel Search v1 is deprecated and replaced by v2. Use the v2 endpoint for new implementations.

Hotel Search (v2) ​

Search for hotels based on various criteria including location, dates, and room requirements.

Endpoint: POST /api/v2/hotels

Parameters:

  • locale (query, optional): 2-letter language code (e.g., en, fr)

Request Body:

json
{
  "search": "Paris",
  "cities": ["city-id-1", "city-id-2"],
  "countries": ["country-id-1"],
  "regions": ["region-id-1"],
  "rooms": [
    {
      "adults": 2,
      "childrenBirthdates": ["2010-05-15", "2012-08-20"],
      "firstAdultNationality": "FR"
    }
  ],
  "startAt": "2024-06-15",
  "endAt": "2024-06-20",
  "stars": 4,
  "state": "available",
  "kinds": ["boutique", "luxury"],
  "styles": ["modern", "classic"],
  "sustainability": "eco-friendly",
  "maxPax": 4,
  "isRefundable": true,
  "isOnRequest": false
}

Response:

json
{
  "state": "finished",
  "data": [
    {
      "id": "hotel-123",
      "display_name": "Hotel Paris Palace",
      "address": "123 Champs-Élysées, Paris",
      "stars": 5,
      "lat": "48.8566",
      "lon": "2.3522",
      "price": 250.00,
      "currency": "EUR",
      "image_url": "https://example.com/hotel-image.jpg",
      "organizationId": 456,
      "organization": "Luxury Hotels Group",
      "country": "France",
      "region": "Île-de-France",
      "styles": ["luxury", "classic"],
      "kinds": ["boutique"],
      "allotmentAvailable": true,
      "minimumStay": 1,
      "isChannelManagerEnabled": false
    }
  ],
  "total": 25,
  "pageSize": 10,
  "resultsFrom": 0
}

Hotel Details ​

Get Hotel Information ​

Retrieve detailed information about a specific hotel.

Endpoint: GET /api/v1/hotels/{id}

Parameters:

  • id (path, required): Hotel ID
  • locale (query, optional): 2-letter language code (e.g., en, fr)

Response:

json
{
  "id": "hotel-123",
  "displayName": "Hotel Paris Palace",
  "address": "123 Champs-Élysées, Paris",
  "stars": 5,
  "lat": "48.8566",
  "lon": "2.3522",
  "currency": "EUR",
  "timezone": "Europe/Paris",
  "city": {
    "id": "paris-1",
    "title": "Paris"
  },
  "country": {
    "id": "fr",
    "title": "France"
  },
  "organization": {
    "id": "org-456",
    "displayName": "Luxury Hotels Group"
  },
  "rooms": [
    {
      "id": "room-1",
      "displayName": "Deluxe Room",
      "minCapacity": 1,
      "maxCapacity": 2,
      "description": "Elegant room with city view"
    }
  ],
  "primaryAttachment": {
    "imageUrl": "https://example.com/main-image.jpg"
  },
  "secondaryAttachments": [
    {
      "imageUrl": "https://example.com/image-2.jpg"
    }
  ]
}