FlightAware history API
The history API from FlightAware — 5 operation(s) for history.
OpenAPI Specification
openapi: 3.1.0
info:
title: Aero airports history API
version: 4.17.1
description: '# Introduction
AeroAPI is a simple, query-based API that gives software developers access
to a variety of FlightAware''s flight data. Users can obtain current or
historical data. AeroAPI is a RESTful API delivering accurate and
actionable aviation data. With the introduction of Foresight™, customers
have access to the data that powers over half of the predictive airline
ETAs in the US.
## Categories
AeroAPI is divided into several categories to make things easier to
discover.
- Flights: Summary information, planned routes, positions and more
- Foresight: Flight positions enhanced with FlightAware Foresight™
- Airports: Airport information and FIDS style resources
- Operators: Operator information and fleet activity resources
- Alerts: Configure flight alerts and delivery destinations
- History: Historical flight access for various endpoints
- Miscellaneous: Flight disruption, future schedule information, and aircraft owner information
## Development Tools
AeroAPI is defined using the OpenAPI Spec 3.0, which means it can be easily
imported into tools like Postman. To get started try importing the API
specification using
[Postman''s instructions](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/).
Once imported as a collection only the "Value" field under the collection''s
Authorization tab needs to be populated and saved before making calls.
The AeroAPI OpenAPI specification is located at:\
https://flightaware.com/commercial/aeroapi/resources/aeroapi-openapi.yml
Our [open source AeroApps project](/aeroapi/portal/resources)
provides a small collection of services and sample applications to help
you get started.
The Flight Information Display System (FIDS) AeroApp is an example of a
multi-tier application using multiple languages and Docker containers.
It demonstrates connectivity, data caching, flight presentation, and leveraging flight maps.
The Alerts AeroApp demonstrates the use of AeroAPI to set, edit, and
receive alerts in a sample application with a Dockerized Python backend
and a React frontend.
Our AeroAPI push notification [testing interface](/commercial/aeroapi/send.rvt)
provides a quick and easy way to test the delivery of customized alerts via AeroAPI push.
'
servers:
- url: https://{env}.flightaware.com/aeroapi
variables:
env:
default: aeroapi
enum:
- aeroapi
security:
- ApiKeyAuth: []
tags:
- name: history
paths:
/history/flights/{ident}:
get:
operationId: get_history_flight
summary: Get information for a historical flight
description: 'Returns historical flight info status summary for a registration, ident,
or fa_flight_id. If a fa_flight_id is specified then a maximum of 1
flight is returned, unless the flight has been diverted in which case
both the original flight and any diversions will be returned with a
duplicate fa_flight_id. If a registraion or ident is specified then a
start_date and end_date must be specified. The span between start_date
and end_date can be up to 7 days. No more than 40 pages may be requested
at once. Data is available from now back to 2011-01-01 00:00:00 UTC.
The field `inbound_fa_flight_id` will not be populated by this resource.
'
tags:
- history
parameters:
- name: ident
in: path
description: 'The ident, registration, or fa_flight_id to fetch. If using
a flight ident, it is highly recommended to specify ICAO flight
ident rather than IATA flight ident to avoid ambiguity and unexpected results.
Setting the ident_type can also be used to help disambiguate.
'
required: true
schema:
type: string
examples:
ident:
value: UAL4
reg:
value: N123HQ
fa_id:
value: UAL1234-1234567890-airline-0123
- name: ident_type
in: query
description: 'Type of ident provided in the ident parameter. By default, the passed
ident is interpreted as a registration if possible. This parameter can
force the ident to be interpreted as a designator instead.
'
schema:
type: string
enum:
- designator
- registration
- fa_flight_id
- name: start
in: query
description: 'The starting date range for flight results, comparing against flights''
`scheduled_out` field (or `scheduled_off` if `scheduled_out` is
missing). The format is ISO8601 date or datetime, and the bound is
inclusive. Specified start date must occur on or after 2011-01-01 00:00:00 UTC
and cannot be in the future. If using date instead of datetime, the
time will default to 00:00:00Z.
'
schema:
type: string
oneOf:
- format: date-time
- format: date
examples:
datetime:
value: '2021-12-31T19:59:59Z'
date:
value: '2021-12-31'
- name: end
in: query
description: 'The ending date range for flight results, comparing against flights''
`scheduled_out` field (or `scheduled_off` if `scheduled_out` is
missing). The format is ISO8601 date or datetime, and the bound is
exclusive. Specified end date must occur after 2011-01-01 00:00:00 UTC
and cannot be in the future. If using date instead of datetime, the
time will default to 00:00:00Z.
'
schema:
type: string
oneOf:
- format: date-time
- format: date
examples:
datetime:
value: '2021-12-31T19:59:59Z'
date:
value: '2021-12-31'
- in: query
name: max_pages
description: Maximum number of pages to fetch. This is an upper limit and not a guarantee of how many pages will be returned.
schema:
type: integer
default: 1
minimum: 1
- in: query
name: cursor
description: 'Opaque value used to get the next batch of data from a paged collection.
'
schema:
type: string
responses:
'200':
description: OK
content:
application/json; charset=UTF-8:
schema:
properties:
links:
type: object
nullable: true
description: 'Object containing links to related resources.
'
properties:
next:
type: string
format: uri-reference
description: 'A link to the next set of records in a collection.
'
required:
- next
num_pages:
description: Number of pages returned
type: integer
minimum: 1
flights:
type: array
items:
allOf:
- title: BaseFlight
type: object
properties:
ident:
type: string
description: 'Either the operator code followed by the flight number for the flight
(for commercial flights) or the aircraft''s registration (for general
aviation).
'
ident_icao:
type: string
nullable: true
description: 'The ICAO operator code followed by the flight number for the flight (for commercial flights)
'
ident_iata:
type: string
nullable: true
description: 'The IATA operator code followed by the flight number for the flight (for commercial flights)
'
actual_runway_off:
type: string
nullable: true
description: 'Actual departure runway at origin, when known
'
actual_runway_on:
type: string
nullable: true
description: 'Actual arrival runway at destination, when known
'
fa_flight_id:
type: string
description: 'Unique identifier assigned by FlightAware for this specific flight. If
the flight is diverted, the new leg of the flight will have a duplicate
fa_flight_id.
'
operator:
type: string
nullable: true
description: 'ICAO code, if exists, of the operator of the flight, otherwise the IATA code
'
operator_icao:
type: string
nullable: true
description: 'ICAO code of the operator of the flight.
'
operator_iata:
type: string
nullable: true
description: 'IATA code of the operator of the flight.
'
flight_number:
type: string
nullable: true
description: 'Bare flight number of the flight.
'
registration:
type: string
nullable: true
description: 'Aircraft registration (tail number) of the aircraft, when known.
'
atc_ident:
type: string
nullable: true
description: 'The ident of the flight for Air Traffic Control purposes, when known and different than ident.
'
inbound_fa_flight_id:
type: string
nullable: true
description: 'Unique identifier assigned by FlightAware for the previous flight of the
aircraft serving this flight.
'
codeshares:
type: array
nullable: true
description: 'List of any ICAO codeshares operating on this flight.
'
items:
type: string
codeshares_iata:
type: array
nullable: true
description: 'List of any IATA codeshares operating on this flight.
'
items:
type: string
blocked:
type: boolean
description: 'Flag indicating whether this flight is blocked from public viewing.
'
diverted:
type: boolean
description: 'Flag indicating whether this flight was diverted.
'
cancelled:
type: boolean
description: 'Flag indicating that the flight is no longer being tracked by
FlightAware. There are a number of reasons this could happen
including cancellation by the airline, but that will not always be the
case.
'
position_only:
type: boolean
description: 'Flag indicating that this flight does not have a flight plan, schedule, or other indication of intent available.
'
origin:
description: 'Information for this flight''s origin airport.
'
title: FlightAirportRef
type: object
nullable: true
properties:
code:
type: string
description: 'ICAO/IATA/LID code or string indicating the location where
tracking of the flight began/ended for position-only flights.
'
nullable: true
code_icao:
type: string
description: 'ICAO code
'
nullable: true
code_iata:
type: string
description: 'IATA code
'
nullable: true
code_lid:
type: string
description: 'LID code
'
nullable: true
timezone:
type: string
description: 'Applicable timezone for the airport, in the TZ database format
'
nullable: true
example: America/New_York
name:
type: string
description: 'Common name of airport
'
nullable: true
example: LaGuardia
city:
type: string
description: 'Closest city to the airport
'
nullable: true
example: New York
airport_info_url:
type: string
nullable: true
format: uri-reference
description: The URL to more information about the airport. Will be null for position-only flights.
required:
- code
- airport_info_url
destination:
description: 'Information for this flight''s destination airport.
'
title: FlightAirportRef
type: object
nullable: true
properties:
code:
type: string
description: 'ICAO/IATA/LID code or string indicating the location where
tracking of the flight began/ended for position-only flights.
'
nullable: true
code_icao:
type: string
description: 'ICAO code
'
nullable: true
code_iata:
type: string
description: 'IATA code
'
nullable: true
code_lid:
type: string
description: 'LID code
'
nullable: true
timezone:
type: string
description: 'Applicable timezone for the airport, in the TZ database format
'
nullable: true
example: America/New_York
name:
type: string
description: 'Common name of airport
'
nullable: true
example: LaGuardia
city:
type: string
description: 'Closest city to the airport
'
nullable: true
example: New York
airport_info_url:
type: string
nullable: true
format: uri-reference
description: The URL to more information about the airport. Will be null for position-only flights.
required:
- code
- airport_info_url
departure_delay:
type: integer
nullable: true
description: 'Departure delay (in seconds) based on either actual or estimated gate
departure time. If gate time is unavailable then based on runway departure
time. A negative value indicates the flight is early.
'
arrival_delay:
type: integer
nullable: true
description: 'Arrival delay (in seconds) based on either actual or estimated gate
arrival time. If gate time is unavailable then based on runway arrival
time. A negative value indicates the flight is early.
'
filed_ete:
type: integer
nullable: true
description: 'Runway-to-runway filed duration (seconds).
'
progress_percent:
type: integer
nullable: true
description: 'The percent completion of a flight, based on runway departure/arrival. Null
for en route position-only flights.
'
minimum: 0
maximum: 100
status:
type: string
description: 'Human-readable summary of flight status.
'
aircraft_type:
type: string
nullable: true
description: 'Aircraft type will generally be ICAO code, but IATA code will be given
when the ICAO code is not known.
'
route_distance:
type: integer
nullable: true
description: 'Planned flight distance (statute miles) based on the filed route. May
vary from actual flown distance.
'
filed_airspeed:
type: integer
nullable: true
description: 'Filed IFR airspeed (knots).
'
filed_altitude:
type: integer
nullable: true
description: 'Filed IFR altitude (100s of feet).
'
route:
type: string
nullable: true
description: 'The textual description of the flight''s route.
'
baggage_claim:
type: string
nullable: true
description: 'Baggage claim location at the destination airport.
'
seats_cabin_business:
type: integer
nullable: true
description: 'Number of seats in the business class cabin.
'
seats_cabin_coach:
type: integer
nullable: true
description: 'Number of seats in the coach cabin.
'
seats_cabin_first:
type: integer
nullable: true
description: 'Number of seats in the first class cabin.
'
gate_origin:
type: string
nullable: true
description: 'Departure gate at the origin airport.
'
gate_destination:
type: string
nullable: true
description: 'Arrival gate at the destination airport.
'
terminal_origin:
type: string
nullable: true
description: 'Departure terminal at the origin airport.
'
terminal_destination:
type: string
nullable: true
description: 'Arrival terminal at the destination airport.
'
type:
type: string
description: 'Whether this is a commercial or general aviation flight.
'
enum:
- General_Aviation
- Airline
scheduled_out:
type: string
format: date-time
nullable: true
description: 'Scheduled gate departure time.
'
example: '2021-12-31T19:59:59Z'
estimated_out:
type: string
format: date-time
nullable: true
description: 'Estimated gate departure time.
'
example: '2021-12-31T19:59:59Z'
actual_out:
type: string
format: date-time
nullable: true
description: 'Actual gate departure time.
'
example: '2021-12-31T19:59:59Z'
scheduled_off:
type: string
format: date-time
nullable: true
description: 'Scheduled runway departure time.
'
example: '2021-12-31T19:59:59Z'
estimated_off:
type: string
format: date-time
nullable: true
description: 'Estimated runway departure time.
'
example: '2021-12-31T19:59:59Z'
actual_off:
type: string
format: date-time
nullable: true
description: 'Actual runway departure time.
'
example: '2021-12-31T19:59:59Z'
scheduled_on:
type: string
format: date-time
nullable: true
description: 'Scheduled runway arrival time.
'
example: '2021-12-31T19:59:59Z'
estimated_on:
type: string
format: date-time
nullable: true
description: 'Estimated runway arrival time.
'
example: '2021-12-31T19:59:59Z'
actual_on:
type: string
format: date-time
nullable: true
description: 'Actual runway arrival time.
'
example: '2021-12-31T19:59:59Z'
scheduled_in:
type: string
format: date-time
nullable: true
description: 'Scheduled gate arrival time.
'
example: '2021-12-31T19:59:59Z'
estimated_in:
type: string
format: date-time
nullable: true
description: 'Estimated gate arrival time.
'
example: '2021-12-31T19:59:59Z'
actual_in:
type: string
format: date-time
nullable: true
description: 'Actual gate arrival time.
'
example: '2021-12-31T19:59:59Z'
required:
- ident
- fa_flight_id
- operator
- operator_iata
- flight_number
- registration
- atc_ident
- inbound_fa_flight_id
- codeshares
- blocked
- diverted
- cancelled
- position_only
- origin
- destination
- departure_delay
- arrival_delay
- filed_ete
- progress_percent
- status
- aircraft_type
- route_distance
- filed_airspeed
- filed_altitude
- route
- baggage_claim
- seats_cabin_business
- seats_cabin_coach
- seats_cabin_first
- gate_origin
- gate_destination
- terminal_origin
- terminal_destination
- type
- scheduled_out
- estimated_out
- actual_out
- scheduled_off
- estimated_off
- actual_off
- scheduled_on
- estimated_on
- actual_on
- scheduled_in
- estimated_in
- actual_in
- title: ForesightPredictionsAvailable
type: object
properties:
foresight_predictions_available:
type: boolean
description: Indicates if Foresight predictions are available for AeroAPI /foresight endpoints.
example: true
required:
- foresight_predictions_available
required:
- links
- num_pages
- flights
'400':
description: 'Incorrect parameter(s). Ident may be missing or not in fa_flight_id format or max_pages may be < 1. Request may be for data before earliest date or more than a 7 day span of results was requested.
'
content:
application/json; charset=UTF-8:
schema:
title: Error
type: object
properties:
title:
type: string
description: Short summary of the type of error encountered.
reason:
type: string
description: Error type name directly from the backend.
detail:
type: string
description: 'More detailed description of the error, possibly including information
about specific invalid fields or remediation steps.
'
status:
type: integer
description: The HTTP response code returned as part of the error.
required:
- title
- reason
- detail
- status
/history/flights/{id}/track:
get:
operationId: get_history_flight_track
summary: Get historical information for a flight's track
description: 'Returns the track for a historical flight as an array of positions.
Data is available from now back to 2011-01-01T00:00:00Z.
'
tags:
- history
parameters:
- name: id
in: path
description: The fa_flight_id to fetch
required: true
schema:
type: string
examples:
fa_id:
value: UAL1234-1234567890-airline-0123
- name: include_estimated_positions
in: query
description: Whether to include estimated positions in the flight track
schema:
type: boolean
responses:
'200':
description: OK
content:
application/json; charset=UTF-8:
schema:
properties:
positions:
type: array
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/flightaware/refs/heads/main/openapi/flightaware-history-api-openapi.yml