openapi: 3.0.2
info:
title: AeroAPI
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.
tags:
- name: flights
- name: foresight
description: |
Foresight endpoints provide access to FlightAware's Foresight predictive models and
predictions for key events. Our advanced machine learning (ML) models identify key
influencing factors for a flight to forecast future events in real-time, providing
unprecedented insight to improve operational efficiencies and facilitate better
decision-making in the air and on the ground. To learn more about the power of Foresight,
visit https://www.flightaware.com/commercial/foresight/
These endpoints each mirror a non-Foresight equivalent endpoint of similar functionality,
with the addition of all the ML 'predicted' values included in the Foresight response. The
respective non-Foresight endpoint response includes a flag, 'foresight_predictions_available',
which can optionally be used as a trigger to obtain and leverage Foresight predictions on an
as-needed basis and manage cost. Foresight is only available to Premium tier customers.
Contact [email protected] for more information, pricing details, and to have
your account enabled for Foresight.
- name: airports
- name: operators
- name: alerts
description: |
AeroAPI alerting can be used to configure and receive real-time alerts on key flight
events. With customizable alerting offered by our alert endpoints, AeroAPI empowers
users to selectively pick various types of events/filters to alert on. By doing so,
you can receive specially tailored alerts delivered to you for events such as flight plan
filed, flight departure (out and off), flight arrival (on and in), and more!
To get started with alerting, the **PUT /alerts/endpoint** endpoint must first be used
to set up the account-wide default URL that alerts will be delivered to. This step must
be done before any alerts can be configured and will serve as the fallback URL that all
alerts will be sent to for the account if a specific delivery URL is not designated on a
particular alert. If this is not performed before configuring alerts, then you will
receive a 400 error with an error message reminding you of this step when trying to interact
with the **POST /alerts** endpoint. Once a URL is set via the **PUT /alerts/endpoint** endpoint,
then alerts can be configured using the **POST /alerts** endpoint. The **GET /alerts** endpoint
can also be used to retrieve all currently configured alerts associated with your AeroAPI key.
The **GET /alerts** endpoint will allow you to easily retrieve the id of any specific alerts of
interest configured for the account which can let you use the **GET** **PUT** and **DELETE**
**/alerts/{id}** endpoints to retrieve, update, and delete specific alerts.
When configuring an individual alert, the *target_url* field can be set to a URL that’s
different than the account-wide target endpoint set via the **PUT /alerts/endpoint**. If
the *target_url* field is set on an alert, then that specific alert will be delivered to
the specified *target_url* rather than the default account-wide one. If this field is not
configured for the alert, then the alert will be delivered to the default account-wide endpoint.
By setting this field, one can easily target different alerts to be received by different endpoints
which can be useful for configuring per-application alerts or sending alerts to an alternate
development environment without having to adjust a production alert configuration.
For each alert configured, one-to-many ‘events’ can be set for alert delivery. While most
events will result in one alert delivery, both the *arrival* and the *departure* events can
result in multiple alerts delivered (referred to as bundled). The *departure* event bundles the
departure (actual OFF the ground) alert, along with the flight plan filed alert and up to 5
per-departure changes which can include alerts for significant departure delays of over
30 minutes, gate changes, and airport delays. FlightAware Global customers will
also receive *Power on* and *Ready to taxi* alerts as part of the departure bundle. The *arrival* event
bundles the arrival (actual ON the ground) alert, along with up to 5 en-route changes (including delays
of over 30 minutes and excluding diversions) identified. FlightAware Global customers will also receive
*taxi stop* times as part of the *arrival* bundle. Setting a bundled type and unbundled type for an
On/Off will only result in a single alert in the case where events may overlap.
If there is a need to change the alert configurations, updating an alert using the **PUT /alerts/{id}**
endpoint and a unique alert identifier (id) is preferred rather than creating an additional alert.
By doing so, you can avoid duplicate alerts being delivered which could create unnecessary noise
if they are not of interest anymore.
If at any point there is a need to delete an alert, the **DELETE alerts/{id}** endpoint can be
leveraged to delete an alert so that it won’t be delivered anymore. As a reminder, specific alert
IDs can be retrieved from the **GET /alerts** endpoint.
- name: history
- name: miscellaneous
servers:
- url: 'https://{env}.flightaware.com/aeroapi'
variables:
env:
default: aeroapi
enum:
- aeroapi
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-apikey
description: |
Unlike previous versions of AeroAPI, authentication is now controlled by
an API key that must be set in the header ```x-apikey```. Your
FlightAware username is not used when authenticating to the API.
security:
- ApiKeyAuth: []
paths:
/flights/search:
get:
operationId: get_flights_by_search
summary: Search for Flights
description: |
Search for airborne flights by matching against various parameters including
geospatial data. Uses a simplified query syntax compared to
/flights/search/advanced.
tags:
- flights
parameters:
- name: query
in: query
description: |
Query to search for flights with a simplified syntax (compared to
/flights/search/advanced). It should not exceed 1000 bytes in length.
Query syntax allows filtering by latitude/longitude box, aircraft ident
with wildcards, type with wildcards, prefix, origin airport,
destination airport, origin or destination airport, groundspeed, and
altitude. It takes search terms in a single string comprising "-key
value" pairs. Codeshares and alternate idents are NOT searched when
using the -idents clause.
Keys include:
* `-prefix STRING`
* `-type STRING`
* `-idents STRING`
* `-identOrReg STRING`
* `-airline STRING`
* `-destination STRING`
* `-origin STRING`
* `-originOrDestination STRING`
* `-aboveAltitude INTEGER`
* `-belowAltitude INTEGER`
* `-aboveGroundspeed INTEGER`
* `-belowGroundspeed INTEGER`
* `-latlong "MINLAT MINLON MAXLAT MAXLON"`
* `-filter {ga|airline}`
schema:
type: string
example: |
-latlong "44.953469 -111.045360 40.962321 -104.046577"
- 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: InFlightStatus
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)
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.
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
waypoints:
type: array
items:
type: number
description: |
Route waypoints as an array of alternating latitudes and longitudes.
first_position_time:
type: string
nullable: true
format: date-time
description: Timestamp of when the first position for this flight was received.
example: '2021-12-31T19:59:59Z'
last_position:
type: object
description: Most recent position received for this flight.
title: FlightPosition
nullable: true
properties:
fa_flight_id:
type: string
nullable: true
description: |
Unique identifier assigned by FlightAware to the flight with this
position. This field is only populated by the `/flights/search/positions`
(in other cases, the user will have already specified the fa_flight_id).
altitude:
type: integer
description: Aircraft altitude in hundreds of feet
altitude_change:
type: string
nullable: false
description: |
C when the aircraft is climbing, D when descending, and - when the
altitude is being maintained.
enum:
- C
- D
- '-'
groundspeed:
type: integer
description: Most recent groundspeed (knots)
heading:
type: integer
nullable: true
description: Aircraft heading in degrees (0-360)
minimum: 0
maximum: 360
latitude:
type: number
description: Most recent latitude position
longitude:
type: number
description: Most recent longitude position
timestamp:
type: string
format: date-time
description: Time that position was received
example: '2021-12-31T19:59:59Z'
update_type:
type: string
nullable: true
description: |
P=projected, O=oceanic, Z=radar, A=ADS-B, M=multilateration,
D=datalink, X=surface and near surface (ADS-B and ASDE-X),
S=space-based
enum:
- P
- O
- Z
- A
- M
- D
- X
- S
- null
required:
- fa_flight_id
- altitude
- altitude_change
- groundspeed
- heading
- latitude
- longitude
- timestamp
- update_type
bounding_box:
type: array
nullable: true
description: |
List of 4 coordinates representing the edges of a box that entirely
contains this flight's positions. The order of the coordinates are the
top, left, bottom, and right sides of the box.
maxItems: 4
minItems: 4
items:
type: number
ident_prefix:
type: string
nullable: true
description: |
A one or two character identifier prefix code (Common values: G or GG
Medevac, L Lifeguard, A Air Taxi, H Heavy, M Medium).
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.
actual_off:
type: string
format: date-time
nullable: true
description: |
Actual runway departure 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'
required:
- ident
- fa_flight_id
- actual_off
- actual_on
- origin
- destination
- waypoints
- first_position_time
- last_position
- bounding_box
- ident_prefix
- aircraft_type
- 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
- title: ForesightLegacyDummy
type: object
properties:
predicted_out:
type: string
format: date-time
nullable: true
description: Predicted time of gate departure event. Only available from /foresight endpoints.
example: null
predicted_off:
type: string
format: date-time
nullable: true
description: Predicted time of runway departure event. Only available from /foresight endpoints.
example: null
predicted_on:
type: string
format: date-time
nullable: true
description: Predicted time of runway arrival event. Only available from /foresight endpoints.
example: null
predicted_in:
type: string
format: date-time
nullable: true
description: Predicted time of gate arrival event. Only available from /foresight endpoints.
example: null
predicted_out_source:
type: string
nullable: true
description: Source indicator of the predicted time of the gate departure event. Only available from /foresight endpoints.
enum:
- null
- Foresight
- Historical Average
predicted_off_source:
type: string
nullable: true
description: Source indicator of the predicted time of the runway departure event. Only available from /foresight endpoints.
enum:
- null
- Foresight
- Historical Average
predicted_on_source:
type: string
nullable: true
description: Source indicator of the predicted time of the runway arrival event. Only available from /foresight endpoints.
enum:
- null
- Foresight
- Historical Average
predicted_in_source:
type: string
nullable: true
description: Source indicator of the predicted time of the gate arrival event. Only available from /foresight endpoints.
enum:
- null
- Foresight
- Historical Average
required:
- predicted_out
- predicted_off
- predicted_on
- predicted_in
- predicted_out_source
- predicted_off_source
- predicted_on_source
- predicted_in_source
required:
- links
- num_pages
- flights
'400':
description: |
Incorrect parameter(s). Query may be empty.
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
/flights/search/positions:
get:
operationId: get_flights_by_position_search
summary: Search for Flight Positions
description: |
Returns flight positions based on geospatial search parameters. This
allows you to locate flights that have ever flown within a specific a
latitude/longitude box, groundspeed, and altitude. It takes search
terms in a single string comprising of {operator key value} elements
and returns an array of flight structures. Each search term must be
enclosed in curly braces. Multiple search terms can be combined in an
implicit boolean "and" by separating the terms with at least one space.
This function only searches flight data representing approximately the
last 24 hours.
The supported operators include (note that operators take different numbers of arguments):
* false - results must have the specified boolean key set to a value of false. Example: {false preferred}
* true - results must have the specified boolean key set to a value of true. Example: {true preferred}
* null - results must have the specified key set to a null value. Example: {null waypoints}
* notnull - results must have the specified key not set to a null value. Example: {notnull aircraftType}
* = - results must have a key that exactly matches the specified value. Example: {= fp C172}
# --- truncated at 32 KB (870 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rockwell-collins/refs/heads/main/openapi/flightaware-aeroapi-openapi.yml