General
Security
Understanding AeroAPI Results
Billing
General
FlightAware released AeroAPI Version 4 (v4) as the next generation of our AeroAPI product in October 2021. AeroAPI v4 replaced legacy AeroAPI version 2 and 3 (v2/v3) offerings (previously known as FlightXML). Both v2 and v3 were sunset October 2023.
Using the GET /history/*
resources will provide you with on-demand access to flight status and flight tracking data from January 1, 2011 onward.
Historical data can be requested for any given flight ident or registration number, as well as all flights arriving or departing from an airport. All historical access options can be found here in the documentation.
For all other endpoints, generally 48-72 hours of data is returned by default, with the additional flexibility to obtain up to 10 days of flight history using the start and end query parameters (see the documentation of each function for specifics). Further history can be purchased on a per-identification basis on the flightaware.com website. For other data needs, contact FlightAware commercial services.
Absolutely, please bring it up in the AeroAPI Developers Discussion Forum.
Security
Yes. Your AeroAPI key should be treated like a password and kept secret. If someone else knows your API key, they will be able to make AeroAPI queries that you will be charged for. The most common source of a compromised key is when it is committed into public source control repositories, like GitHub.
Yes, you can always delete an API key and create new keys. There are no fees for additional API keys.
Simply log into your account, go to 'My AeroAPI -> API Keys'. Your keys will be listed along with current status. Delete any key using the Delete button on the far right. If you only have one key, you must first 'Add API Key' before you can delete the existing key.
If you are not able to log in and delete your key, contact FlightAware support for assistance.
Yes, in fact we encourage you to have multiple keys if you would like to track usage by environment or use case.
You might have one key for development and one for production, or perhaps separate API keys for different applications. You can add keys at any time simply by logging into your account, going to 'My AeroAPI' in the top banner, then to 'API Keys'. Click 'Add API Key'. Active accounts must have at least one active key at all times. There are no additional fees for additional keys.
Understanding AeroAPI Results
Generally, the preferred method is to use the GET /flights/{ident}
resource with the ident of the flight you are interested in. Look through the returned results for the flight occurring on the date and with an origin of the airport you are expecting. Here are some general rules for interpreting the fields in a flight's structure.
- If (actual_off == null), then the flight has not departed yet.
- If (actual_off != null && actual_on == null), then the flight is currently en route.
- If (actual_off != null && actual_on != null && actual_off != actual_on), then the flight has arrived.
- If (actual_off != null && actual_on != null && actual_off == actual_on), then the flight result is unknown and has probably arrived but we don't have an arrival confirmation.
Another common thing that you might want to compute based on multiple fields:
- Actual elapsed time en route = (actual_on - actual_off).
Your application will have to be robust and support null (or zero) values in virtually every field. For example, actual_on will be null if the aircraft has not arrived.
The diverted field is a boolean; it can be true or false. If it is true, the actual_on field will indicate the diverted time. To determine the diversion airport and arrival time (if aircraft has arrived), your application will have to find the flight for that aircraft with the same origin and departure time.
This is an indication that the result of the flight is unknown, but we suspect that the flight has already ended.
The "fa_flight_id" field in AeroAPI is a unique identifier that is generated by FlightAware for referencing a specific instance of a flight. All AeroAPI responses that contain the same "fa_flight_id" value can be assumed to be in reference to the same flight. The meaning of the components within the flight id are not documented as having any public meaning and are purely an artifact of how we generate the ids to be unique. External customers should consider the flight id to be entirely opaque. The FlightAware flight id is meant to be a unique identifier for a particular flight, which comprises of one takeoff and one full-stop landing.
If your application has received details about a flight through AeroAPI you can allow your users to view the FlightAware flight tracking page for that specific flight by taking the "fa_flight_id" field and forming a URL like this: "https://flightaware.com/live/flight/id/" + fa_flight_id.
Resolution varies depending on the exact source of each position. In some cases, the resolution could be as large as one minute or approximately 0.88 miles. However, most positions are derived from ADS-B and tend to be very accurate when the position source on the aircraft is GNSS (GPS).
This is the result of a "position-only" flight for which FlightAware has not received a filed flight plan schedule, or intent information; for example a VFR flight. FlightAware will use the position reports via ADS-B to determine the origin or destination airport. However, in some cases there is not enough data to accurately determine an airport. In these cases the the first or last position may be reported in the style of "L 33.60006 -111.87098
" instead of an airport code. For position-only flights that are still active the destination will be null.
Of the three airport codes (ICAO, IATA, and LID), only the ICAO codes are unique. Thus, to ensure that the results you receive from the endpoint is for the airport you want, please use the ICAO code whenever possible. In the event that the ICAO code is unknown and an IATA or LID code is provided, we will attempt to translate it to the corresponding ICAO code for you using a static translation. In the case where the provided IATA or LID code conflicts and is ambiguous, we will fall back to US/Canada airports.
When a successful (HTTP 200 or 400 series responses, except 429) request is made, the results are returned in chunks called 'result sets', also sometimes referred to as a 'page'. A result set can contain up to 15 records.
By default, all API resources will respond with one result set and consume one result set of rate limit quota. If an API resource contains a max_pages
query-string parameter, it can be optionally supplied to increase the amount of result sets returned. These resources will also contain a num_pages
field in the response that indicates the actual number of result sets delivered. The max_pages
will be checked against the current remaining rate limit quota, while num_pages
is what is deducted from the rate limit quota.
If an API resource does not contain a max_pages
query-string parameter it will always respond with a single result set.
Result set counts are used to compute total cost, as pricing is based on volume of data returned which is measured in 'result sets'.
Some API resources can return many records broken up into many result sets. By default, responses will only contain one result set. If there are additional result, there will be an object in the links
field that contains a uri-reference
with a cursor. This opaque value can be provided to the API to request the next result set(s) of data without having to re-request the same data by only increasing the max_pages value. If this field is null there are no more result sets available for the specific request.
A cursor will persist for 5 minutes after it is delivered in a response.
Billing
You can see recent activity and statements on the AeroAPI billing page.
You can also request your current usage stats at any time using the account management resource, GET /account/usage. By specifying the date range of interest you can see total calls, total costs, discounted costs (volume discounting is applied), number of successful and failed requests, and counts by resource for any period of time. These stats are updated approximately every 10-20 minutes (not quite real-time). Usage can be requested for a single key or all API keys for the account. It is suggested to use this endpoint to both monitor usage and help manage total costs. There is no fee for using GET /account/usage .
Your credit card will be charged once a month at the beginning of the month in arrears for the prior month based on actual usage (subject to any monthly minimum that may apply based on plan tier).
You can update your billing data on the billing profile management page.
AeroAPI pricing is based on volume of data returned. The results of your requests(queries) are returned as 'result set(s)', also referred to as 'pages'. A resultset can contain up to 15 records, which are usually flight records.
For requests in which a single flight (record) is returned the total cost will simply be the per resultset price, as posted on product pricing page here. For requests that return a list of objects, the total cost can be calculated by dividing the number of objects (records) by 15 to determine the total resultset count, and then multiply the resultset count by the per resultset price.
Example:
GET /airports/KMSP/flights returns 150 flights. 150/15 = 10 result sets. 10 *.02 = $.20.
You will be charged for each alert that is delivered to you (Push Alert Delivery). The number of alerts that you will receive is based on which alert ‘events’ you have configured. The departure and arrival events may each result in 1 or more alerts delivered (actual departure/arrival, plus potentially 1-2 additional alerts relaying departure/arrival change info when known). All endpoints used to configure and manage your flight alerts and the alert callback URL will not incur any fees.
Troubleshooting
The AeroAPI servers do not support Cross-Origin Resource Sharing (CORS) requests. We do not recommend using AeroAPI through Javascript in the browser due to the potential exposure of your AeroAPI credentials. A backend application server should be used to make the AeroAPI requests instead.
If you have a firewall that needs authorization, then please authorize the following IP addresses:
- 35.192.194.208
- 35.192.194.209
- 35.192.156.45
One method would be to include a unique token parameter when setting your alert endpoint via the /alerts/endpoint
resource. Then the endpoint would be expected to verify the value.
https://myserver.example.com/path/handler.cgi?secretkey=abc123
It is also possible to use basic authentication on the endpoint by submitting a username and password in the legacy URL encoding method. However this method is not recommended and will only function with endpoints configured for HTTPS. https://user:password@myserver.example.com/path/handler.cgi