A flight has one departure and one arrival, but a status feed carries several times for each, and they are not interchangeable.
| Time | What it is | When it exists |
|---|---|---|
| Scheduled | The timetable. Set when the flight was planned, changed rarely and usually days out. | Always. |
| Estimated | The airline's current expectation, revised as the day unfolds. | From a few hours before departure, sometimes earlier. |
| Actual | What happened, reported after the fact. | Once the event has occurred. |
A delay is the difference between estimated (or actual) and scheduled. A flight whose estimated time equals its scheduled time is on time, whatever the board says.
Gate and runway
Each of the three comes in two flavours, because a flight leaves twice. It leaves the gate (pushback, "out") and then the runway (take-off, "off"); it lands on the runway ("on") and then reaches the gate ("in"). Airline operations people call these OOOI times. Passengers experience gate times; everything a driver or a pickup cares about is a gate time too, because nobody can be met on the runway.
In FlightByte
Every time is present or absent, never guessed, and each has a UTC and a local form with the airport's time zone:
| Field | Meaning |
|---|---|
departure.times.scheduledGate | Timetable departure from the gate. |
departure.times.estimatedGate | Current expectation for leaving the gate. |
departure.times.actualGate | When it left the gate. |
departure.times.scheduledRunway, estimatedRunway, actualRunway | The same three for take-off. |
arrival.times.* | The same six for landing and reaching the gate. |
departure.bestTimeUtc, arrival.bestTimeUtc | Actual if known, else estimated, else scheduled. The one number to show. |
departure.delayMinutes, arrival.delayMinutes | Gate delay in minutes; negative when early. |
Every change to one of the six gate and runway times is its own event: departure.scheduled.changed, departure.estimated.changed, departure.actual.changed, and the three arrival.* counterparts, each with from, to and deltaMinutes. delay.increased and delay.decreased fire when the gate delay crosses your subscription's threshold. See Flights → The snapshot and Webhooks → Change types.
Two mistakes worth naming
Showing the scheduled time as if it were current. After the estimate exists, the scheduled time is history. Read bestTimeUtc unless you have a reason to show all three.
Treating an absent time as midnight. An estimate that is not there yet is undefined, not null and not 00:00. Code that formats it blindly prints a delay of several hours.