Overview

Introduction

The Hotels Live Prices API is used to search for and return hotel offers 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 pricing options 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 offers are retrieved from. These can be OTAs, hotel chains, or groups. Within the documentation they can also be referred as supply partners.
pricing option	An offer from a specific agent for a specific hotel. An agent may return multiple pricing options per hotel (e.g., different room types, board plans, or cancellation policies) but Hotel Live Pricing API will return only the most basic one that satisfies the applied search query and filtering criteria. Also referred to as offers.

Core concepts

Term	Description
session	The /create request is used to initiate a new search session for a given hotel search query. It returns a session token that is reused on every subsequent /poll request. The session token keeps state between /poll requests, enabling stable pagination. All sessions are time-constrained and can expire.
pagination	To keep responses lean and fast, pagination controls the amount of hotels to return for each API call. Responses include the total hotel results count so you can build reliable paging.
sorting	The API returns sort scores which you can apply to order the items within the UI. The API provides scores for both hotels and pricing options within each hotel. You can specify the sorting order type and direction for hotels. However pricing options sorting options are not configurable.
filtering	Hotel filters (such as star rating, price ranges, amenities, etc.) run on the server. Apply them on the /poll request to keep the result set consistent across pages. Client-side filtering is not recommended.

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 results in the centre are populated with the available offers 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 offers 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. For example pricing options are grouped based on the hotel that they're for.

👉 Here you can try out a search on your own.

note

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 session. In most cases, the response will not include any results. However in some cases it will return pricing options for up to the specified initial page size amount of hotels.

/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 offers. 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. The /poll endpoint is designed to be called repeatedly until the status field in the response is set to completed. After all results become available, you will be able to navigate through all results via pagination, or apply desired filters and sorting.

info

The sessionToken is time-bound. Session duration can vary but is no longer than 15 minutes. After a session expires, the API will return the following 400 response:

Session token is expired or invalid

If the token is expired, you should use the /create endpoint and initiate a new session.

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
initialPageSize	The number of hotels to return pricing options for. This should ideally be the amount of hotels that each page would have in your UI.
rooms	Number of rooms to book

Optional fields

Below are additional optional fields to modify the outcome of the request:

Field name	Description
childrenAges	List of children ages
includedAgentsIds	Options for search result to only include offers from specified agents.
excludedAgentsIds	Options for search result to exclude offers from specified agents.

/poll

POST https://partners.api.skyscanner.net/apiservices/v1/hotels/live/search/poll/{sessionToken}

The sessionToken comes from the /create endpoint response. It is used strictly only in the URL path.

Required fields

Requests to the /poll endpoint need to contain the following:

Field name	Description
pagination	Required to navigate results on page-by-page basis. Specifies the limit and offset (page size and cursor). Please use the formula offset = pageIndex × limit. To provide best experience possible you should always re-start from page 1 after changing filters or sort.

Optional fields

Below are additional optional fields to modify the outcome of the request:

Field name	Description
filters	Specifies any filters to be applied to the current search query. For example adding a FREE_CANCELLATION filter will make sure that all returned pricing options include a free cancellation policy.
sort	Specifies the sort criteria to be applied. This sorting preference is applied only to the hotels. The sorting of pricing options is not configurable. Please refer to How sorting works section below for types & direction of sorting available to hotels.

tip

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

Each /create or /poll response includes a status, the total hotel results, an agents map, the current page of results, and sorting metadata (score maps). While results are still streaming, some fields may be empty or partially populated. Continue polling until status is completed to retrieve the complete result set

How sorting works (hotels vs. pricing options)

There are two independent sorts returned in the response, each with a score map you apply on the client:

Hotels (configurable) - you choose type and direction in /poll. The response echoes these and returns a score list you use to order hotels.

• Direction:

  • ASCENDING - lowest to highest
  • DESCENDING - highest to lowest

• Type:

  • PRICE
  • GUEST_RATING
  • PROXIMITY
  • STAR_RATING
  • DISCOUNT
  • BEST

A full list of available sort types are documented in the Poll API reference.

Pricing options (not configurable) - always type: BEST, direction: DESCENDING. The response returns scores to order options within each hotel. BEST is a ranking devised by Skyscanner's internal algorithm, which uses a variety of factors (price, reviews, popularity, etc.), resulting in an well-rounded assessment.

Fields

Field name	Description
status	The status of the search request. For example running or completed
totalHotelResultCount	Total number of hotels within the results for the actual session and the applied filters.
agents	Information about the agents referenced in hotelsPricingOptions.
hotelInfo	Hotel information related to the search. For example, it will contain how far the hotel is to the location from the search query.
hotelContent	Static information about a specific hotel such as name, star rating, etc.
sortOptions	Hotel and pricing option sorting score maps, and also the applied sorting type and direction.

Check the API reference for additional detail.