Basic Hotel Concepts

This page contains information about the basic concepts used by Spotnana APIs for hotel bookings and other hotel-related workflows.

Overview

Spotnana allows travelers, travel arrangers, and agents to book hotel accommodations as part of business or personal travel. Our platform APIs provide the endpoints needed to manage all hotel booking-related actions, such as searching for hotels, viewing hotel details, checking prices, and canceling existing bookings.

Note: Refer to hotel workflow to understand the different actions you can perform using our hotel APIs.

How is a hotel booking related to a trip?

A unique PNR (i.e., a pnrId) is generated by Spotnana whenever a new hotel booking is made. This PNR ID must be associated with a trip (i.e., using tripId).

All travel bookings (i.e., hotel, air, rail, car, and miscellaneous) made using Spotnana must be associated with a trip (using the tripId). If the hotel booking is part of an existing trip, you can use the same tripId when creating a hotel booking. You can also use the create trip API to create a new trip.

How is a hotel booking related to an event?

Events allow organizations to create and manage company-wide events and and the travel bookings associated with them using the Spotnana platform. Refer to the event concepts page to learn more about events. For example, an event coordinator may invite travelers to book a hotel stay for an upcoming event. In this scenario, a hotel booking must be associated with both a trip (i.e., tripId) and an event (i.e., eventId).

Notes:

• The Get PNR API endpoint allows you to view the hotel booking details, as well as basic trip and event information.
• To understand more about trips and events, refer to the trip and event concepts pages.

Difference between a hotel and a room

A hotel is an establishment or a property that offers different rooms and services to travelers. The hotel can assign different prices to the rooms based on different factors such as the room size, the number of guests allowed, and other additional amenities or services. Based on room availability and the hotel policy, a traveler may be allowed to modify their room booking if they later wish to choose a different room.

Unique identifiers used in Hotel APIs

The following are some unique identifiers used in our hotel APIs:

• hotelDetailsKey: Assigned to each hotel in the search results based on the filters and preferences used for searching. This key is regenerated every time the search filters are changed.
• hotelId: A unique ID created for a hotel. The hotel’s hotelId will remain the same throughout the booking process.
• chainCode: Used to identify the hotel chain of a specific hotel within the Global Distribution System (GDS).
• priceValidateKey: Generated to capture the latest price of a hotel room. This key will change if the search filters are modified or if the hotel changes its price (e.g., due to demand).
• bookingKey: Created after the price of a hotel room has been validated and the details of the stay (i.e., occupancy dates, number of travelers, and other room preferences) are confirmed. The bookingKey is used to create a new booking. Its value will change if the price or booking details are modified.

What is rebooking?

Hotel room prices tend to change often due to demand and other factors. Some hotels allow travelers to rebook their existing bookings if the price changes. For example, a traveler may choose to rebook an existing hotel booking after noticing a price drop. This could potentially help them reduce their business travel expenses.

Our APIs allow travelers to rebook their existing PNR to optimize their travel spending (if the hotel allows it and the room is still available).

Supported booking modifications

Travelers can modify a hotel booking (depending on room availability and the hotel policies). Currently, our APIs support the following modifications to existing hotel PNRs:

• Check-in and check-out dates: Travelers can choose different check-in and check-out dates for their existing booking.
• Occupancy details: The number of adults or children accompanying the traveler can be modified.
• Room type: Most hotels offer different room types with varying amenities and services. Travelers can choose to change the room type within the same hotel booking. This may incur additional charges if they select a more expensive room.

Notes:

• While our APIs support the ability to modify bookings, the ability to make changes is contingent upon room availability and individual hotel policies.
• Many hotels charge a penalty for modifying an existing booking. In the modify hotel details API response you can review the penalty amount in the rooms > penaltyAmount field.

Hotel ratings

A hotel star rating system is a standardized method used to categorize hotels based on their quality, amenities, services, and facilities offered to customers. These ratings provide a quick way for travelers to understand the quality and level of service they can expect from a hotel. The ratings commonly range from 1 to 5 stars, with 5 indicating the highest quality services offered.

In Spotnana APIs, the star-based ratings are represented for each hotel in numeric values ranging from 0 to 5 (5 indicating a 5-star hotel). A hotel’s star rating can be viewed in the get hotel details API response in the hotelSpec > starRating > starRating field. The hotelSpec > starRating > ratingType field indicates if the rating is assigned by an official organization (e.g., government tourism board) or if it’s a self-assigned rating (i.e., rated by the property owners themselves).

Hotel cancellation

Hotels have cancellation policies that outline their terms and conditions for canceling a booking. These policies vary for different hotels. For example, a particular hotel may allow free cancellation until a specific date while another may only permit non-refundable bookings. It's important to review the cancellation policy before making or canceling a hotel room booking.

Cancellation scenarios

This section provides an overview of different cancellation scenarios that may occur when working with hotel APIs.

When you're booking a hotel, the get hotel details endpoint's response contains the rooms > rateOptions > cancellationPolicy object which can be used to view the hotel's cancellation policy.

The following table explains the different cancellation scenarios using the API fields present within the cancellationPolicy object:

If you've already made the hotel booking and wish to cancel, be sure to check the cancellation policy before canceling. Visit the hotel cancellation workflow to review the APIs used to cancel a hotel booking.

To review the cancellation policy for an existing booking, use the get PNR endpoint. In the response, the hotelPnr > room > cancellationPolicy object will contain the cancellation policy details. The following table explains the important fields and values present within the cancellationPolicy object: