FlightXML 2.0 Documentation

About

Using the FlightXML API, programs can query the FlightAware live flight
information and recent history datasets.

Queries for in-flight aircraft return a set
of matching aircraft based on a combination of location, flight or tail number,
origin and/or destination airport, aircraft type, and/or a low-to-high range of
altitude and/or ground speed, among others. For each matching aircraft, data
returned includes the flight or tail number, the aircraft type, origin and
destination, time the last position was received, and the longitude, latitude,
groundspeed, and altitude of that position. Matching flights' flight tracks can
be requested as well.

For airports, FlightXML queries can return a list of scheduled flights,
flights that have departed, flights that are enroute to the airport, and flights
that have arrived at the airport.

Create a customized alerting system based on the current status of your fleet.

Streamline flight planning by showing common routes as cleared by air traffic control between two airports.

Add real flight data to your simulations.

Show flight tracks in Google Earth.

Create visualizations of traffic patterns.

Add live flight information to your company's website.

Authentication

To access FlightXML 2.0, all requests must include a username and FlightXML Key (don't have one?).
This data is transmitted via the "basic" HTTP Authentication standard, which is sent to the FlightXML server as a part of each HTTP request.

The web service libraries available in most programming languages allow you to directly specify a username and password as an argument for the request, so that the authentication is transparent to your application as it makes requests. However, with some libraries it may be necessary to manually encode the "user:key" in base64 and send the result in the "Authorization" header as part of each HTTP request.

If data security is a concern, all FlightXML services are also available over SSL by simply substituting "https" as the protocol for any flightxml.flightaware.com URLs.

Web Services / SOAP / WSDL

The primary protocol recommended for use with FlightXML 2.0 is the "Simple Object Access Protocol" (SOAP). Most modern SOAP implementations support use of "Web Services Description Language" (WSDL) definition file, which greatly simplifies accessing web services.

Although you can read the WSDL and generate SOAP queries manually, it is recommended that you develop your
applications using a SOAP library that automatically parses the WSDL and populates your application namespace
with the FlightXML functions.

It is strongly suggested that you ensure that your applications cache the WSDL
file so that it is not necessary to fetch and parse the WSDL for every request or instance of your
application. This will vastly improve the performance and efficiency of your application.

The FlightXML 2.0 WSDL uses the "Document/Literal wrapped" method for encoding SOAP requests and responses.
This is a newer method that recent SOAP industry standards dictate should be used instead of the older
"RPC/Encoded" method that was used by the FlightXML 1.0 WSDL. Most modern SOAP client libraries fully
support this newer method, although some older SOAP libraries are not yet compatible. The SOAP client
libraries listed in the examples section have been tested to be compatible.

REST / JSON

FlightXML 2.0 can also be accessed using a light-weight "Representational state transfer" (REST) inspired protocol that returns its responses encoded in "JavaScript Object Notation" (JSON) format. This allows FlightXML to be used in environments in which it is inconvenient or impossible to invoke SOAP services, such as mobile phone applications, web browser applications, or server-side JavaScript environments.

To access any method, simply perform either a GET or POST request to http://flightxml.flightaware.com/json/FlightXML2/METHODNAME using standard CGI-style representation of the arguments. All requests made must supply the username and API Key as a "basic" Authorization HTTP header.

For example, the following URL is how you might request the current weather at John F. Kennedy airport (KJFK) in New York: http://flightxml.flightaware.com/json/FlightXML2/MetarEx?airport=KJFK&startTime=0&howMany=1&offset=0

Requests can be returned in "JSONP" format, allowing a web page to load the response in a way that avoids the same-domain security restrictions enforced by some browsers. To do this, simply specify the optional argument "jsonp_callback" with a value that is the name of the JavaScript function that should be invoked with the JSON data.

Pushed Notifications

Although FlightXML functionality is primarily intended to be accessed through a "pull" oriented request model using the SOAP/WSDL or REST/JSON interfaces, you can also opt to receive a "pushed" notification from our server to yours whenever certain flight events occur. Upon receiving a notification, your server-based application is sent basic information about the flight, its current status, and the triggering event. In response, your server-based application can initiate requests to FlightXML using the normal SOAP/WSDL or REST/JSON interfaces to obtain additional details. This can allow your application to intelligently reduce or increase the rate at which it makes other FlightXML requests at various parts of a flight, reducing your costs by avoiding unnecessary API requests during uneventful time periods.

To use pushed notifications, you must first call the "RegisterAlertEndpoint" method once to configure the URL endpoint where your server-based application can receive POST requests via HTTP or HTTPS. Once the URL endpoint has been registered, you can use the "SetAlert" method to define the triggering event conditions for the notifications that you want to receive.

When an event occurs, your URL endpoint will receive a POST request containing a JSON message. Although you can define alerts using either the SOAP/WSDL or REST/JSON interfaces, pushed notifications are always delivered in a JSON format. Delivery of each alert is attempted only once and is made on a best-effort policy. Your URL endpoint must accept the POST request and return a successful response within 5 seconds. It is recommended that your URL endpoint return a "Content-type" of "text/plain", and a short body (less than 32 characters) that acknowledges receipt of the pushed alert. If troubleshooting of alert delivery is required, the body responses for each delivered alert can be later reviewed on the Recently delivered alerts page.

long_desc -- human-readable description of the event (sometimes longer than 80 characters). Not intended to be machine parsed, since this text is localized and the formatting is occasionally altered. (required)

short_desc -- human-readable description of the event (generally about 50 characters long). Not intended to be machine parsed, since this text is localized and the formatting is occasionally altered. (required)

summary -- human-readable summary of the event (generally about 20 characters long). Not intended to be machine parsed, since this text is localized and the formatting is occasionally altered. (required)

eventcode -- Indicates the type of event that has triggered this notification. May have one of the following values: (required)

filed -- details about an upcoming flight have been received (generally 1-2 hours before departure)

departure -- flight has departed from the origin (runway wheels-up or gate block-off)

minutes_out -- flight is several minutes (usually 30-45 minutes) from its destination.

diverted -- flight has been diverted to another airport. To retrieve the new flight details, call FlightInfoEx to access the new flight by faFlightID or ident.

change -- some aspect of the flight plan has been modified, such as a departure time delay or a gate change.

alert_id -- Integer identifier of the alert that triggered the event. This is the value returned by SetAlert, and can be used with DeleteAlert to stop receiving notifications. (required)

flight -- Nested array with more details about the flight. Due to technical data limitations, some of these nested values (such as the actualarrivaltime and actualdeparturetime) may not yet be available for the latest event that is being alerted, but a subsequent call to FlightInfoEx might. Description of the nested values:

ident -- Operating identifier or registration for the aircraft (required)

aircrafttype -- Type of aircraft, if known (optional)

origin -- Origin airport, if known (optional)

destination -- Destination airport, if known (optional)

filed_ete -- Scheduled flight duration, if known (optional)

route -- Filed route waypoints, if known (optional)

faFlightID -- Unique FlightAware identifier for the flight, which can be used for FlightInfoEx or other methods (required)

filed_altitude -- Altitude of the flight plan, if known (optional)

filed_airspeed_kts -- Airspeed of the flight plan, in knots if known (optional)

filed_time -- Timestamp of when the flight plan was initially filed, in UNIX epoch seconds since 1970. (required)

Examples (SOAP / WSDL)

Microsoft .NET

Any Microsoft CLR .NET language should be usable to make requests to FlightXML 2.0, however this example is using C#. The procedure for using other languages may vary slightly. The steps described here use the command-line utilities to generate the WSDL stub and compile, but the steps can be adapted for use within the Visual Studio IDE.

Requirements

Microsoft Visual Studio 2003 or newer

Save the following file as test.cs, but substitute your actual username and API key:

The Perl CPAN module SOAP::Lite is an old and well-known SOAP client for Perl, however it is not especially well-suited for modern "Document/Literal" SOAP services. However, it can be used if you are willing to make calls to explicitly declare the types of all function arguments using the SOAP::Data method. The "stubmaker.pl" utility and the SOAP::Lite WSDL support cannot be used.

Requirements

Perl5 or above

SOAP::Lite (tested with 0.710.10)

On RHEL/Fedora based systems: yum install perl-SOAP-Lite

On FreeBSD systems: cd /usr/ports/net/p5-SOAP-Lite && make install

Otherwise: perl -MCPAN -e 'install SOAP::Lite'

Save the following file as testlite.pl, but substitute your actual username and API key:

Wait for the WSDL parsing. You should see all the names of all the generated java classes in the output window. The process should finish with "BUILD SUCCESSFUL"

Inspect your resources

The URL of the WSDL that you used to create the client is mapped to the local copy of the WSDL which you can see under the main node, in jax-ws-catalog.xml

Within the Generated Sources node , you should see the client stubs that were generated by the JAX-WS Web Service Client wizard. By inspecting the stub names you should see that the stubs are generally grouped as "request", "result" and possibly "struct"

Import the stubs you want

In your Java Class import the stubs you want from the Generated Sources. For example, to import all of them you would use a command similar to:import com.flightaware.flightxml.soap.flightxml2.*;
Make sure that the package name matches yours! Sometimes it may be com.flightaware.flightxml.soap.FlightXML2.*

Observations

FlightXML2Soap.java stub will provide all the starting point methods. After selecting FlightXML2Soap.java from the Generated Sources you should see all the methods in the NetBeans Navigator window under Members.

All the methods take a request object and return a result object, both of which can be found in the Generated Resources as well.
Therefore, you need to create a request, pass it to the FlightXML2Soap.java method you need and finally get all the information from the result object. Again, the Navigator window will show all methods available for each class and you can use these methods to get to a easily printable value that you want such as a String or an int.

Additional documentation on developing a JAX-WS Web Service Client in NetBeans can be found on netbeans.com:

Examples (REST / JSON)

JavaScript

This example is a static HTML page using JavaScript and jQuery to access FlightXML2 over its JSON interface.
We recommend that this technique be only used in protected Intranet environment, since embedding your
FlightXML API key in public web pages will allow other users to copy your key and make unauthorized use against your account.

(2011-02) Changed GetHistoricalTrack, DecodeFlightRoute, MapFlightEx, and AirlineFlightInfo to allow "ident@departureTime" syntax to optionally be used instead of a faFlightID, saving the need to explicitly use GetFlightID first.

(2012-03) Added support for Australian airspace. To receive these flights, you must use the API key request page to obtain a new key and agree to the distribution terms. Otherwise such flights may appear in your results with an ident of "BLKFA" and its other fields will be blank/zero.

(2012-04) Enhanced FlightInfoEx to allow a faFlightID to be requested.

(2012-04) Changed FlightInfo and FlightInfoEx to now return results sorted by filed_departuretime instead of file_time.

(2012-04) Changed RoutesBetweenAirportsEx to now allow maxDepartureAge and maxFileAge to be specified as blank to search the maximum routes available.

(2012-09) Added AirlineFlightSchedules again

(2013-03) FlightInfo and FlightInfoEx can now return results for tail/registration numbers for flights operating under a different callsign. FlightInfoEx also now supports "ident@departureTime" syntax, avoiding the need to call GetFlightID first