Flight Extensive Search

GET

Flight Extensive Search

The Extensive Flight Search allows you to find the prices of one-way or return flights between two airports over a large number of dates, and for a large variety of stay durations. The search doesn't return exact itineraries, but rather tells you the best price for a flight on a given day, for a stay of a given duration.

The search is based on our Extreme Search platform, which continually caches a large number of flight search results from a list of origin cities to a variety of destinations. Since it's a cached search, the response time is fast, but not all origin airports are available. Here is a list of the currently supported origin-destination IATA location pairs. We try to keep this list as fresh as possible for you, but be aware that it may not always be exactly up-to-date and it can change without warning.

That said, a price graph like this provides a powerful bargin shopping tool - allowing travelers with flexible itineraries to identify days on which they can get the cheapest flights to their destinations.

Resource URL

https://api.sandbox.amadeus.com/v1.2 /flights/extensive-search

Query Parameters


Name Values Description
apikey
(required)

API Key provided for your account, to identify you for API access. Make sure to keep this API key secret.

origin
(required)

IATA code of the city from which the traveler will depart. See the location and airport interfaces for more information.

destination
(required)

IATA code of the city to which the traveler is going

departure_date

Range of dates between which the traveler could depart. Dates are specified in the ISO 8601 yyyy-MM-dd date format. Ranges are inclusive and ranges of months will apply from the start to the end of the month. If just a single date is specified, only that date will be searched. By default, the date range starts today and applies up to 361 in the future is applied. Past dates are generally not supported, future dates should be in the next 361 days, although results start to become sparse after about 6 months in the future, as airlines may still be defining their schedules. The default is to search all future dates available.

one-way

When set to true, the query will be for a single trip from the origin to the destination. When this parameter is not provided, or is set to false, the query is for a round trip from the origin to the destination and back again.

duration

The allowed duration or range of durations of the trip, in days. This parameter must not be set if the one-way parameter is set to true.

direct

Limit the search to results that do not require the passenger to change plane?

max_price

Maximum price of trips to find in the result set, in the currency specified for this origin and destination pair in the cache contents spreadsheet. So, for example, if the origin is NYC, and the max price is 400, this means 400 USD. If the origin is PAR, and the max price is 400, this means 400 EUR. By default, no limit is applied

aggregation_mode

Specifies the granularity of results to be found. DAY is the default when one-way is true finds a result for departure date in the date range. STAY is the default otherwise and finds all round trip permutations for this route withim the given date range. DESTINATION finds one result, only the cheapest price for this route over the provided date range. WEEK finds the cheapest result for every week in the date range. Note that specifying a small granularity but a large search scope may result in a huge output. For some very large outputs, the API may refuse to provide a result.


Request Body

Make a request and see the response.

Make a request and see the response.

Make a request and see the response.

Working...

 

Response format - Flight Extensive Search

The successful (HTTP 200) response is returned as a JSON object, filled with certain piece of data. The exact format of the output will depend on the aggregation_mode provided.

Element Meaning Multiplicity
Root object
origin The IATA code of the city from which all proposed price results depart 1
currency The ISO 4217 currency code that will be used for all prices in this response 1
results An array of result objects, each summarizing an itinerary from the above origin to a potential destination for the traveler, sorted by price from cheapest to most-expensive. 0..n
Result object
destination The IATA code of the city or airport to which the traveler may go, from the provided origin 1
departure_date The date departure at the origin, in ISO 8601 date format yyyy-MM-dd, to go to the above destination 1
return_date The date at which the flight from the destination to the origin will arrive at the origin. The date is in ISO 8601 date format yyyy-MM-dd, in the local date of the origin 1
price The minimum total price for one adult passenger for a round trip from the origin to the destination and back. Always a string, formatted correctly for the provided currency 1
airline The 2 character alphanumeric IATA airline code of the airline that is responsible for selling the traveler this flight - also known as the Validating Carrier. See the airlines API for more information 1

 

 

Example: A few days in Las Vegas

 

Request

I want to make a 2 or 3 day trip to Las Vegas sometime between October and the end-of-the-year. When's the cheapest time to go?

http://api.sandbox.amadeus.com/v1.2/flights/extensive-search?origin=NYC&destination=LAS&departure_date=2015-07--2015-09&duration=2--3&apikey=<your API key>

Sample Response (actual response was much longer!)

{
	"origin": "NYC",
	"currency": "USD",
	"results": [
		{
			"destination": "LAS",
			"departure_date": "2015-09-12",
			"return_date": "2015-09-15",
			"price": "337.20",
			"airline": "VX"
		}, {
			"destination": "LAS",
			"departure_date": "2015-08-30",
			"return_date": "2015-09-01",
			"price": "346.70",
			"airline": "DL"
		}, {
			"destination": "LAS",
			"departure_date": "2015-07-14",
			"return_date": "2015-07-17",
			"price": "350.20",
			"airline": "DL"
		}, {
			"destination": "LAS",
			"departure_date": "2015-07-03",
			"return_date": "2015-07-05",
			"price": "524.70",
			"airline": "NK"
		}
	]
}

Following up an extensive search

Now that your users have dates in mind, a good next step is to do a low-fare search. You can formulate a low-fare search from your extensive search like this:

http://api.sandbox.amadeus.com/v1.2/flights/low-fare-search?origin=<origin>&destination=<destination>&departure_date=<departure_date>&return_by=<return_date>T23:59&apikey=<your API key>

 

If you wish to display ONLY the itinerary for the low price quoted by the inspiration search, you should also include the airline provided, and set the number_of_results to 1. If you set the max_price, you can also identify whether that low price is still available - but be aware that this may sometimes return no result, as the inspiration search is cached hourly, so occasionally the quoted price may no longer exist.

You might also want to propose a selection of hotels at their destination on those days. To do this, you first need the geocode of the destination, by calling

http://api.sandbox.amadeus.com/v1.2/location/<destination>?apikey=<your API key>

and from this result, use the airport geocode to make a hotel search, for example

http://api.sandbox.amadeus.com/v1.2/hotels/search-circle?check_in=<departure_date>&check_out=<return_date>&longitude=<longitude>&latitude=<latitude>&radius=15&apikey=<your API key>