Subscription-Based Flight Status Push Alerts API v3.0
Learn how to subscribe to flights and receive status updates with the VariFlight DataWorks Flight Status Subscription and Push API. This documentation covers authentication, subscription requests, JSON push payloads and delivery acknowledgements.
For product details, see the Flight Status Data API.
With a vision of "living on time" , a global leading aviation data intelligence company
Step 1: Subscription
Introduction
This document specifies the VariFlight subscription-based flight status push service. The service works in two steps: in Step 1 you subscribe to a flight by calling the subscription endpoint; in Step 2, once the subscription is active, status updates for that flight are pushed to your receiving endpoint. UTF-8 encoding is used throughout.
Endpoint
https://open-al.variflight.com/api/addflightpushRequest method: GET
Response format: JSON (UTF-8)
Authentication
When the partnership is established, VariFlight assigns each partner a user identification code (appid) and a registration code (appsecurity).
Every request is validated by two mechanisms — a request token and an IP allowlist:
- IP allowlist: requests are accepted only from allowlisted IP addresses; any other source receives error_code = 2.
- Token: computed for every request with the algorithm below and passed in the token parameter.
Token generation algorithm (MD5)
Request the registration code from your VariFlight administrator. It is used for mutual authentication and must be kept strictly confidential.
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)。Worked example
Customize by Flight Number + Route + Date:
Request URL:
https://open-al.variflight.com/api/addflightpush?appid=${appid}&arr=YIH&date=2023-03-08&dep=HAK&fid=a2014090511012&fnum=GX8915&lang=&token=${token}1. Take all request parameters except token and sort them by parameter name in ascending ASCII order to obtain the signature string str:
str = appid=${appid}&arr=YIH&date=2023-03-08&dep=HAK&fid=a2014090511012&fnum=GX8915&lang=2. Take the registration code appsecurity:
appsecurity = ${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))Request Parameters
| Parameter | Description | Example | Required | Type |
|---|---|---|---|---|
appid | App ID | Yes | string | |
token | Token | Yes | string | |
fnum | Flight Number | GX8915 | Yes | string |
dep | Departure Airport IATA Code | HAK | Yes | string |
arr | Destination Airport IATA Code | YIH | Yes | string |
fid | Flight identifier string returned to the user when pushing real-time data. Digits or letters, max 20 characters. May be empty. Optional. | a2014090511012 | No | string |
date | yyyy-mm-dd format | 2023-03-08 | Yes | string |
lang | lang=en for English; any other value is Chinese (Chinese also applies when lang is omitted) | No | string |
Parameter format rules
- fnum: 3–7 alphanumeric characters; the server strips leading zeros after the airline code (e.g. CA0123 → CA123).
- dep / arr: 3-letter IATA airport code.
- date: YYYY-MM-DD format; must not be earlier than yesterday.
- fid: up to 50 characters; digits, letters, underscores and hyphens only. It is echoed back verbatim in every push payload for correlation on your side, and is part of the subscription identity — subscribing to the same flight with a different fid creates a separate subscription.
- lang: pass EN for English responses; Chinese is returned by default.
Response Parameters
| Parameter | Description | Example | Type |
|---|---|---|---|
error_code | Status Code | number | |
error | Status Name | string | |
FlightDeptimePlanDate | Scheduled Departure Time | string | |
FlightArrtimePlanDate | Scheduled Arrival Time | string |
Response examples:
Successful subscription (error_code is 8 on success):
{
"error_code" : 8,
"error" : "success",
"FlightDeptimePlanDate" : "",
"FlightArrtimePlanDate" : ""
}Error response:
{
"error_code": 3,
"error": "Lack of parameters or parameter identification failed"
}Error Codes
| error_code | Description |
|---|---|
2 | The requesting IP address is not on the IP allowlist |
3 | Missing parameter or parameter validation failed (e.g. invalid token, date, flight number, origin/destination or fid format) |
4 | No data permission (interface not enabled, disabled or expired, or invalid request method) |
5 | No flight matches the given criteria |
6 | Duplicate subscription is not allowed |
8 | Subscription succeeded |
11 | Unknown error (subscription failed) |
500 | Unknown error (internal server error) |
Subscription Rules
- A subscription is uniquely identified by the combination of appid + flight number + origin airport + destination airport + flight date + fid + language (lang). Submitting the exact same combination again returns error_code = 6, while a different fid (or lang) creates a new, independent subscription with its own push stream.
- Once a subscription succeeds, every subsequent change to the flight data is pushed to your receiving endpoint as described in Step 2, including updates after arrival or cancellation (e.g. baggage carousel).
- With lang=EN, both the subscription response and the push payloads are returned in English.
Step 2: Push Alerts
Introduction
Once a subscription is active, whenever the status data of the flight changes, the system automatically pushes the latest data to the receiving endpoint you provide.
- Push payloads are UTF-8 encoded JSON; URL decoding is not required.
- A push is triggered only when the data content actually changes (payloads are deduplicated); a flight is typically pushed several times over its life cycle.
- Respond with an HTTP 2xx status code to acknowledge delivery; on any non-2xx response the system retries.
Push Method
HTTP POST.
- The request body is a JSON array containing the flight object(s) for the subscribed segment (usually one).
- Content-Type is application/json;charset=utf-8.
Push Parameters
The set of pushed fields is determined by the field permissions enabled for your account. Enabled fields that currently have no data are sent as an empty string ("") — except the array field alternate_info, which is sent as [], and the object field FillFlightInfo, which is sent as null.
| Parameter | Description | Example | Type |
|---|---|---|---|
fcategory | Flight Attribute | string | |
ftype | Aircraft Type Code | B738 | string |
fservice | Type Of Aircraft (J: Passenger; F: Cargo) | J | string |
FirstClassCheckinTable | First Class Check-In Counter | C3 | string |
BusinessCheckinTable | Business Class Check-In Counter | C3 | string |
FlightNo | Flight Number | SC7621 | string |
FlightCompany | Airline Name | Shandong Airlines | string |
FlightDepcode | Departure Airport IATA Code | YNT | string |
FlightArrcode | Arrival Airport Code | CAN | string |
AircraftNumber | Aircraft Number | B306R | string |
FlightDeptimePlanDate | Scheduled Departure Time | 2023-12-22 08:20:00 | string |
FlightArrtimePlanDate | Scheduled Arrival Time | 2023-12-22 11:20:00 | string |
FFlightDeptimePlanDate | Original Scheduled Departure Time | 2023-12-22 07:05:00 | string |
FFlightArrtimePlanDate | Original Scheduled Arrival Time | 2023-12-22 10:35:00 | string |
FlightDeptimeReadyDate | Official Estimated Departure Time | 2023-12-22 08:20:00 | string |
FlightArrtimeReadyDate | Official Estimated Arrival Time | 2023-12-22 11:20:00 | string |
FlightDeptimeDate | Actual Departure Time | 2023-12-22 08:28:00 | string |
FlightArrtimeDate | Actual Arrival Time | 2023-12-22 11:28:00 | string |
FlightIngateTime | On-Block Actual Time | 2023-12-22 11:57:00 | string |
FlightOutgateTime | Off-Block Actual Time | 2023-12-22 11:57:00 | string |
CheckinTable | Check-In Counter | C | string |
CheckDoor | Airport Entrance Door | gate 4 | string |
BoardGate | Boarding Gate | 15 | string |
ReachExit | Airport Arrival Exit | W1 | string |
BaggageID | Baggage Turntable | 7 | string |
BoardState | Boarding Status | check-in | string |
FlightState | Flight Status | schedule | string |
FlightHTerminal | Departure Terminal | T1 | string |
FlightTerminal | Arrival Terminal | T1 | string |
org_timezone | Departure Time Zone | 28800 | string |
dst_timezone | Destination Time Zone | 28800 | string |
ShareFlightNo | Codeshare Flight Number | string | |
StopFlag | Stop Flag | 1 | string |
ShareFlag | Code Share Flag | 1 | string |
VirtualFlag | Virtual Flag | 0 | string |
BoardGateTime | Security Gate To Boarding Gate Walking Time | string | |
ArrStandGate | Inbound Aircraft Stand | 212 | string |
DepStandGate | Departure Aircraft Stand | 309 | string |
DelayReason | Delay Reason | ATC flow control restrictions | string |
LegFlag | Segment Flag | 0 | string |
Food | Meal | string | |
LastCheckinTime | Latest Check-In Cutoff Time | 2023-12-22 07:45:00 | string |
EstimateBoardingStartTime | Estimated Boarding Start Time | string | |
EstimateBoardingEndTime | Estimated Boarding End Time | string | |
FlightDep | Departure City Name | Yantai | string |
FlightArr | Arrival City Name | Guangzhou | string |
deptel | Departure Airport Information Hotline | 0535-5134352 | string |
arrtel | Arrival Airport Information Hotline | 020-96158 | string |
TodayTimeRate | Today On-Time Rate | string | |
airlinetel | Airline Information Hotline | 95369 | string |
FlightWaitData | Flight Queue Status | 0 | number |
bridge | Outbound Boarding Bridge | not utilize aerobridge | string |
arr_bridge | Inbound Boarding Bridge | utilize aerobridge | string |
FlightDepAirport | Departure Airport Name | Yantai Penglai | string |
FlightArrAirport | Arrival Airport Name | Guangzhou Baiyun | string |
OntimeRate | Historical Punctuality Rate | 80.00% | string |
generic | Aircraft Type | Boeing 737-85N | string |
FlightYear | Aircraft Age | 7.3 | number |
ArrOntimeRate | Historical Arrival On-Time Rate | 83.33% | string |
DepWeather | Departure Airport Weather | Snow Shower to Cloudy|||89|-4/-10 | string |
ArrWeather | Arrival Airport Weather | Cloudy|||102|12/3 | string |
FlightDuration | Duration Of Flight | 171 | string |
distance | Flight Distance | 2132 | string |
FastestExitDuration | Fastest Exit Duration | 62.8 | number |
SlowestExitDuration | Slowest Exit Duration | 73.8 | number |
FastestExitTime | Fastest Exit Time | 2023-12-22 12:45:48 | string |
SlowestExitTime | Slowest Exit Time | 2023-12-22 12:56:48 | string |
DepOnCargodoorTime | Takeoff Cargo Door Open Time | string | |
DepOffCargodoorTime | Departure Cargo Door Close Time | string | |
ArrOnCargodoorTime | Arrival Cargo Door Open Time | string | |
ArrOffCargodoorTime | Arrival Cargo Door Close Time | string | |
ChangePlane | Aircraft Change Flag | 0 | string |
VeryZhunReadyDeptimeDate | VariFlight Estimated Departure Time | 2023-12-22 08:29:00 | string |
VeryZhunReadyArrtimeDate | VariFlight Estimated Arrival Time | 2023-12-22 11:43:18 | string |
AssistFlightState | Auxiliary Flight Status | arrival | string |
DepAirportLat | Departure Airport Latitude | 37.660556 | string |
DepAirportLon | Departure Airport Longitude | 120.979167 | string |
DepTerminalLat | Departure Terminal Latitude | 37.664518 | string |
DepTerminalLon | Departure Terminal Longitude | 120.99807 | string |
ArrAirportLon | Arrival Airport Longitude | 113.29734 | string |
ArrTerminalLon | Arrival Terminal Longitude | 113.309858 | string |
ArrAirportLat | Arrival Airport Latitude | 23.387861 | string |
ArrTerminalLat | Arrival Terminal Latitude | 23.393169 | string |
FlightCancelTime | Flight Cancellation Time | string | |
FlightStateNum | Flight Status Value | 1 | number |
FillFlightNo | Substituted Flight Number | string | |
StopAirportCode | Stopover Airport IATA Code | string | |
alternate_info | Diversion Information | array | |
AlternateStatus | Diverted Flight Status | arrival | string |
AlternateDepCity | Diverted Departure Airport Name | Guilin Liangjiang | string |
AlternateArrCity | Diverted Arrival Airport Name | Guangzhou Baiyun | string |
AlternateDepAirport | Post-Diversion Departure Airport IATA Code | KWL | string |
AlternateArrAirport | Post-Diversion Arrival Airport IATA Code | CAN | string |
AlternateDeptimePlan | Post-Diversion Scheduled Takeoff Time | 2026-09-14 16:32:00 | string |
AlternateArrtimePlan | Post-Diversion Scheduled Arrival Time | 2026-09-14 17:02:00 | string |
AlternateDeptime | Diverted Actual Departure Time | 2026-09-14 17:59:00 | string |
AlternateArrtime | Diverted Actual Arrival Time | 2026-09-14 18:59:00 | string |
AlternateDepTimezone | Post-Diversion Departure Airport Time Zone | 28800 | string |
AlternateArrTimezone | Diversion Arrival Airport Time Zone | 28800 | string |
StopCity | Stopover City | string | |
depctry | Departure Country Alpha-2 Code | CN | string |
depprov | Departure Airport Province | 新疆 | string |
arrctry | Arrival Country Alpha-2 Code | CN | string |
arrprov | Arrival Airport Province | 广东 | string |
depcontinent | Departure Country Continent | 亚洲 | string |
arrcontinent | Arrival Country Continent | 亚洲 | string |
fid | Flight ID | string | |
FillFlightInfo | Extra Flight Info | object | |
FlightNo | Flight Number | 9C668Q | string |
FlightDepcode | Extra Flight Departure Airport IATA Code | URC | string |
FlightArrcode | Arrival Airport Code | AAT | string |
FlightState | Flight Status | schedule | string |
FlightDeptimePlanDate | Scheduled Departure Time | 2025-11-14 12:30:00 | string |
FlightArrtimePlanDate | Scheduled Arrival Time | 2025-11-14 13:40:00 | string |
FlightDeptimeDate | Actual Departure Time | 2025-11-14 12:30:00 | string |
FlightArrtimeDate | Actual Arrival Time | 2025-11-14 13:40:00 | string |
Push payload example (the outermost element is a JSON array):
[ {
"fcategory" : "",
"ftype" : "B738",
"fservice" : "J",
"FirstClassCheckinTable" : "C3",
"BusinessCheckinTable" : "C3",
"FlightNo" : "SC7621",
"FlightCompany" : "Shandong Airlines",
"FlightDepcode" : "YNT",
"FlightArrcode" : "CAN",
"AircraftNumber" : "B306R",
"FlightDeptimePlanDate" : "2023-12-22 08:20:00",
"FlightArrtimePlanDate" : "2023-12-22 11:20:00",
"FFlightDeptimePlanDate" : "2023-12-22 07:05:00",
"FFlightArrtimePlanDate" : "2023-12-22 10:35:00",
"FlightDeptimeReadyDate" : "2023-12-22 08:20:00",
"FlightArrtimeReadyDate" : "2023-12-22 11:20:00",
"FlightDeptimeDate" : "2023-12-22 08:28:00",
"FlightArrtimeDate" : "2023-12-22 11:28:00",
"FlightIngateTime" : "2023-12-22 11:57:00",
"FlightOutgateTime" : "2023-12-22 11:57:00",
"CheckinTable" : "C",
"CheckDoor" : "gate 4",
"BoardGate" : "15",
"ReachExit" : "W1",
"BaggageID" : "7",
"BoardState" : "check-in",
"FlightState" : "schedule",
"FlightHTerminal" : "T1",
"FlightTerminal" : "T1",
"ShareFlightNo" : "",
"StopFlag" : "1",
"ShareFlag" : "1",
"VirtualFlag" : "0",
"BoardGateTime" : "",
"ArrStandGate" : "212",
"DepStandGate" : "309",
"DelayReason" : "ATC flow control restrictions",
"LegFlag" : "0",
"Food" : "",
"EstimateBoardingEndTime" : "",
"FlightDep" : "Yantai",
"FlightArr" : "Guangzhou",
"deptel" : "0535-5134352",
"arrtel" : "020-96158",
"TodayTimeRate" : "",
"airlinetel" : "95369",
"FlightWaitData" : 0,
"bridge" : "not utilize aerobridge",
"arr_bridge" : "utilize aerobridge",
"FlightDepAirport" : "Yantai Penglai",
"FlightArrAirport" : "Guangzhou Baiyun",
"OntimeRate" : "80.00%",
"generic" : "Boeing 737-85N",
"FlightYear" : 7.3,
"ArrOntimeRate" : "83.33%",
"DepWeather" : "Snow Shower to Cloudy|||89|-4/-10",
"ArrWeather" : "Cloudy|||102|12/3",
"FlightDuration" : "171",
"distance" : "2132",
"FastestExitDuration" : 62.8,
"SlowestExitDuration" : 73.8,
"FastestExitTime" : "2023-12-22 12:45:48",
"SlowestExitTime" : "2023-12-22 12:56:48",
"DepOnCargodoorTime" : "",
"DepOffCargodoorTime" : "",
"ArrOnCargodoorTime" : "",
"ArrOffCargodoorTime" : "",
"ChangePlane" : "0",
"VeryZhunReadyDeptimeDate" : "2023-12-22 08:29:00",
"VeryZhunReadyArrtimeDate" : "2023-12-22 11:43:18",
"AssistFlightState" : "arrival",
"DepAirportLat" : "37.660556",
"DepAirportLon" : "120.979167",
"DepTerminalLat" : "37.664518",
"DepTerminalLon" : "120.99807",
"ArrAirportLon" : "113.29734",
"ArrTerminalLon" : "113.309858",
"ArrAirportLat" : "23.387861",
"ArrTerminalLat" : "23.393169",
"FlightCancelTime" : "",
"FlightStateNum" : 1,
"FillFlightNo" : "",
"StopAirportCode" : "",
"alternate_info" : [ {
"AlternateArrCity" : "Guangzhou Baiyun",
"AlternateDepAirport " : "KWL",
"AlternateArrAirport" : "CAN",
"AlternateDeptimePlan" : "2026-09-14 16:32:00",
"AlternateArrtimePlan" : "2026-09-14 17:02:00",
"AlternateDeptime" : "2026-09-14 17:59:00",
"AlternateArrtime" : "2026-09-14 18:59:00",
"AlternateDepTimezone" : "28800",
"AlternateArrTimezone" : "28800",
"AlternateDepCity" : "Guilin Liangjiang",
"AlternateStatus" : "arrival"
} ],
"StopCity" : "",
"depctry" : "CN",
"depprov" : "新疆",
"arrctry" : "CN",
"arrprov" : "广东",
"depcontinent" : "亚洲",
"FillFlightInfo" : {
"FlightNo" : "9C668Q",
"FlightDepcode" : "URC",
"FlightArrcode" : "AAT",
"FlightState" : "schedule",
"FlightDeptimePlanDate" : "2025-11-14 12:30:00",
"FlightArrtimePlanDate" : "2025-11-14 13:40:00",
"FlightDeptimeDate" : "2025-11-14 12:30:00",
"FlightArrtimeDate" : "2025-11-14 13:40:00"
},
"LastCheckinTime" : "2023-12-22 07:45:00",
"EstimateBoardingStartTime" : "",
"fid" : "",
"arrcontinent" : "亚洲",
"dst_timezone" : "28800",
"org_timezone" : "28800"
} ]Flight Status Codes
In response and push payloads, the FlightStateNum field carries the numeric status code and the FlightState field carries the status text (with lang=EN), mapped as follows:
| FlightStateNum | FlightState (lang=EN) |
|---|---|
0 | schedule |
1 | departure |
2 | arrival |
3 | cancel |
4 | delay |
5 | diversion |
11 | return |
13 | delay alert |
14 | cancellation alert |
31 | diverted flight departure |
32 | diverted flight arrival |
33 | diverted flight cancel |
41 | returned flight departure |
42 | returned flight arrival |
43 | returned flight cancel |
73 | cancel in advance |
