Displaying Essential Hotel Details

Welcome to the liteAPI guide on retrieving essential hotel details. This guide is intended for developers who have already completed simple bookings and now want to provide detailed information about hotels to their customers. By the end of this guide, you'll be able to display key information such as hotel photos, facilities, ratings, and room details.

Prerequisites

Before we begin, ensure that you have:

Created an account and obtained your API key.
Familiarized yourself with the "Preparing a List of Hotel IDs" guide to get the hotelId required for querying hotel details.

Overview

To retrieve hotel details, you'll need to use the /data/hotel endpoint with a specific hotelId. This will return comprehensive information about the hotel, including its name, address, facilities, room details, and images.

Example JSON Output

The following is a snippet of the JSON response you'll receive when querying the /data/hotel endpoint:

{
  "data": {
    "id": "lp3803c",
    "name": "Palette Resort Myrtle Beach by OYO",
    "hotelDescription": "Oceanfront Property with Luxurious Amenities...",
    "hotelImportantInformation": "Guests are required to show a photo identification...",
    "checkinCheckoutTimes": {
      "checkin": "04:00 PM",
      "checkinStart": "04:00 PM"
    },
    "hotelImages": [...],
    "country": "us",
    "city": "Myrtle Beach",
    "starRating": 2,
    "location": {
      "latitude": 33.67902,
      "longitude": -78.89426
    },
    "address": "703 South Ocean Boulevard",
    "hotelFacilities": [...],
    "rooms": [...]
  }
}

All of the hotel's details are inside the data object.

var hotelId = "lp3803c";
const targetUrl = 'https://api.liteapi.travel/v3.0/data/hotel?hotelId=' + hotelId;

const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    'X-API-Key': 'sand_c0155ab8-c683-4f26-8f94-b5e92c5797b9'
  }
};

fetch(targetUrl, options)
  .then(response => response.json())
  .then(response => 
  {
    var data = response.data;
    console.log(data)
  	//access the hotel data via calls here. 
  	// For example create HTML elements to display the JSON data
 	 	// const nameElement = document.createElement("h1");
  	// nameElement.textContent = "" + data.name;
  })
  .catch(err => console.error(err));

Displaying Hotel Basics

Hotel Name, Description, and Images

To display the hotel name and a brief description, use the following fields from the JSON response:

name
hotelDescription

To display hotel images, iterate over the hotelImages array and use the url and caption fields.

Example:

"data": {
  ...
  "name": "Palette Resort Myrtle Beach by OYO",
  "hotelDescription": "<p><strong>Oceanfront Property with Luxurious Amenities</strong>..."
  "hotelImages": [
    {
      "url": "https://snaphotelapi.com/hotels/322367676.jpg",
      "caption": "hotel building",
      "order": 1,
      "defaultImage": false
    },
    {
      "url": "https://snaphotelapi.com/hotels/399360240.jpg",
      "caption": "swimming pool",
      "order": 7,
      "defaultImage": false
    },
    ...
  ],
  ...
}

<h1>Palette Resort Myrtle Beach by OYO</h1>
<img width="350px" src="https://snaphotelapi.com/hotels/322367676.jpg" alt="hotel building" />
<img width="350px" src="https://snaphotelapi.com/hotels/399360240.jpg" alt="swimming pool" />
<p><strong>Oceanfront Property with Luxurious Amenities</strong>...</p>

Address and Location

To display the hotel's address and geographical location, use:

address
city
country
location.latitude
location.longitude

Example:

"data": {
  ...
  "address": "703 South Ocean Boulevard",
  "city": "Myrtle Beach",
  "country": "us",
  ...
}

<p>Address: 703 South Ocean Boulevard, Myrtle Beach, US</p>
<p><a href="https://maps.google.com/?q=33.67902,-78.89426">View Map</a></p>

Hotel Rating

To display the hotel's star rating and review count:

starRating
rating
reviewCount

Example:

"data": {
  ...
  "starRating": 2,
  "rating": 4.9,
  "reviewCount": 1599,
  ...
}

<p>Stars: 2 stars</p>
<p>Rating: 4.9</p>
<p>Reviews: 1599 reviews</p>

⭐️ Note: Stars or starRating refer to the amenities and facilities of the hotel, while rating refers to its reviews from guests. Don't confuse the two. This example, for instance, is a two star hotel, so while it may not have a giant pool or indoor gym, the rating of 4.9 shows the guests find the beach front stay to be an incredible experience.

Individual Hotel Ratings

In addition to showing the aggregate ratings, it is also possible to query the individual ratings. You can access the reviews by passing the hotelId to the /data/reviews endpoint.

const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    'X-API-Key': 'sand_c0155ab8-c683-4f26-8f94-b5e92c5797b9'
  }
};

fetch('https://api.liteapi.travel/v3.0/data/reviews?hotelId=lp3803c&timeout=4', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

The response will be in JSON with a data containing an array of all the individual reviews that can be iterated over and displayed.

{
  "data": [
    {
      "averageScore": 9,
      "country": "us",
      "type": "family with young children",
      "name": "Daisha",
      "date": "2024-06-20 04:10:14",
      "headline": "The stay was pleasant ,...",
      "language": "en",
      "pros": "it was beachfront , so it wasn’t a far walk at all .",
      "cons": "the kitchen area could have been more nicer ."
    },
    {
      "averageScore": 4,
      "country": "us",
      "type": "young couple",
      "name": "Diandra",
      "date": "2024-06-20 23:46:40",
      "headline": "Palette Myrtle Beach spares every...",
      "language": "en",
      "pros": "Spacious 1 bedroom Suite with a full kitchen. Comfy bed.",
      "cons": "Balcony door was stuck for duration of stay. Maintenance failed to fix on two attempts. Living room air conditioner was not producing cold air. The only other a c. unit in the suite was in the bedroom..."
    },
    ...
  ]
}

<h2>Reviews</h2>
<div>
  <h3>Daisha - The stay was pleasant,...</h3>
  <p>Score: 9/10</p>
  <p>Date: 2024-06-20</p>
  <p>Pros: it was beachfront, so it wasn’t a far walk at all.</p>
  <p>Cons: the kitchen area could have been nicer.</p>
</div>
<div>
  <h3>Diandra - Palette Myrtle Beach spares every...</h3>
  <p>Score: 4/10</p>
  <p>Date: 2024-06-20</p>
  <p>Pros: Spacious 1 bedroom Suite with a full kitchen. Comfy bed.</p>
  <p>Cons: Balcony door was stuck for duration of stay. Maintenance failed to fix on two attempts. Living room air conditioner was not producing cold air. The only other a/c unit in the suite was in the bedroom...</p>
</div>

Hotel Policies

To display important policies such as check-in/check-out times and special notes:

checkinCheckoutTimes.checkin
checkinCheckoutTimes.checkout
hotelImportantInformation

Example:

"data": {
  ...
    "hotelImportantInformation": "Guests are required to show a photo identification and credit card upon check-in...",
 		"checkinCheckoutTimes": {
      "checkin": "04:00 PM",
      "checkinStart": "04:00 PM"
    },
  ...
}

<p>Check-in: 04:00 PM</p>
<p>Check-out: 04:00 PM</p>
<p>Important Information: Guests are required to show a photo identification and credit card upon check-in...</p>

Displaying Cancellation Policies

To display the hotel’s cancellation policies, use the cancellationPolicies object. If there is an amount listed for a cancellation policy, that’s how much will be charged if the user cancels after that policy date. Some have multiple policies, in which case the policy with the cancelTime most recently passed will be used.

"cancellationPolicies": {
  "cancelPolicyInfos": [
    {
      "cancelTime": "2024-11-11 08:00:00",
      "amount": 712.39,
      "currency": "USD",
      "type": "amount",
      "timezone": "GMT"
    }
  ],
  "hotelRemarks": [],
  "refundableTag": "RFN"
}

Explanation:

The refundableTag has the value RFN, meaning it can be refunded.
This policy tells us that after November 11th at 8 am GMT, users will be charged the full room amount $712.39 if they cancel.
Since there is no policy in place before November 11th, and the room is marked RFN, any cancellation before then will refund the full amount.
For more information on cancelation policies and handling 0 amount policies, refer to the Canceling a Booking Guide.

Example

<h2>Cancellation Policies</h2>
<div>
  <h3>Policy</h3>
  <p>Cancel Time: November 11th, 2024, 08:00 AM GMT</p>
  <p>Amount Charged: $712.39 USD</p>
  <p>Refundable: Yes</p>
</div>

Displaying Hotel Facilities

There are two options for listing hotel facilities. hotelFacilities is an array of the facilities as strings, use it when needing to list out all the facilities in a list. The second option facilities is an array of objects, containing the name and facilityId. This option works best if you are looking to filter by facilities, or implement custom code or icons for specific facilities.

To list the facilities available at the hotel, iterate over either facility array.

Example:

"data": {
  ...
   "hotelFacilities": [
     "WiFi available",
     "Free WiFi",
     "Parking",
     "Free Parking",
     ...
  ],
  "facilities": [
    {
      "facilityId": 47,
      "name": "WiFi available"
    },
    {
      "facilityId": 107,
      "name": "Free WiFi"
    },
    ...
  ],
  ...
}

<h2>Facilities</h2>
<ul>
  <li>WiFi available</li>
  <li>Free WiFi</li>
  <li>Parking</li>
  <!-- Add more facilities as needed -->
</ul>

Displaying Room Details

Room details work a bit differently. While rooms may occasionally be listed with general hotel information, usually room information is needed when showing a rate. Clients are interested, not only in the hotel details, but also in knowing more about specific room the rate is attached to. This is where room mapping comes in, when querying for rates set roomMapping: true like so:

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    'X-API-Key': 'sand_c0155ab8-c683-4f26-8f94-b5e92c5797b9'
  },
  body: JSON.stringify({
    hotelIds: ['lp3803c'],
    occupancies: [{adults: 1}],
    currency: 'USD',
    guestNationality: 'US',
    checkin: '2024-12-30',
    checkout: '2024-12-31',
    roomMapping: true
  })
};

fetch('https://api.liteapi.travel/v3.0/hotels/rates', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

This will return a mappedRoomId as part of the rate offering if we have the hotel mapped in our system. This mappedRoomId that can be used to locate that specific rooms' photos and information by locating the rooms object with that id.

To display room details, iterate over the rooms array and extract relevant information from each room object like:

roomName
description
maxOccupancy
bedTypes
roomAmenities

In addition, to display the images, iterate over the room's photos array and use the url field.

Example:

"data": {
  ...
  	"rooms": [
        {
          "id": 5787126,
          "roomName": "Studio King",
          "description": "This studio includes an attached bathroom and a flat-screen TV and private balcony. The kitchenette features a stove, microwave and refrigerator.",
          "roomSizeSquare": 33,
          "roomSizeUnit": "m2",
          "hotelId": "57871",
          "maxAdults": 2,
          "maxChildren": 2,
          "maxOccupancy": 3,
          "bedTypes": [
            {
              "quantity": 1,
              "bedType": "Extra-large double bed(s) (Super-king size)",
              "bedSize": "181-210 cm wide"
            }
          ],
          "roomAmenities": [
            {
              "amenitiesId": 9,
              "name": "Telephone",
              "sort": 113
            }
          ],
          "photos": [
            {
              "url": "https://snaphotelapi.com/rooms-large-pictures/322367522.jpg",
              "imageDescription": "",
              "imageClass1": "hotel room",
              "imageClass2": "",
              "failoverPhoto": "https://q-xx.bstatic.com/xdata/images/hotel/max1200/322367522.jpg?k=a0a9f05828252228ab4a876fef3304616cc8260e776735d83322bebaa0e1fb45&o=",
              "mainPhoto": false,
              "score": 4.53,
              "classId": 1,
              "classOrder": 1
            },
            {
              "url": "https://snaphotelapi.com/rooms-large-pictures/322367511.jpg",
              "imageDescription": "",
              "imageClass1": "hotel room",
              "imageClass2": "",
              "failoverPhoto": "https://q-xx.bstatic.com/xdata/images/hotel/max1200/322367511.jpg?k=9c3b9357535b353eff4e1a7ac0c5088c7d331dbc3405264f455921436210dadf&o=",
              "mainPhoto": false,
              "score": 4.55,
              "classId": 1,
              "classOrder": 1
            },
            ...
         ]
      },
      ...
   ],
   ...
}

<h2>Rooms</h2>
<div>
  <h3>Studio King</h3>
  <img width="350px" src="https://snaphotelapi.com/rooms-large-pictures/322367522.jpg" />
	<img width="350px" src="https://snaphotelapi.com/rooms-large-pictures/322367511.jpg"  />
  <p>This studio includes an attached bathroom and a flat-screen TV and private balcony...</p>
  <p>Max Occupancy: 3 people</p>
  <p>Beds: 1 Extra-large double bed (Super-king size)</p>
  <h4>Amenities</h4>
  <ul>
    <li>Telephone</li>
    <!-- Add more amenities as needed -->
  </ul>
  <!-- Add more rooms as needed -->
</div>

Summary

This guide covered the most common information requested, but there is much more information in the JSON file that can be used depending on the purpose of what is being built. If you have questions about any of the fields not mentioned, please contact us or ask in the community discord server.