ML Flight Time Estimation

The Flight Time Estimation endpoint uses a trained machine learning model to predict gate-to-gate flight times between any two airports. The model accounts for aircraft performance characteristics, great-circle distance, and real-world routing constraints such as airspace restrictions and oceanic routing.

When the ML model is available, predictions are generated by a GradientBoostingRegressor trained on real flight data, achieving an R-squared score of 0.9754. When the model is not loaded, the endpoint falls back to a physics-based distance/speed calculation with route deviation adjustments.

---

Predict Flight Time

Estimate the gate-to-gate flight time between two airports.

GET /v3/ml/flight-time

Parameters

Parameter	In	Type	Required	Description
from	query	string	Yes	Origin airport code (ICAO or IATA), 3-4 characters (e.g., KJFK, JFK)
to	query	string	Yes	Destination airport code (ICAO or IATA), 3-4 characters (e.g., EGLL, LHR)
aircraft	query	string	No	Aircraft type code, up to 4 characters (e.g., B738, A320, C172). When omitted, default jet cruise parameters are used.

Example Request

curl -X GET "YOUR_API_BASE_URL/v3/ml/flight-time?from=KJFK&to=EGLL&aircraft=B77W" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

Example Response

{
  "origin": "KJFK",
  "destination": "EGLL",
  "aircraft_type": "B77W",
  "distance_nm": 2999.5,
  "estimated_minutes": 423,
  "estimated_hours_display": "7h 3m",
  "min_minutes": 372,
  "max_minutes": 474,
  "model_version": "1.0.0"
}

Example Request (without aircraft type)

curl -X GET "YOUR_API_BASE_URL/v3/ml/flight-time?from=LAX&to=NRT" \
  -H "X-RapidAPI-Key: YOUR_API_KEY"

Example Response

{
  "origin": "KLAX",
  "destination": "RJAA",
  "aircraft_type": null,
  "distance_nm": 4723.8,
  "estimated_minutes": 636,
  "estimated_hours_display": "10h 36m",
  "min_minutes": 560,
  "max_minutes": 712,
  "model_version": "1.0.0"
}

Response Fields

Field	Type	Description
origin	string	Origin airport ICAO code (resolved from IATA if necessary)
destination	string	Destination airport ICAO code (resolved from IATA if necessary)
aircraft_type	string or null	Aircraft type code used for the prediction, or null if not specified
distance_nm	float	Great-circle distance between the airports in nautical miles
estimated_minutes	integer	Estimated gate-to-gate flight time in minutes
estimated_hours_display	string	Human-readable flight time (e.g., 7h 3m)
min_minutes	integer	Lower bound estimate in minutes
max_minutes	integer	Upper bound estimate in minutes
model_version	string	Version of the model used. "fallback" indicates the physics-based estimator was used instead of the ML model.

Error Responses

Status	Description
404	One or both airport codes could not be resolved
500	Internal prediction error

---

How It Works

ML Model

The prediction model is a scikit-learn GradientBoostingRegressor trained on real-world flight duration data. The model uses five input features:

Feature	Description
distance_nm	Great-circle distance between origin and destination
aircraft_encoded	Encoded aircraft type identifier
cruise_speed_kts	Typical cruise speed for the aircraft type in knots
cruise_altitude_ft	Typical cruise altitude for the aircraft type in feet
route_deviation_factor	Multiplier accounting for routing detours (see below)

The model produces a point estimate in minutes. A confidence range is then computed: +/-12% for ML predictions, +/-15% for fallback estimates.

Route Deviation Factors

Real-world flight routes are often longer than the great-circle distance due to airspace restrictions, geopolitical constraints, and oceanic routing requirements. The API accounts for these automatically:

• Russian airspace ban -- Flights between Europe and East Asia that previously transited Russian airspace are rerouted via polar or southern corridors, adding approximately 25-30% to the distance.
• Conflict zones -- Routes avoid active conflict areas, potentially increasing flight distance.
• Oceanic routing -- Transoceanic flights follow organized track systems (e.g., North Atlantic Tracks) that may deviate from the direct path.

Fallback Estimator

When the ML model is not loaded, or for very short flights under 50 nautical miles, the endpoint uses a physics-based fallback:

1. Look up the cruise speed for the given aircraft type (default: 460 kts for unknown jets)
2. Multiply the great-circle distance by the route deviation factor
3. Calculate cruise time: (adjusted_distance / cruise_speed) * 60
4. Add 20 minutes for taxi, climb, and descent phases
5. Apply a minimum of 15 minutes

Supported Aircraft Types

The model recognizes a range of common aircraft types with tuned cruise parameters. Some examples:

Code	Aircraft	Cruise Speed	Cruise Altitude
B738	Boeing 737-800	460 kts	36,000 ft
A320	Airbus A320	450 kts	36,000 ft
B77W	Boeing 777-300ER	490 kts	39,000 ft
A388	Airbus A380	490 kts	39,000 ft
B789	Boeing 787-9	490 kts	41,000 ft
E175	Embraer E175	430 kts	35,000 ft
C172	Cessna 172	110 kts	8,000 ft

If an unrecognized aircraft type is provided, default jet cruise parameters (460 kts, 36,000 ft) are used.