This JSON file reports on the state of all of the aircraft tracked by a receiver or merged feed.
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:
|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.
|fAir||String||The to / from / via airport code|
|fAlt||Integer range||Altitude in feet|
|fDst||Number range||Distance in kilometres|
|fNoPos||Boolean||No position transmitted|
|fTyp||String||Model ICAO code|
|fOpIcao||String||Operator ICAO code|
|fInt||Boolean||Is flagged as interesting in database|
|fWtc||Enum||Wake turbulence category|
|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|
|Equals||Q||String, Boolean, Enum|
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).
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=.
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.
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.
|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.|
|shtTrlSec||Number||The number of seconds of positions that short trails contain.|
|acList||Array||The aircraft list. See below.|
|feeds||Array||A list of every feed configured on the server. The feed object is |
|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.
|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.|
|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.|
|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.|
|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.|
|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 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:
|||Latitude of earliest coordinate|
|||Longitude of earliest coordinate|
|||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.