How to set the maxFlightTime in a flight offers search with the Amadeus API?

Question

I am making a POST to the Amadeus API for flight offers.

I am trying to set the maxFlightTime parameter.

The API documentation says:

maxFlightTime number example: 200 This option allows to modify the value for the Elapsed Flying Time (EFT) masterPricer option

• https://developers.amadeus.com/self-service/category/air/api-doc/flight-offers-search/api-reference

My question is: What does this parameter expect? The documentation says a number and provides 200 as an example.

What does the number represent? Is it minutes, hours, or something different?

Answer 1

maxFlightTime is a bit complex to use. The number is a percentage expressing how much longer the flight offers you want to find can be compared to the shortest flight that exists for these search criteria.

Let's take an example: We are looking for a flight from MAD to SFO (and we are returning only 1 offer for the sake of the example) using the POST endpoint of Flight Offers Search:

JSON Body:

{
    "currencyCode": "EUR",
    "originDestinations": [
        {
            "id": "1",
            "originLocationCode": "MAD",
            "destinationLocationCode": "SFO",
            "departureDateTimeRange": {
                "date": "2021-05-01",
                "time": "10:00:00"
            }
        }
    ],
    "travelers": [
        {
            "id": "1",
            "travelerType": "ADULT",
            "fareOptions": [
                "STANDARD"
            ]
        }
    ],
    "sources": [
        "GDS"
    ],
    "searchCriteria": {
        "maxFlightOffers": 1,
        "flightFilters": {
            "cabinRestrictions": [
                {
                    "cabin": "ECONOMY",
                    "coverage": "MOST_SEGMENTS",
                    "originDestinationIds": [
                        "1"
                    ]
                }
            ]
        }
    }
}

If you check the JSON response you will see that the offer is MAD to IST (duration PT4H15M so 4h15) and IST to SFO (duration PT13H20M so 13h20M) so in total duration of 17h35. Note that this API always returns the cheapest flight offers for the given criteria.

If now we want to do the same request adding maxFlightTime but we don't want to have such a long trip, we want to have a maximum total duration of 110% longer than the shortest flight available.

We can use this JSON body

{
    "currencyCode": "EUR",
    "originDestinations": [
        {
            "id": "1",
            "originLocationCode": "MAD",
            "destinationLocationCode": "SFO",
            "departureDateTimeRange": {
                "date": "2021-05-01",
                "time": "10:00:00"
            }
        }
    ],
    "travelers": [
        {
            "id": "1",
            "travelerType": "ADULT",
            "fareOptions": [
                "STANDARD"
            ]
        }
    ],
    "sources": [
        "GDS"
    ],
    "searchCriteria": {
        "maxFlightOffers": 1,
        "flightFilters": {
            "maxFlightTime": 110,
            "cabinRestrictions": [
                {
                    "cabin": "ECONOMY",
                    "coverage": "MOST_SEGMENTS",
                    "originDestinationIds": [
                        "1"
                    ]
                }
            ]
        }
    }
}

This is the response you will get: MAD to DFW for a duration of PT10H35M (10h35) and then DAL (another Dallas Airport?) to SFO for a duration of PT4H4M (4h04) so a total duration of 14h39.

This is why maxFlightTime can only be between 100 and 999.

The API specification is not very clear for this parameter, we will update it very soon.