Radar ADS-B Aircraft Real-Time Position V2.0
Related product: Real-Time Aircraft Tracking (ADS-B).
Introduction
This document describes the VariFlight Radar ADS-B Aircraft Real-Time Position V2.0 API, including authentication, request parameters, response fields, JSON examples and error responses. The interface uses UTF-8 encoding.
Authentication
The interface uses both token and IP for concurrent verification.
Token generation algorithm (MD5)
Registration code: Please obtain the registration code from the administrator of VariFlight. It is necessary for verification during the request process by both parties. Please be careful not to disclose it to the public.
Example (PHP):
<?php
function generateToken(array $data, string $appsecurity): string {
unset($data['token']);
ksort($data, SORT_STRING);
$pairs = [];
foreach ($data as $key => $value) {
$pairs[] = $key . '=' . $value;
}
$str = implode('&', $pairs);
return hash('md5', hash('md5', $str . $appsecurity));
}
// 参数值使用 UTF-8 原文;通过 token 参数传入结果,构建 URL 时再编码。
// $data['token'] = generateToken($data, $appsecurity);
// $query = http_build_query($data, '', '&', PHP_QUERY_RFC3986);
Example (Java):
import java.nio.charset.StandardCharsets;
import java.util.Map;
import java.util.stream.Collectors;
import java.security.MessageDigest;
import java.util.HexFormat;
public class TokenExample {
public static String generateToken(
Map<String, String> data, String appsecurity) throws Exception {
String str = data.entrySet().stream()
.filter(entry -> !"token".equals(entry.getKey()))
.sorted(Map.Entry.comparingByKey())
.map(entry -> entry.getKey() + "=" + entry.getValue())
.collect(Collectors.joining("&"));
return digestHex(digestHex(str + appsecurity));
}
private static String digestHex(String value) throws Exception {
byte[] bytes = MessageDigest.getInstance("MD5")
.digest(value.getBytes(StandardCharsets.UTF_8));
return HexFormat.of().formatHex(bytes);
}
}
// 请求 URL 追加 "&token=" + URLEncoder.encode(token, StandardCharsets.UTF_8)。
Example (C#):
using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Security.Cryptography;
public static class TokenExample {
public static string GenerateToken(
Dictionary<string, string> data, string appsecurity) {
string str = string.Join("&", data
.Where(entry => entry.Key != "token")
.OrderBy(entry => entry.Key, StringComparer.Ordinal)
.Select(entry => entry.Key + "=" + entry.Value));
return DigestHex(DigestHex(str + appsecurity));
}
private static string DigestHex(string value) {
using (var digest = MD5.Create()) {
byte[] result = digest.ComputeHash(Encoding.UTF8.GetBytes(value));
return BitConverter.ToString(result).Replace("-", "").ToLowerInvariant();
}
}
}
// 请求 URL 追加 "&token=" + Uri.EscapeDataString(token)。Query by Flight Number + Route + Date:
Request URL:
https://open-al.variflight.com/api/radarv2?appid=${appid}&arr=SHA&date=2019-07-10&dep=PEK&fnum=MU5138&lang=en&token=${token}The parameter part in the URL is:
appid=${appid}&arr=SHA&date=2019-07-10&dep=PEK&fnum=MU5138&lang=en&token=${token}
Generating the encrypted string:
str = appid=${appid}&arr=SHA&date=2019-07-10&dep=PEK&fnum=MU5138&lang=en
Step2. The registration code is '${appsecurity}'. Assign this value to the variable $appsecurity.
Append appsecurity (the registration code) directly to str, with no extra separator.
Apply MD5 twice. Each result is a 32-character lowercase hexadecimal string. The second digest takes the UTF-8 bytes of the first Hex string, not its raw digest bytes.
token = md5Hex(md5Hex(str + appsecurity))
Note: $appsecurity=Registration code
API Endpoints
The request URL:
https://open-al.variflight.com/api/radarv2?The way to request: GET
The format of return: json
Request parameter Details
Radar ADS-B Aircraft Real-Time Position V2.0 employs an authorized authentication interface. At the beginning of the cooperation, VariFlight will apply on behalf of the third party to allocate user identification codes and registration codes (i.e., appid and appsecurity).
1 Response 1
Inquiry Method: 1: Query by Flight Number + Route + Date
| Request parameter | Description | Example | Required or Optional | Parameter Type |
|---|---|---|---|---|
token |
Token | Yes | string |
|
date |
Defaults to today | 2019-07-10 | Yes | string |
appid |
App ID | Yes | string |
|
arr |
Destination Airport IATA Code | SHA | Yes | string |
dep |
Departure Airport IATA Code | PEK | Yes | string |
fnum |
Flight Number | MU5138 | Yes | string |
lang |
Optional. Defaults to Chinese; returns English when set to "en". | en | No | string |
Return Parameter Details
| Request parameter | Description | Example | Parameter Type |
|---|---|---|---|
leftTip |
Mileage and other tips | 1178 kilometers journey | string |
rightTip |
tip such as time | Arrive 47 minutes behind schedule | string |
distance |
Total Distance | 1178 | number |
percentage |
Full Flight Progress | 100% | string |
routeAlltime |
unit: seconds | 6600 | number |
airModels |
Aircraft Type | A333 | string |
flightStatus |
Flight Status | arrival | string |
p_flightNo |
Flight Number | MU5138 | string |
FlightCompany |
Airline | China Eastern Airlines | string |
FlightDepAirport |
Departure Airport Name | Beijing Capital | string |
FlightArrAirport |
Arrival Airport Name | Shanghai Hongqiao | string |
airplaneAge |
Aircraft Age | 4.3 | number |
AircraftNumber |
Aircraft Number | B304A | string |
line |
Flight Track | array |
|
time |
Data Retrieval Time | 1562716615 | number |
name |
City Name | Beijing | string |
airportName |
Airport Name | Beijing Capital | string |
code |
IATA Code | PEK | string |
position |
Position | object |
|
lng |
Longitude | 116.5871 | number |
vspeed |
Vertical Speed | 0 | number |
onground |
On Ground Flag | -1 | number |
tip |
description of the flight track at this point | destination | string |
lat |
Latitude | 40.07854 | number |
speed |
Speed | 0 | number |
angle |
Clockwise angle from true north, with true north as 0 degrees | 241 | number |
height |
Height | 0 | number |
pic |
Aircraft Image | http://file.veryzhun.com/buckets/adsb-dm/keys/20181101-222431-69905bdb0c9f29b19.jpg | string |
Return Parameter Examples
Example 1: Failed return
{
"error_code": 3,
"error": "Lack of parameters or parameter identification failed"
}
Example 2: Successful return
{
"line" : [ {
"position" : {
"lat" : 40.07854,
"lng" : 116.5871
},
"vspeed" : 0,
"height" : 0,
"angle" : 241,
"speed" : 0,
"time" : 1562716615,
"name" : "Beijing",
"airportName" : "Beijing Capital",
"code" : "PEK",
"onground" : -1,
"tip" : "destination"
} ],
"leftTip" : "1178 kilometers journey",
"rightTip" : "Arrive 47 minutes behind schedule",
"distance" : 1178,
"percentage" : "100%",
"routeAlltime" : 6600,
"airModels" : "A333",
"flightStatus" : "arrival",
"p_flightNo" : "MU5138",
"FlightCompany" : "China Eastern Airlines",
"FlightDepAirport" : "Beijing Capital",
"FlightArrAirport" : "Shanghai Hongqiao",
"airplaneAge" : 4.3,
"AircraftNumber" : "B304A",
"pic" : "http://file.veryzhun.com/buckets/adsb-dm/keys/20181101-222431-69905bdb0c9f29b19.jpg"
}Error Responses
| Return parameter | Description | Trigger Scene | Suggestions |
|---|---|---|---|
0 |
No data permissions | ||
2 |
The visiting ip have not been joined in white list | ||
3 |
This request method has no permission temporarily | ||
3 |
Lack of parameters or parameter identification failed | ||
3 |
wrong flight number format | ||
3 |
wrong departure airport format | ||
3 |
wrong arrival airport format | ||
19 |
No permissions to inquire inland data | ||
18 |
No permissions to inquire international data | ||
3 |
the radius can not be minus | ||
3 |
wrong date format | ||
3 |
No permissions to inquire future data | ||
13 |
No permissions to inquire data of current day | ||
12 |
No permissions to inquire historical data | ||
10 |
No data | ||
5 |
Flight does not exist | ||
5 |
No data | ||
4 |
The current interface is expired | ||
4 |
The current interface is closed | ||
4 |
No data permissions | ||
1 |
Pending review | ||
11 |
Unknown error | ||
0 |
Invalid user |
2 Response 2
Inquiry Method: 1: Query by Bottom-Left Coordinates + Top-Right Coordinates
| Request parameter | Description | Example | Required or Optional | Parameter Type |
|---|---|---|---|---|
appid |
App ID | Yes | string |
|
longrightup |
Top-Right Longitude | 122 | Yes | number |
token |
Token | Yes | string |
|
longleftdown |
Bottom-Left Latitude | 118 | Yes | number |
latrightup |
Bottom-Right Latitude | 37 | Yes | number |
latleftdown |
Bottom-Left Latitude | 32 | Yes | number |
lang |
Optional. Defaults to Chinese; returns English when set to "en". | en | No | string |
Inquiry Method: 2: Query by Center Coordinates + Radius
| Request parameter | Description | Example | Required or Optional | Parameter Type |
|---|---|---|---|---|
token |
Token | Yes | string |
|
longcenter |
Longitude | 118 | Yes | number |
latcenter |
Latitude | 32 | Yes | number |
radius |
Unit: km | 50 | Yes | number |
appid |
App ID | Yes | string |
|
lang |
Language Type | No | string |
Return Parameter Details
| Request parameter | Description | Example | Parameter Type |
|---|---|---|---|
flightCount |
Aircraft Count | 67 | number |
data |
Returned Data | array |
|
flightNo |
Flight Number | SC4663 | string |
dep |
Departure Airport IATA Code | TAO | string |
arr |
Destination Airport IATA Code | SHA | string |
height |
Height | 5394.9599609375 | number |
speed |
horizontal speed | 746.35601806641 | number |
angle |
Clockwise angle from true north, with true north as 0 degrees | 222 | number |
lat |
Latitude | 35.649052 | number |
lng |
Longitude | 120.42722 | number |
pic |
Aircraft Image | http://file.veryzhun.com/buckets/adsb-dm/keys/20181101-222431-69905bdb0c9f29b19.jpg | string |
Return Parameter Examples
Example 1: Failed return
{
"error_code": 3,
"error": "Lack of parameters or parameter identification failed"
}
Example 2: Successful return
{
"data" : [ {
"lat" : 35.649052,
"height" : 5394.9599609375,
"angle" : 222,
"lng" : 120.42722,
"speed" : 746.35601806641,
"pic" : "http://file.veryzhun.com/buckets/adsb-dm/keys/20181101-222431-69905bdb0c9f29b19.jpg",
"flightNo" : "SC4663",
"dep" : "TAO",
"arr" : "SHA"
} ],
"flightCount" : 67
}Error Responses
| Return parameter | Description | Trigger Scene | Suggestions |
|---|---|---|---|
0 |
No data permissions | ||
2 |
The visiting ip have not been joined in white list | ||
3 |
This request method has no permission temporarily | ||
3 |
Lack of parameters or parameter identification failed | ||
3 |
wrong flight number format | ||
3 |
wrong departure airport format | ||
3 |
wrong arrival airport format | ||
19 |
No permissions to inquire inland data | ||
18 |
No permissions to inquire international data | ||
3 |
the radius can not be minus | ||
3 |
wrong date format | ||
3 |
No permissions to inquire future data | ||
13 |
No permissions to inquire data of current day | ||
12 |
No permissions to inquire historical data | ||
10 |
No data | ||
5 |
Flight does not exist | ||
5 |
No data | ||
4 |
The current interface is expired | ||
4 |
The current interface is closed | ||
4 |
No data permissions | ||
1 |
Pending review | ||
11 |
Unknown error | ||
0 |
Invalid user |
3 Response 3
Inquiry Method: 1: Query by Aircraft Number
| Request parameter | Description | Example | Required or Optional | Parameter Type |
|---|---|---|---|---|
token |
Token | Yes | string |
|
anum |
Aircraft Number | B209Q | Yes | string |
appid |
App ID | Yes | string |
|
lang |
Optional. Defaults to Chinese; returns English when set to "en". | en | No | string |
Return Parameter Details
| Request parameter | Description | Example | Parameter Type |
|---|---|---|---|
arr |
Destination IATA Code | SHA | string |
anum |
Aircraft Number | B5969 | string |
speed |
Speed | 835.252 | number |
dep |
Departure Airport IATA Code | HKG | string |
fnum |
Flight Number | FM3012 | string |
vspeed |
Vertical Speed | 0 | number |
angle |
Angle | 41 | number |
position |
Position | object |
|
lng |
Longitude | 116.21353 | number |
lat |
Latitude | 22.77429 | number |
updatetime |
Data Update Time | 1727590571 | number |
height |
Height | 10058.4 | number |
pic |
Image | http://file.veryzhun.com/buckets/wxapp/keys/20190108-104617-138g2sqw7bku7l0l.jpg | string |
Return Parameter Examples
Example 1: Failed return
{
"error_code": 3,
"error": "Lack of parameters or parameter identification failed"
}
Example 2: Successful return
{
"position" : {
"lat" : 22.77429,
"lng" : 116.21353
},
"vspeed" : 0,
"height" : 10058.4,
"angle" : 41,
"speed" : 835.252,
"pic" : "http://file.veryzhun.com/buckets/wxapp/keys/20190108-104617-138g2sqw7bku7l0l.jpg",
"dep" : "HKG",
"arr" : "SHA",
"anum" : "B5969",
"fnum" : "FM3012",
"updatetime" : 1727590571
}Error Responses
| Return parameter | Description | Trigger Scene | Suggestions |
|---|---|---|---|
0 |
No data permissions | ||
2 |
The visiting ip have not been joined in white list | ||
3 |
This request method has no permission temporarily | ||
3 |
Lack of parameters or parameter identification failed | ||
3 |
wrong flight number format | ||
3 |
wrong departure airport format | ||
3 |
wrong arrival airport format | ||
19 |
No permissions to inquire inland data | ||
18 |
No permissions to inquire international data | ||
3 |
the radius can not be minus | ||
3 |
wrong date format | ||
3 |
No permissions to inquire future data | ||
13 |
No permissions to inquire data of current day | ||
12 |
No permissions to inquire historical data | ||
10 |
No data | ||
5 |
Flight does not exist | ||
5 |
No data | ||
4 |
The current interface is expired | ||
4 |
The current interface is closed | ||
4 |
No data permissions | ||
1 |
Pending review | ||
11 |
Unknown error | ||
0 |
Invalid user |
