API docs

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.

Produced by
VariFlight
Create time
October 22, 2026
Appid
${appid}
Appsecurity
${appsecurity}

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

GEThttps://open-al.variflight.com/api/addflightpush

Request 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)

Note: the token itself never takes part in the signature. Every other parameter actually present in the URL — including optional parameters such as fid and lang — must be included.

Request the registration code from your VariFlight administrator. It is used for mutual authentication and must be kept strictly confidential.

Example (PHP):

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):

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#):

CSHARP
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)。
Note: appsecurity in the samples above denotes the registration code.

Worked example

Customize by Flight Number + Route + Date:

Request URL:

TEXT
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:

TEXT
str = appid=${appid}&arr=YIH&date=2023-03-08&dep=HAK&fid=a2014090511012&fnum=GX8915&lang=

2. Take the registration code appsecurity:

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

TEXT
token = md5Hex(md5Hex(str + appsecurity))

Request Parameters

ParameterDescriptionExampleRequiredType
appidApp IDYesstring
tokenTokenYesstring
fnumFlight NumberGX8915Yesstring
depDeparture Airport IATA CodeHAKYesstring
arrDestination Airport IATA CodeYIHYesstring
fidFlight identifier string returned to the user when pushing real-time data. Digits or letters, max 20 characters. May be empty. Optional.a2014090511012Nostring
dateyyyy-mm-dd format2023-03-08Yesstring
langlang=en for English; any other value is Chinese (Chinese also applies when lang is omitted)Nostring

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

ParameterDescriptionExampleType
error_codeStatus Codenumber
errorStatus Namestring
FlightDeptimePlanDateScheduled Departure Timestring
FlightArrtimePlanDateScheduled Arrival Timestring

Response examples:

Successful subscription (error_code is 8 on success):

JSON
{
  "error_code" : 8,
  "error" : "success",
  "FlightDeptimePlanDate" : "",
  "FlightArrtimePlanDate" : ""
}

Error response:

JSON
{
  "error_code": 3,
  "error": "Lack of parameters or parameter identification failed"
}

Error Codes

error_codeDescription
2The requesting IP address is not on the IP allowlist
3Missing parameter or parameter validation failed (e.g. invalid token, date, flight number, origin/destination or fid format)
4No data permission (interface not enabled, disabled or expired, or invalid request method)
5No flight matches the given criteria
6Duplicate subscription is not allowed
8Subscription succeeded
11Unknown error (subscription failed)
500Unknown 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.

ParameterDescriptionExampleType
fcategoryFlight Attributestring
ftypeAircraft Type CodeB738string
fserviceType Of Aircraft (J: Passenger; F: Cargo)Jstring
FirstClassCheckinTableFirst Class Check-In CounterC3string
BusinessCheckinTableBusiness Class Check-In CounterC3string
FlightNoFlight NumberSC7621string
FlightCompanyAirline NameShandong Airlinesstring
FlightDepcodeDeparture Airport IATA CodeYNTstring
FlightArrcodeArrival Airport CodeCANstring
AircraftNumberAircraft NumberB306Rstring
FlightDeptimePlanDateScheduled Departure Time2023-12-22 08:20:00string
FlightArrtimePlanDateScheduled Arrival Time2023-12-22 11:20:00string
FFlightDeptimePlanDateOriginal Scheduled Departure Time2023-12-22 07:05:00string
FFlightArrtimePlanDateOriginal Scheduled Arrival Time2023-12-22 10:35:00string
FlightDeptimeReadyDateOfficial Estimated Departure Time2023-12-22 08:20:00string
FlightArrtimeReadyDateOfficial Estimated Arrival Time2023-12-22 11:20:00string
FlightDeptimeDateActual Departure Time2023-12-22 08:28:00string
FlightArrtimeDateActual Arrival Time2023-12-22 11:28:00string
FlightIngateTimeOn-Block Actual Time2023-12-22 11:57:00string
FlightOutgateTimeOff-Block Actual Time2023-12-22 11:57:00string
CheckinTableCheck-In CounterCstring
CheckDoorAirport Entrance Doorgate 4string
BoardGateBoarding Gate15string
ReachExitAirport Arrival ExitW1string
BaggageIDBaggage Turntable7string
BoardStateBoarding Statuscheck-instring
FlightStateFlight Statusschedulestring
FlightHTerminalDeparture TerminalT1string
FlightTerminalArrival TerminalT1string
org_timezoneDeparture Time Zone28800string
dst_timezoneDestination Time Zone28800string
ShareFlightNoCodeshare Flight Numberstring
StopFlagStop Flag1string
ShareFlagCode Share Flag1string
VirtualFlagVirtual Flag0string
BoardGateTimeSecurity Gate To Boarding Gate Walking Timestring
ArrStandGateInbound Aircraft Stand212string
DepStandGateDeparture Aircraft Stand309string
DelayReasonDelay ReasonATC flow control restrictionsstring
LegFlagSegment Flag0string
FoodMealstring
LastCheckinTimeLatest Check-In Cutoff Time2023-12-22 07:45:00string
EstimateBoardingStartTimeEstimated Boarding Start Timestring
EstimateBoardingEndTimeEstimated Boarding End Timestring
FlightDepDeparture City NameYantaistring
FlightArrArrival City NameGuangzhoustring
deptelDeparture Airport Information Hotline0535-5134352string
arrtelArrival Airport Information Hotline020-96158string
TodayTimeRateToday On-Time Ratestring
airlinetelAirline Information Hotline95369string
FlightWaitDataFlight Queue Status0number
bridgeOutbound Boarding Bridgenot utilize aerobridgestring
arr_bridgeInbound Boarding Bridgeutilize aerobridgestring
FlightDepAirportDeparture Airport NameYantai Penglaistring
FlightArrAirportArrival Airport NameGuangzhou Baiyunstring
OntimeRateHistorical Punctuality Rate80.00%string
genericAircraft TypeBoeing 737-85Nstring
FlightYearAircraft Age7.3number
ArrOntimeRateHistorical Arrival On-Time Rate83.33%string
DepWeatherDeparture Airport WeatherSnow Shower to Cloudy|||89|-4/-10string
ArrWeatherArrival Airport WeatherCloudy|||102|12/3string
FlightDurationDuration Of Flight171string
distanceFlight Distance2132string
FastestExitDurationFastest Exit Duration62.8number
SlowestExitDurationSlowest Exit Duration73.8number
FastestExitTimeFastest Exit Time2023-12-22 12:45:48string
SlowestExitTimeSlowest Exit Time2023-12-22 12:56:48string
DepOnCargodoorTimeTakeoff Cargo Door Open Timestring
DepOffCargodoorTimeDeparture Cargo Door Close Timestring
ArrOnCargodoorTimeArrival Cargo Door Open Timestring
ArrOffCargodoorTimeArrival Cargo Door Close Timestring
ChangePlaneAircraft Change Flag0string
VeryZhunReadyDeptimeDateVariFlight Estimated Departure Time2023-12-22 08:29:00string
VeryZhunReadyArrtimeDateVariFlight Estimated Arrival Time2023-12-22 11:43:18string
AssistFlightStateAuxiliary Flight Statusarrivalstring
DepAirportLatDeparture Airport Latitude37.660556string
DepAirportLonDeparture Airport Longitude120.979167string
DepTerminalLatDeparture Terminal Latitude37.664518string
DepTerminalLonDeparture Terminal Longitude120.99807string
ArrAirportLonArrival Airport Longitude113.29734string
ArrTerminalLonArrival Terminal Longitude113.309858string
ArrAirportLatArrival Airport Latitude23.387861string
ArrTerminalLatArrival Terminal Latitude23.393169string
FlightCancelTimeFlight Cancellation Timestring
FlightStateNumFlight Status Value1number
FillFlightNoSubstituted Flight Numberstring
StopAirportCodeStopover Airport IATA Codestring
alternate_infoDiversion Informationarray
AlternateStatusDiverted Flight Statusarrivalstring
AlternateDepCityDiverted Departure Airport NameGuilin Liangjiangstring
AlternateArrCityDiverted Arrival Airport NameGuangzhou Baiyunstring
AlternateDepAirportPost-Diversion Departure Airport IATA CodeKWLstring
AlternateArrAirportPost-Diversion Arrival Airport IATA CodeCANstring
AlternateDeptimePlanPost-Diversion Scheduled Takeoff Time2026-09-14 16:32:00string
AlternateArrtimePlanPost-Diversion Scheduled Arrival Time2026-09-14 17:02:00string
AlternateDeptimeDiverted Actual Departure Time2026-09-14 17:59:00string
AlternateArrtimeDiverted Actual Arrival Time2026-09-14 18:59:00string
AlternateDepTimezonePost-Diversion Departure Airport Time Zone28800string
AlternateArrTimezoneDiversion Arrival Airport Time Zone28800string
StopCityStopover Citystring
depctryDeparture Country Alpha-2 CodeCNstring
depprovDeparture Airport Province新疆string
arrctryArrival Country Alpha-2 CodeCNstring
arrprovArrival Airport Province广东string
depcontinentDeparture Country Continent亚洲string
arrcontinentArrival Country Continent亚洲string
fidFlight IDstring
FillFlightInfoExtra Flight Infoobject
FlightNoFlight Number9C668Qstring
FlightDepcodeExtra Flight Departure Airport IATA CodeURCstring
FlightArrcodeArrival Airport CodeAATstring
FlightStateFlight Statusschedulestring
FlightDeptimePlanDateScheduled Departure Time2025-11-14 12:30:00string
FlightArrtimePlanDateScheduled Arrival Time2025-11-14 13:40:00string
FlightDeptimeDateActual Departure Time2025-11-14 12:30:00string
FlightArrtimeDateActual Arrival Time2025-11-14 13:40:00string

Push payload example (the outermost element is a JSON array):

JSON
[ {
  "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:

FlightStateNumFlightState (lang=EN)
0schedule
1departure
2arrival
3cancel
4delay
5diversion
11return
13delay alert
14cancellation alert
31diverted flight departure
32diverted flight arrival
33diverted flight cancel
41returned flight departure
42returned flight arrival
43returned flight cancel
73cancel in advance