Documentation Formats

This JSON file reports on the state of all of the aircraft tracked by a receiver or merged feed.

Request

The address of the JSON file is http://<site-address>/VirtualRadar/AircraftList.json. The request uses query string parameters and a custom header to pass information about the state of the site to the browser.

Virtual Radar Server will respond to both GET and POST requests for AircraftList.json but there is a caveat, see Known Aircraft for details.

Query string parameters

The names of query string parameters are case-insensitive. They are used to modify the output from AircraftList.json:

Name	Value
ldv	The lastDv value from the last aircraft list fetched. Omit this if this is the first time you are fetching an aircraft list. The server will use this value and the X-VirtualRadarServer-AircraftIds header to figure out what has changed since the last time you fetched a list and will only send the changed information. If you do not supply these values then you are always sent a full aircraft list.
lat	The decimal latitude to measure distances and calculate bearings from. Omit if no distance or bearing calculations are to be made.
lng	The decimal longitude to measure distances and calculate bearings from. Omit if no distance or bearing calculations are to be made.
selAc	The ID of the selected aircraft, if any. Omit if no aircraft is selected.
trFmt	The format of trails that you want to be passed. Omit if you do not want trail history to be sent for each aircraft that is transmitting a position. The legal values for this parameter are f for a full trail, fa for a full trail with altitudes, fs for a full trail with speeds, s for a short trail, sa for a short trail with altitudes and ss for a short trail with speeds. Short trails only show the last 30 seconds of positions. The duration of a short trail can be changed in the server settings.
refreshTrails	Set to 1 to force the server to send the entire trail for each aircraft. If this is missing or 0 then the server will try to only send new positions for the trail.
feed	The ID of the feed whose aircraft list you want to see. If missing or invalid then the default feed is used - this is configured on the server.

Filters can be passed as query string parameters to constrain the results to just those aircraft that match some condition. Multiple filters can be passed but only one of each kind of filter can be passed - for example, if you pass two callsign filters then only one of them will be honoured.

Prefix	Filter Type	Value
fAir	String	The to / from / via airport code
fAlt	Integer range	Altitude in feet
fCall	String	Callsign
fCou	String	Country
fDst	Number range	Distance in kilometres
fEgt	Enum	Engine type
fNoPos	Boolean	No position transmitted
fIco	String	ICAO
fMil	Boolean	Is military
fTyp	String	Model ICAO code
fOp	String	Operator name
fOpIcao	String	Operator ICAO code
fReg	String	Registration
fSpc	Enum	Aircraft species
fSqk	Intger range	Squawk
fInt	Boolean	Is flagged as interesting in database
fWtc	Enum	Wake turbulence category
fUt	String	User tag
fNBnd	Bounds	The top-most latitude of the bounds. Only returns aircraft within these bounds.
fSBnd	Bounds	The bottom-most latitude of the bounds. Only returns aircraft within these bounds.
fWBnd	Bounds	The left-most longitude of the bounds. Only returns aircraft within these bounds.
fEBnd	Bounds	The right-most longitude of the bounds. Only returns aircraft within these bounds.

All filters (except the Bounds filters) are passed with a name that consists of a prefix and then a single-character code that describes the condition. If the condition is negated / reversed (e.g. NOT equal to) then a suffix of N is also appended. The full list of conditions is as-per below:

Condition	Suffix Character	Filter Types That Can Use It
Between - lower	L	Number range
Between - upper	U	Number range
Contains	C	String
Ends with	E	String
Equals	Q	String, Boolean, Enum
Starts with	S	String

When a range has both an upper and a lower bound then two query string parameters need to be passed, one for the upper and one for the lower. If one part of the range is negated (i.e. it has an N suffix) then the other part must also be negated.

The order in which filter parameters are passed has no effect, an aircraft must match all of the filters in order for it to pass. In effect the filters are ANDed together. If the aircraft does not have a value for a particular filter type (e.g. you filter against a callsign and the aircraft has no callsign) then it will only match against filters that have no value (e.g. fCallQ=) or filters that are negated (e.g. fCallQN=BAW1).

The Enum filter values are the enum to match (or not match) against. The enums are strings described in the JavaScript file enums.js. Boolean filters should pass 0 for false, 1 for true or nothing for undefined.

The four parameters that make up the Bounds filter do not accept a condition. If you supply one of the bounds then you must supply all of them and the effect will be to only return aircraft that have a position within those bounds. If you supply the selected aircraft ID in selAc then the selected aircraft will always returned in an aircraft list that has been constrained to a Bounds, even if the selected aircraft isn't within the bounds that you supply.

All of the filters are case insensitive.

So for example, if you wanted to constrain the list to only aircraft whose model ICAO type code starts with "A38" then you would pass a filter parameter of fTypeS=A38. If you want to filter just to those aircraft whose model ICAO type code does not start with "A38" then you would pass fTypSN=A38. If you wanted to filter to just those aircraft that do not have a model ICAO type code then you would pass fTypQ=, and similarly if you only wanted aircraft that have something, anything, for a model ICAO type code then it'd be fTypQN=.

Known Aircraft

When a browser first opens the map page it sends a request for an AircraftList.json that contains everything that the site knows about every aircraft being tracked.

For the second and subsequent requests the site tells the server which aircraft identifiers it now knows about. The server uses this information along with the ldv query string value to avoid resending information that has not changed. It uses these values to reduce the bandwidth for the second and subsequent requests.

The "known aircraft" list is a list of aircraft identifiers. There are two ways that you can send the list to the server: the old way and the new way.

The old way

The old way was to create a comma-separated list of aircraft identifiers (their numerical UniqueID identifiers, not the six character ICAO identifier) and send that in a header called X-VirtualRadarServer-AircraftIds.

If you are sending a GET request then this is the only way that you can tell the server about known aircraft.

The new way

The new way is to send a POST request rather than a GET and to send the known aircraft identifiers as a standard URL encoded form field in the body. The field is called icaos. The field value should be a hyphen separated list of six character ICAO hex codes for every known aircraft.

Virtual Radar Server has been using the new mechanism since version 2.2 but it continues to support both methods.

Response

The response is a JSON file. The first response will always contain everything that it knows about every aircraft that passes the filters (if any were supplied). Subsequent fetches will only return information that has changed, unless you fail to pass the correct ldv query parameter and Known Aircraft list.

Property	Type	Description
lastDv	Number	Identifies the version of the aircraft list. Pass this in the ldv query string parameter on the next fetch.
totalAc	Number	The total number of aircraft tracked by the list. This can be larger than the rows in acList if the list has been filtered.
src	Number	The source that the feed is working from. 0 = unknown, 1 = receiver, 2 = a fake receiver (only used in testing) and 3 = Flight Simulator X.
showSil	Boolean	True if the server has a silhouettes folder configured. No longer used.
showFlg	Boolean	True if the server has an operator flags folder configured. No longer used.
showPic	Boolean	True if the server has a pictures folder configured. No longer used.
flgW	Number	Pixel width of all flags. No longer used, now configured in JavaScript.
flgH	Number	Pixel height of all flags. No longer used, now configured in JavaScript.
shtTrlSec	Number	The number of seconds of positions that short trails contain.
stm	Number	The server time at UTC in JavaScript ticks.
acList	Array	The aircraft list. See below.
feeds	Array	A list of every feed configured on the server. The feed object is `{ id: integer, name: string }`.
srcFeed	Number	The ID of the feed that was used to generate the list.
configChanged	Boolean	True if the server configuration has been changed since the last fetch.

The acList is an array of objects where each object describes an aircraft being tracked by the server. If the request supplied filter parameters then only the aircraft that passed the filter are shown. Many of the properties of an aircraft are optional - if they are marked as such then they are not passed if they have not changed since the last time the aircraft list was fetched (see the ldv query string parameter and X-VirtualRadarServer-AircraftIds header.

Property	Type	Optional	Description
Id	Number	No	The unique identifier of the aircraft.
TSecs	Number	No	The number of seconds that the aircraft has been tracked for.
Rcvr	Number	No	The ID of the feed that last supplied information about the aircraft. Will be different to srcFeed if the source is a merged feed.
Icao	String	Yes	The ICAO of the aircraft.
Bad	Boolean	Yes	True if the ICAO is known to be invalid. This information comes from the local BaseStation.sqb database.
Reg	String	Yes	The registration.
Alt	Number	Yes	The altitude in feet at standard pressure.
GAlt	Number	Yes	The altitude adjusted for local air pressure, should be roughly the height above mean sea level.
InHg	Number	Yes	The air pressure in inches of mercury that was used to calculate the AMSL altitude from the standard pressure altitude.
AltT	Number	Yes	The type of altitude transmitted by the aircraft: 0 = standard pressure altitude, 1 = indicated altitude (above mean sea level). Default to standard pressure altitude until told otherwise.
TAlt	Number	Yes	The target altitude, in feet, set on the autopilot / FMS etc.
Call	String	Yes	The callsign.
CallSus	Boolean	Yes	True if the callsign may not be correct.
Lat	Float	Yes	The aircraft's latitude over the ground.
Long	Float	Yes	The aircraft's longitude over the ground.
PosTime	Number	Yes	The time (at UTC in JavaScript ticks) that the position was last reported by the aircraft.
Mlat	Boolean	Yes	True if the latitude and longitude appear to have been calculated by an MLAT server and were not transmitted by the aircraft.
PosStale	Boolean	Yes	True if the last position update is older than the display timeout value - usually only seen on MLAT aircraft in merged feeds.
IsTisb	Boolean	Yes	True if the last message received for the aircraft was from a TIS-B source.
Spd	Number	Yes	The ground speed in knots.
SpdTyp	Number	Yes	The type of speed that Spd represents. Only used with raw feeds. 0/missing = ground speed, 1 = ground speed reversing, 2 = indicated air speed, 3 = true air speed.
Vsi	Number	Yes	Vertical speed in feet per minute.
VsiT	Number	Yes	0 = vertical speed is barometric, 1 = vertical speed is geometric. Default to barometric until told otherwise.
Trak	Number	Yes	Aircraft's track angle across the ground clockwise from 0° north.
TrkH	Boolean	Yes	True if Trak is the aircraft's heading, false if it's the ground track. Default to ground track until told otherwise.
TTrk	Number	Yes	The track or heading currently set on the aircraft's autopilot or FMS.
Type	String	Yes	The aircraft model's ICAO type code.
Mdl	String	Yes	A description of the aircraft's model. Usually also includes the manufacturer's name.
Man	String	Yes	The manufacturer's name.
CNum	String	Yes	The aircraft's construction or serial number.
From	String	Yes	The code and name of the departure airport.
To	String	Yes	The code and name of the arrival airport.
Stops	String[]	Yes	An array of strings, each being a stopover on the route.
Op	String	Yes	The name of the aircraft's operator.
OpCode	String	Yes	The operator's ICAO code.
Sqk	Number	Yes	The squawk as a decimal number (e.g. a squawk of 7654 is passed as 7654, not 4012).
Help	Boolean	Yes	True if the aircraft is transmitting an emergency squawk.
Dst	Number	Yes	The distance to the aircraft in kilometres.
Brng	Number	Yes	The bearing from the browser to the aircraft clockwise from 0° north.
WTC	Enum	Yes	The wake turbulence category of the aircraft - see enums.js for values.
Engines	String	Yes	The number of engines the aircraft has. Usually '1', '2' etc. but can also be a string - see ICAO documentation.
EngType	Enum	Yes	The type of engine the aircraft uses - see enums.js for values.
EngMount	Enum	Yes	The placement of engines on the aircraft - see enums.js for values.
Species	Enum	Yes	The species of the aircraft (helicopter, jet etc.) - see enums.js for values.
Mil	Boolean	Yes	True if the aircraft appears to be operated by the military.
Cou	String	Yes	The country that the aircraft is registered to.
HasPic	Boolean	Yes	True if the aircraft has a picture associated with it.
PicX	Number	Yes	The width of the picture in pixels.
PicY	Number	Yes	The height of the picture in pixels.
FlightsCount	Number	Yes	The number of Flights records the aircraft has in the database.
CMsgs	Number	Yes	The count of messages received for the aircraft.
Gnd	Boolean	Yes	True if the aircraft is on the ground.
Tag	String	Yes	The user tag found for the aircraft in the BaseStation.sqb local database.
Interested	Boolean	Yes	True if the aircraft is flagged as interesting in the BaseStation.sqb local database.
TT	String	Yes	Trail type - empty for plain trails, 'a' for trails that include altitude, 's' for trails that include speed.
Trt	Number	Yes	Transponder type - 0=Unknown, 1=Mode-S, 2=ADS-B (unknown version), 3=ADS-B 0, 4=ADS-B 1, 5=ADS-B 2.
Year	String	Yes	The year that the aircraft was manufactured.
Sat	Boolean	Yes	True if the aircraft has been seen on a SatCom ACARS feed (e.g. a JAERO feed).
Cos	Array	Yes	Short trails - see note 1.
Cot	Array	Yes	Full trails - see note 2.
ResetTrail	Boolean	Yes	True if the entire trail has been sent and the JavaScript should discard any existing trail history it's built up for the aircraft.
HasSig	Boolean	Yes	True if the aircraft has a signal level associated with it.
Sig	Number	Yes	The signal level for the last message received from the aircraft, as reported by the receiver. Not all receivers pass signal levels. The value's units are receiver-dependent.

Note 1 - Short Trails (Cos)

Short trails are a list of values that represent the positions that the aircraft has been seen in over so-many seconds (by default 30 seconds).

The array is an array of numbers. The numbers are arranged in groups of either 3 or 4, depending on whether just positions are being sent or whether the altitude or speed is also being sent.

If just positions are being sent (TT is empty or missing) then the first value is latitude, the second value is longitude and the third is the server time that the position was seen at UTC in JavaScript ticks.

If altitude or speeds are also being sent (TT is either 'a' for altitude or 's' for speed) then the first value is latitude, the second longitude, the third is server time and the fourth is either altitude or speed.

The first group of values represents the earliest position in the trail while the last group represents the latest position in the trail. If ResetTrail is true then the array contains the entire trail over the last 30 seconds, otherwise it just holds the coordinates added to the trail since you last fetched the aircraft list.

To look at it another way, if Cos is an array of n numbers and TT is an empty string then the values represent:

[0]	Latitude of earliest coordinate
[1]	Longitude of earliest coordinate
[2]	Time of earliest coordinate
...
[n-3]	Latitude of latest coordinate
[n-2]	Longitude of latest coordinate
[n-1]	Time of latest coordinate

Note 2 - Full Trails (Cot)

Full trails are a list of values that represent the positions that the aircraft has been seen in since it was first picked up.

The array is an array of numbers. It's very similar to short trails (see Note 1 - Cos above) except that instead of being sent the server time you are sent the heading of the aircraft at each coordinate. The idea is that the full track only shows the position the aircraft was in when its heading changed, so that if an aircraft travels in a straight line across the map then it can be described with just two positions - its start position and its end position - rather than hundreds of positions that together end up describing a straight line.

With that in mind, if just positions are being sent (TT is empty or missing) then the first value is latitude, the second value is longitude and the third is the heading angle (see Trak) that the aircraft was pointing in when it was at that position.

If altitude or speeds are also being sent (TT is either 'a' for altitude or 's' for speed) then the first value is latitude, the second longitude, the third is heading and the fourth is either altitude or speed.