What is the maxFlightTime? about amadeus-ruby

[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.