Overview
Introduction
The Flights Live Prices API is used to search for, and return flight prices for a given route and set of dates.
The API takes an origin and destination for a given date and returns a list of possible flights that will be bookable by travellers.
You can see examples of the create endpoint with this postman collection:
You can see examples of the poll endpoint with this postman collection:
How we use it at Skyscanner
We use the /create and /poll Flights Live Prices endpoints to power flight searches on our main website.
When a user initiates a flight search, the first results (displayed immediately after clicking the 'search' button) are populated using the /create endpoint.
We do this to reduce the time to first result which gives travellers a better experience.
The rest of the results are retrieved from /poll endpoint. To the user, they see this as more results populating the results page and as the loading indicator progresses.
👉 Here is a sample in Skyscanner.
Endpoints
This API has 2 endpoints, /create and /poll.
/create
POST https://partners.api.skyscanner.net/apiservices/v3/flights/live/search/create
/create is used to initiate the search request. This endpoint returns an incomplete cached subset of results for a quicker time to first result.
/poll
POST https://partners.api.skyscanner.net/apiservices/v3/flights/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 inventories. The /poll endpoint is invoked with a sessionToken which is returned in the result of the /create call.
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 inventory results. Often, the best itineraries 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 |
queryLegs | origin and destination for the given search. See flights live prices API documentation for format |
adults | number of adults traveling |
Optional fields
Below are additional optional fields to modify the outcome of the request:
| Field name | Description |
|---|---|
childrenAges | Number of children traveling |
| Include carriers and agents | Options for search result to only contain inventory from specified carriers (airlines) and / or agents (OTAs) |
| Exclude carrier and agents | Options for search result to exclude inventory from specified carriers and / or agents |
includeSustainabilityData | Option for search to include flights emissions data. Defaults to true |
nearbyAirports | If set to true, the search will include airports near the specified origin airport. Only origin-side nearby airport support is available; nearby airports for the destination are not supported at this time. Defaults to false |
cabinClass | Class of travel to search for |
/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/v3/flights/live/search/poll/{ADD SESSION TOKEN}
The sessionToken expires after around an hour.
In this case, the API will return the following 400 response:
No sessions were found for the session token. Please retry with a new createSearch session
If the token is expired, you should use the createSearch endpoint and create a new sessionToken
Response /create and /poll
Fields
| Field name | Description |
|---|---|
Status | Indicates status of the search request is running or completed |
Action | Indicates how to treat the SearchResults contained in a SearchContent. Prior results should only be replaced if the action is explicitly RESULT_ACTION_REPLACED. |
Itineraries | Bookable itinerary which corresponds with what was requested in the search. A return trip will consist of 2 legs, while a one-way trip will consist of 1 leg. An itinerary will contain a deepLink field which takes the traveler to the booking page. |
Leg | Includes details about the flight leg from destination to origin. A leg has 1 segment if it is a direct flight, and can have multiple segments if there are multiple stopovers. |
Segment | Shows the individual stops in a leg. I.e.: if a leg has 1 stop, the segment will show details about the stopover such as the length of time and where the stopover location is. |
Places | Shows the individual stops in a leg. I.e.: if a leg has 1 stop, the segment will show details about the stopover such as the length of time and where the stopover location is. |
Carriers | Similar to places, carriers contains information about the airlines referenced in itineraries. |
Agents | Similar to places, agents contains information about the OTAs referenced in itineraries. |
Stats | Provides meta information regarding the itineraries returned. It contains the minPrice, minDurtation, maxDuration of the flights and also an aggregated object stops which contains the data of how are direct, have 1 stop, or multiple stops. Stats can be useful to get fastest/ longest trip amongst other things. |
Sorting options | Sorting options are used to help sort itineraries based on a preferred criteria. |