Tuesday, November 18, 2014

FlightStats releases Positions v2

FlightStats is pleased to announce an upgrade to our Flight Track API.  On December 10, 2014, FlightStats will release Positions v2 which provides a richer set of positional data to be used within flight tracker applications.  This upgraded API will include several new fields as well as derived positions when observed positions are not available.  

Additional Fields:
  • course: The direction of travel in degrees relative to geographic north, clockwise. The range for this data field is -179 to 180.
  • vrateMps: The velocity of ascent or descent (if negative) in meters per second.
  • phase: Description used to indicate the most likely activity of the plane at a given time. Phases include: Ground, Take-Off, Departure, Climb, Leveled, Cruise, Descend, Approach, Landing. Not all positions will include a phase.
  • lastObserved: The timestamp of when FlightStats last received an observed position. In cases where no observed positions are provided for a flight, this field will not be present. The 'date' field in each of the positions blocks identifies the time when the plane is believed to be at that specific location -- either observed or calculated. FlightStats continues to calculate the position even when no additional observed data is provided. In such cases, there will be a difference between date and lastObserved, a gap that increases as the flight continues.
  • stationID: The station identifier used by the FAA for ASDI data. Examples: KZLA, KZAB, KZDV.

Special Note regarding stationID:
The ASDI stream consists of a collection of observations from different regional and national tracking systems. Each of these has a separate stationId. A single aircraft may be observed by multiple stations at once, each of which may report a slightly different position due to the inherent inaccuracy of radar. Because of this, trackers showing ASDI streams should either show all signals separately, maintain an affinity between a callsign and single stationId as long as possible, or integrate the different signals.
(Note: ADS-B data payloads will be unchanged in the new system. ASDI data payloads will include one additional field - stationID.)

Request Parameters:
Applications will not need to make any changes to their current request in order to receive derived positions -- derived will be the sourceType by default. If you want to continue receiving positional data as it currently is provided, you will need to add a single argument.  (sourceType=raw)

If you would like to take advantage of the new fields, your application will need to include that value in the 'extendedOptions' n/v pair, as shown below. 

Here is an example request that will return positional data as it is currently in production, without the new fields. 

?appId<appid>
&appKey=<appkey>
&sourceType=raw
&includeFlightPlan=true


This example will return the new derived data.  sourceType is not needed, because it defaults to sourceType=derived.  In this case, new fields will be included. 

?appId<appid>
&appKey=<appkey>
&extendedOptions=includeNewFields
&includeFlightPlan=true

This example will return the new derived data and include new fields (extendedOptions=includeNewFields)

?appId=[appID]
&appKey[appKey]
&includeFlightPlan=false
&maxPositions=25
&sourceType=derived
&extendedOptions=includeNewFields

Please see the Developer Center for additional documentation.

(Note:  From now until release date, you will need to include the n/v pair "sourceType=derived" in order to test and review the new data payload.)