Overview
Introduction
The Hotels Live Prices API is used to search for and return hotel quotes for any time window from the current day until one year from the current day.
The API takes a location entity ID, check-in and check-out dates, and basic traveller information, and returns a list of hotel offers that will be bookable by travellers.
Terminology
Throughout the documentation, you'll see the use of various terms. To eliminate uncertainty, here's a small explanation to establish the distinction between them.
| Term | Description |
|---|---|
hotels | Hotels are accommodation properties that offer rooms or stays |
agents | Agents are supply partners where the quotes are retrieved from. These can be OTAs, hotel chains, or groups |
How we use it at Skyscanner
To provide the best UXE, our APIs are asynchronous, meaning that once the Search is created (CreateSearch), a set of predefined filters and sorting orders are rendered in the UI. Values for some filters, such as hotel chain names, groups, and agents, will be dependent on the actual data returned, which will be built during the polling process.
The prices, along with the hotel's details and room characteristics, are loaded asynchronously. As results are loaded, the values on the filters on the left-hand side are updated, and the results in the centre are populated with the available quotes as they are received from our supply partners.
This asynchronous behaviour is achieved through polling calls. Each polling call checks for available results and returns them directly to the client, with the option to apply additional filtering or sorting conditions.
The polling made by the client should be active, meaning that the client will have to make multiple requests to receive all the available quotes and data info. The API returns results as soon as they are received. It's expected to take between 1 and 10 seconds to get the full set of results.
The above screenshot captures what you can build, including some example data points. We have:
- Quotes can be grouped based on the data points you receive for each quote.
- In the centre, we have cards with the specific hotels, their characteristics, and prices. Note that the same hotel can have multiple quotes since different agents might have similar offers.
👉 Here you can try out a search on your own.
Legal disclaimer on content availability
Skyscanner maintains contractual agreements with various supply partners that restrict our ability to distribute certain pricing information and content through our API services. As a result, the content and pricing available through our APIs may differ from what is displayed on skyscanner.net. As a result, certain pricing options will not be available as part of Skyscanner's Hotel Live Pricing API and review summaries will display average rating and number of reviews only.
Endpoints
This API has 2 endpoints, /create and /poll.
/create
POST https://partners.api.skyscanner.net/apiservices/v1/hotels/live/search/create
/create is used to initiate the search request.
/poll
POST https://partners.api.skyscanner.net/apiservices/v1/hotels/live/search/poll/{sessionToken}
/poll is used to retrieve the complete list of results. This usually takes some amount of time as our backend makes
calls to our full list of supply partners for quotes. The /poll endpoint is invoked with a sessionToken which is
returned in the result of the /create call. Note that the despite taking some seconds for the API to fetch all the
results the calls to the /poll endpoint are rapid, usually taking less than 100ms. The /poll endpoint is designed to
be called repeatedly until the status field in the response is set to completed.
Concepts
Create and poll workflow
There is a large variance in the time to first result and the time to last result as some supply partners take
longer to return results. Often, the cheapest quotes are returned from supply partners that take longer to return
results. This is why the API workflow has been split into the /create and /poll endpoints.
To learn more about the create and poll workflow, please see our create and poll guide
Request
/create
Required fields
Requests to the /create endpoint need to contain the following:
| Field name | Description |
|---|---|
market | Market where search is coming from. E.g.: UK |
locale | Language to be used for the search. E.g.: en-GB |
currency | Currency that the search result prices are returned in. E.g.: GBP |
entityId | Place entity id (i.e. Hotel, City, Nation, etc.) |
checkinDate | Date of check-in |
checkoutDate | Date of check-out. Must be at a later point than the check-in date. |
adults | Number of adults. Should be greater than or equal to 1 |
Optional fields
Below are additional optional fields to modify the outcome of the request:
| Field name | Description |
|---|---|
childrenAges | List of children ages |
rooms | Number of rooms to book |
includedAgentsIds | Options for search result to only include quotes from specified agents. |
excludedAgentsIds | Options for search result to exclude quotes from specified agents. |
/poll
The /create endpoint will return a sessionToken in the response which is used to invoke the /poll endpoint.
POST https://partners.api.skyscanner.net/apiservices/v1/hotels/live/search/poll/{sessionToken}
The sessionToken expires after around 5 minutes.
In this case, the API will return the following 400 response:
Session token is expired or invalid
If the token is expired, you should use the createSearch endpoint and create a new sessionToken
Pagination, filtering and sorting
Hotel searches can return thousands of results for some destinations.
To manage payload size, results are paginated and navigated via the /poll request.
Paging,
filtering, and sorting are all specified on the POLL calls and applied server-side while results are being accumulated.
Note that:
- Navigating between pages is done via subsequent POLL requests. Users typically only browse the first few pages which are the most relevant, so fetching the full result set is rarely necessary.
- Filtering can be provided on the POLL request, without the need of additional client-side filtering.
- You can sort by price, guest rating, proximity, star rating, discount, or a bespoke "best" score. Only the active sort criterion is returned as a single score per hotel in the response.
When changing filtering or sorting on POLL, treat it as a new result stream: request page 1 first, then continue paging (page 2, page 3, …) as needed.
Check the API reference for additional detail.
Response /create and /poll
Fields
| Field name | Description |
|---|---|
status | Indicates status of the search request is running or completed |
hotelsPricingOptions | Contains the search results with offers from different agents. Each agent might provide different pricing options for different hotels. |
agents | Contains information about the agents referenced in hotelsPricingOptions. Agents are supply partners where we get quotes from. |
hotelInfo | Hotel information related to the search. For example, it will contain how far the hotel is to the location from the query. |
hotelContent | Static information about a specific hotel such as name, star rating, etc. |
sortOptions | Sort results by price, distance from the searched location, star rating, or guest (review) rating. Each option supports ascending or descending order. |