What is the maxFlightTime?

[jtFrancisco]

I have a question about the maxFlightTime?

I asked it on Stack Overflow here:
https://stackoverflow.com/questions/66391335/how-to-set-the-maxflighttime-in-a-flight-offers-search-with-the-amadeus-api

Here is the 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?

[anthonyroux]

Hi,

Thanks for raising this issue, you are right the description of this parameter is not clear at all, the team is going to change it.
maxFlightTime is a bit complex and not easy to use (this feature is mainly used by big travel agencies...). The number is a percentage expressing how much longer you are ready to accept the flight duration to be, as compared to the shortest flight that exists for this search criteria, not very clear right?

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.

I hope it clarifies a bit how this works (I do agree it is not easy to understand and we will update the API documentation very soon).
I have raised a question to the API development team about why using 100 in my example doesn't return any flight, I would have expected to have the shortest flight available. I will keep you informed when I have more information.

Don't hesitate if you need more explanations.