Quickstart
Introductionβ
HotelX API is a powerful aggregation solution that allows you to get results from the largest network of Sellers in a single request. Whether it's at the hotel, room type, or rate plan level, you have the flexibility to aggregate data to meet your specific needs.
What sets HotelX API apart is its innovative structure: with a single integration, you can access the products of all Suppliers in the Marketplace, aggregate results, and easily add plugins or apps to extend functionality. This unique feature is complemented by HotelX's ability to provide pre-processed responses, ensuring your system tasks are efficient and hassle-free.
Β
Within HotelX API, Buyers work across three main areas:
- Content: static master data, including both FastX codes (Travelgate unique codes) and each Supplier's native codes and static information.
- Booking Flow: all required steps to complete an end-to-end booking flow.
- Booking Management: calls to manage existing bookings, such as retrieving or canceling reservations.
In this quickstart tutorial, you will learn how to create a simple sample booking.
Let's Get Started: How to Make a Bookingβ
HotelX offers a powerful GraphQL-based API that simplifies the process of booking hotels and managing reservations. Whether you're a seasoned developer or just getting started, this guide will walk you through the basics of using the API to make hotel bookings.
Prerequisitesβ
Endpointβ
HotelX uses different GraphQL hosts depending on the operation family:
-
Shopping / booking flow:
https://api-shopping.travelgate.com/graphql
Used forsearch,quote,book,cancel,booking, amendments,oneStepBook, andoneStepQuote. -
Content / static data:
https://api-content.travelgate.com/graphql
Used for hotel, board, destination, and other static master-data requests. -
Generic / shared GraphQL:
https://api.travelgate.com
Used for other shared GraphQL operations such as stats, logging, admin, and non-shopping API calls.
For HotelX booking and shopping requests, the main endpoint is:
https://api-shopping.travelgate.com/graphql
Request Headersβ
To interact with the API, you'll need to include the following request headers:
- Compression: this header is mandatory. At least one of the following values must be included in every request:
Accept-Encoding: gzip
or
Accept-Encoding: zstd
- Keep Alive: In order to increase performance and improve response times.
Connection: keep-alive
- API Key: You can find your API Key on the Travelgate website in API Keys.
Authorization: Apikey xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
If you don't have an API key yet, you can still test the upcoming query and mutation examples in the playground using your personal Travelgate bearer token and preloaded test data. Follow the Admin API Authentication Guide to obtain your token. The Development credentials and test data section below explains how to set the Authorization header and lists the test hotel data.
Supported Operationsβ
Lastly, please note that the HotelX API supports two types of operations:
-
Query: which are "read-only" and used for retrieving data from our system. You can use queries to search for hotels, check availability, and more. -
Mutation: which allow for changes, additions, or deletions of data within our system. This is where you can create bookings, update reservations, etc.
But now this quickstart guide will focus on the basics of using the HotelX API to make hotel reservations, so let's dive in and get started!
1. Find available hotels based on your search criteriaβ
The Search query is where the adventure begins in our shopping journey.
In HotelX, a Buyer can decide the scope of each Search request:
- Send the request to all connected Suppliers.
- Send the request to only specific Suppliers.
- Send the request to only specific accesses (credentials).
In this example, we'll explore availability for a single hotel using its FastX code and we will send the Search request to 2 specific accesses: '2' and '5647'.
Remember, an access is a unique code representing the credentials that a Supplier provides to allow you to query their portfolio. By specifying the accesses in your search, you can retrieve options from one or more Suppliers for the same hotel, all in a single request.
This step lets you explore your options before committing to a booking, ensuring you understand what each Supplier offers for the same property.
View the exampleShopping API
Β
If you execute the previous Search query by clicking the play button, you'll get a Search response with all available options and rates for the requested hotel and criteria. You can also expand View sample response to inspect a captured example.
For each option, you will receive key details such as Supplier, FastX and Supplier codes, room type, price, cancellation policies, and more. This example focuses on the essential fields, but HotelX API supports many additional capabilities. To explore all Search features, check the full search step documentation.
As explained in the detailed Search documentation, the more Suppliers and accesses you include in a single request, the larger the response can become.
To keep responses manageable and improve performance, we strongly recommend using an aggregation plugin such as Cheapest Price or Preference. With aggregation, HotelX can internally group equivalent options (for example, same hotel, board, and room type) across Suppliers and return only the N best options, based on your configuration.
This is one of the key advantages of FastX: in a single Buyer Search request, you can query all suppliers or only selected ones β Travelgate orchestrates the Seller-specific requests behind it β and then aggregate results automatically. π
2. Quote your selected optionβ
Now, let's dive into the exciting part! After carefully reviewing all the options in the search results and finding the hotel that perfectly suits your journey, it's time to move forward and request a quote. This Quote operation is like getting an exclusive preview before the grand booking. It provides you with up-to-the-minute pricing, a detailed breakdown of your expenses, and crucial information about cancellation policies.
To make this happen, you'll need to retrieve the optionRefId from the option of the search results that you want to valuate and use this value as the input for the Quote request:
View the exampleShopping API
Β
OptionRefID is a unique identifier assigned to each option. It must not be modified and must not be used or interpreted externally, as it is an internal Travelgate system identifier.
3. Confirm and book the option!β
You're almost there! After securing your quote and ensuring all the details align with your travel plans, it's time to proceed with the booking. In this step, you confirm your reservation and officially lock in your stay.
You'll need to provide the optionRefId returned in the Quote step and enter all the necessary passenger information. Upon a successful booking request, you'll receive a confirmation along with essential reservation details. Congratulations! Your hotel stay is now officially booked.
View the exampleShopping API
Β
Make sure to change the value of the clientReference field so that the Book can be confirmed correctly.
Development credentials and test dataβ
To help you get started, we provide test data that you can safely use during development. In the GraphQL editor, set the Authorization header to Apikey <YOUR_API_KEY>, replacing only the placeholder with your Apikey. Keep the Apikey prefix and the space after it.
Credentials
- Authorization:
Apikey <YOUR_API_KEY>for the playground and direct API requests. Replace only the placeholder and keep the prefix. - Authorization (without an API key): For the playground, set the
Authorizationheader to theBearerprefix, a space, and your personal Travelgate bearer token. - Client:
<YOUR_CLIENT>. Use the client assigned to your organization for the Certification process.
Example Suppliers and Hotels
-
Travelgate test supplier (supplier code: HOTELTEST - context: HOTELTEST)
- Access Code:
2 - Available Hotel Codes:
ES284122,BR1518
- Access Code:
-
Smyrooms test supplier (supplier code: TTHOTTEST - context: LOGITEST)
- Access Code:
5647 - Available Hotel Code:
BR1518
- Access Code:
-
FastX test supplier, to retrieve static master data such hotel and board codes (code: FASTX)
- Access Code:
34769
- Access Code:
These credentials and hotel codes are for development and testing purposes only. Please do not use them in a production environment, as they are shared and may not reflect live availability.
Next Stepsβ
Congratulations on completing this quickstart tutorial! π You've successfully learned the basics of creating a sample booking. But there's a world of knowledge waiting for you:
- Explore the Making Requests section to dive deep into how a GraphQL API works and maximize its performance.
- Discover various queries and mutations grouped by the following actions:
- Retrieve static information: Explore accessing static data, including how to obtain the list of unique FastX codes for hotels and boards, as well as the additional information provided by the Sellers.
- Make a booking: Learn how to book with more details.
- Manage reservations: Get the hang of reservation management.
- Unleash the full potential of your business with our diverse range of plugins.
Our documentation is a treasure trove of additional features and functionalities to enhance your business. To uncover these valuable resources, explore our documentation further and make the most of these methods. Enjoy your journey!