Our API is designed with having simplicity, scalability and speed in mind. In a broad sense, we have divided the documentation into five sections of "Authorization", "Search", Pre-book", "Booking", and "Static Content".

To begin using our API, you will need an api_key and an api_secret. If you do not posses these, contact our api sales team either through the website, or our email at api_support@hotelian.com.

The workflow of this API is as described in the chart below



To successfully make a reservation using our API, you need to follow these steps:

1) Search for multiple hotels

Search for multiple hotels using one of our endpoints: /city, /geo-nearby, /geo-box, or /hotel. Regardless of the endpoint you use, the search process is the same. For example, you can search for hotels in Paris using /city an Paris's id, or by including all the hotels in Paris in /hotel, or by using Paris's centroid in /geo-nearby. We'll return bookable prices available for each viable hotel.

For multi-hotel search methods, it's recommended to set best_price_only parameter to true (it's true by default) since it significantly reduces search time. By doing so, you will receive only one option for each hotel with the lowest price.

Note: In /city, all your codes should be inside the same country, and in /hotel, all your codes should be in the same city.

What is an Option? Each collection of one or more available rooms is referred to as an option in our API. Our search methods will return an array of options for every hotel. The number of rooms in each option will depend on your search request. For example, if you request one room, the resulting options will consist of one room each, and if you request two rooms, the resulting options will consist of two rooms each.

2) Get availabilities of a single hotel (no cache)

In order to get all the options and prices, you must search for a single hotel using /search/hotel and set the best_price_only parameter to false.

We recommend first searching for a city(or any other multi-hotel search methods described in #1), and once the user is interested in a specific hotel, search for the availabilities of that individual hotel to get the complete list of available options.

In other words, the only way that you can ensure you are getting all the prices and options of a hotel is to search it individually. Make sure you only do this after your user is interested in the hotel, since this is a technically expensive procedure.

3) Get-policies

Once the user chooses an option, you need to call /get-policies to update the prices and policies for your user. Make sure you don't call this endpoint before your user asks for the final step of the reservation. A free-cancellation option might become non-refundable and vice versa. If an option becomes unavailable (sold-out), it won't be included in the results; Make sure you handle this scenario accordingly.

What is a policy? We refer to cancellation penalty policies as a policy. These define the set of rules for each option's cancellation and the possible following refund.

4) Book

After calling /get-policies and refreshing the prices and policies for your user, you can call /book. In this step, you can provide a client-reference that you can later use to look up this reservation. Make sure you handle all errors and exceptions accordingly.

Note that you cannot book the same option twice.

At this point, your reservation could be done; You have to check the results.status in the response and act accordingly. A pending reservation must be checked every 10 minutes using GET /book/{id} to follow up on its new status, which can be either rejected, or confirmed. This process can take anywhere from 10 minutes up to hours depending on the case. We suggest you set up a scheduled task for these reservations.

You should note that the status might become rejected straightaway without going to pending at all. In this case, your balance will be refunded automatically and you can try booking other options, or other hotels.

Timeout: Make sure to set your timeout up to 120 seconds. This operation could take a while in some cases.

5) Reservation details

You can check the list of your bookings and filter them using GET /book, or check the details of a single booking in /book/{id}. Some reservations might have a pending status, and for these, you must check the details every 10 minutes to see if they change to confirmed or rejected.

6) Payments

If your account supports it, you must pay for a pay_later booking using PATCH /book/{id} before its initial deadline. Failure to do so will result in a canceled booking.

Note that you don't need to do this step if you call /book with pay_later=false.

7) Cancel

You can also cancel a confirmed booking if its check-in date has not yet been reached. According to the policies you received in /get-policies, you will receive a refund if any is applicable.

A cancellation can result in a cancellation pending status. In this case, a refund will not be possible until the case is investigated further.

Timeout: Make sure to set your timeout up to 120 seconds. This operation could take a while in some cases.

Postman API

To start using our API, Use our Postman workspace

To use our API, you'll need to include two headers in your HTTP requests: x-api-key and x-api-signature.

1) x-api-key:

This header should contain your API key, which you can obtain from Hotelian.com. Simply set it as the x-api-key HTTP header.

2) x-api-signature:

This header requires a bit more work. In addition to your API key, you'll also need your API secret and the current Unix time (in seconds). You must calculate a new x-api-signature value for each request you send.

The formula for calculating this header is: SHA256(SHA256(your_api_key + your_api_secret + current_unix_time))

Here are the steps to calculate the x-api-signature header:

• Concatenate your API key, API secret, and the current Unix time in seconds.
• Encode the resulting string twice using SHA256 hash method.
• Set the resulting string as the x-api-signature HTTP header.

Some notes:

• Do not commit your API secrets to your version control system (VCS) or Git: Version control systems are designed to remember changes, so if you commit your API key or secret, it will be almost impossible to remove them from the repository history. Instead, consider setting up environment variables in your programming language and store the secrets there. Also, make sure to add any files containing your secrets to your .gitignore file to prevent them from accidentally being committed.

• Calculate your x-api-signature header for each request: This header is time-based and will become invalid within seconds of its creation. Therefore, you must calculate a new x-api-signature header for every request you send to our API.

---

2-2. PHP sample of x-api-signature generation

function generateAPISignature(string $api_key, string $api_secret): string
{
    return hash(
        'sha256',
        hash('sha256', $api_key . $api_secret . ((string) time()))
    );
}

---

2-3. Postman Pre-request script

// Set your api key in postman environment as `API-KEY`
// Set your api secret in postman environment as `SECRET`
//Begin UTC creation
var utcDate = Math.floor(new Date().getTime() / 1000);

//Begin Signature Assembly
var publicKey = pm.environment.get("API-KEY");
var privateKey = pm.environment.get("SECRET");

var assemble = (publicKey+privateKey+utcDate);

//Begin SHA-256 Encryption
hash = CryptoJS.SHA256((CryptoJS.SHA256(assemble).toString()))
encryption = (hash.toString(CryptoJS.enc.Hex));

var Header = require('postman-collection').Header;
pm.request.headers.add(new Header("X-API-key: " + pm.environment.get('API-KEY')));
pm.request.headers.add(new Header("X-API-Signature: " + encryption));

---

2-4. Real Example

current_unix_time = 1642429744

your_api_key = hotelian_api_usd

your_api_secret = CDSmQDeq6rTgCSr8GvSyQG7IV9NBNycU

cat  = hotelian_api_usdCDSmQDeq6rTgCSr8GvSyQG7IV9NBNycU1642429744

first_hash = eb45597bfb366bbcf3be4dc089f8a877fb25a514cf54dd28191cc053a45f0079

your_signature = 080e0d6cd1e438d33d63e18098d53caaf92392a741204440a7ef45a0f264a783

1. Set your api key (in this example hotelian_api_usd) as the X-API-Key HTTP header in your request.
2. Set the calculated signature (in this example080e0d6cd1e438d33d63e18098d53caaf92392a741204440a7ef45a0f264a783) as the X-API-Signature HTTP header in your request.

Search for room availability of hotels within a selected period(check-in, check-out). Note that our search will return all the possible prices for every hotel. The currency of which the prices are returned in is the one set on your account.

Mandatory operations before reservation.

Reservation operations

Static Content API is designed to offer detailed information about all the hotels available in our Booking API. The API provides various CSV files that allow you to access the hotels' details, as well as a range of features such as cities, hotel images, hotel descriptions, hotel facilities, and hotel issues. The purpose of this API is to offer comprehensive information about the hotels and their attributes.

Please be aware that the static content you receive in the TEST environment is intended only for testing purposes. Once you have got live credentials, it is necessary to retrieve the static content again.