Documentation Formats

 

AircraftList.json

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
fOpIcaoString 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.