Flight Status Query API V3.0

Appsecurity: ${appsecurity}

With a vision of "living on time" , a global leading aviation data intelligence company

The VariFlight DataWorks Flight Status Query API supports flight-status queries by flight number, airport or city route, and airport arrivals or departures with a date. This documentation covers authentication, request parameters, JSON response fields, pagination, error codes and flight status definitions.

Appid: ${appid}

Create time: 2026-10-22

https://dataworks.variflight.com Email: dataworks@variflight.com

Related product: Flight Status Data API.

Flight Status API

Introduction

This document specifies the VariFlight flight status query API, covering the request format, authentication, parameters, response structures and error codes. UTF-8 encoding is used throughout.

Endpoint

https://open-al.variflight.com/api/flight

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

Note: appsecurity in the samples above denotes the registration code.

Worked example

Query by Flight Number + Date (Route Empty):

Request URL:

https://open-al.variflight.com/api/flight?appid=${appid}&date=2023-02-24&fid=&fnum=GX8915&lang=EN&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}&date=2023-02-24&fid=&fnum=GX8915&lang=EN

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 and Response Parameters

The API supports multiple query modes. The sections below are grouped by response structure; each group lists its query modes together with the corresponding request and response fields.

Response group 1

Query mode 1: Query by Flight Number + Date (Route Empty)

Parameter	Description	Example	Required	Type
`fnum`	Required	GX8915	Yes	`string`
`date`	yyyy-mm-dd format	2023-02-24	Yes	`string`
`appid`	App ID		Yes	`string`
`token`	Token		Yes	`string`
`lang`	Optional. Defaults to Chinese; returns English when set to "en".	EN	No	`string`
`fid`	Flight ID		No	`string`

Query mode 2: Query by Airport Route + Date (Flight Number Empty)

Parameter	Description	Example	Required	Type
`dep`	Departure Airport IATA Code	HAK	Yes	`string`
`arr`	Arrival Airport IATA Code	YIH	Yes	`string`
`date`	yyyy-mm-dd format	2014-09-18	Yes	`string`
`appid`	App ID		Yes	`string`
`token`	Token		Yes	`string`
`lang`	Optional. Defaults to Chinese; returns English when set to "en".	EN	No	`string`
`fid`	Flight ID		No	`string`

Remark: lang is optional; defaults to Chinese when not provided.

Query mode 3: Query by City Route + Date (Flight Number Empty)

Parameter	Description	Example	Required	Type
`depcity`	Note: this is the city IATA code	BJS	Yes	`string`
`arrcity`	Note: this is the city IATA code	SHA	Yes	`string`
`date`	yyyy-mm-dd	2014-09-18	Yes	`string`
`appid`	App ID		Yes	`string`
`token`	Token		Yes	`string`
`lang`	Optional. Defaults to Chinese; returns English when set to "en".	EN	No	`string`
`fid`	Flight ID		No	`string`

Remark: lang is optional; defaults to Chinese when not provided.

Query mode 4: Query by Flight Four Elements

Parameter	Description	Example	Required	Type
`fnum`	Flight Number	GX8915	Yes	`string`
`dep`	Departure Airport IATA Code	HAK	Yes	`string`
`arr`	Arrival Airport IATA Code	YIH	Yes	`string`
`date`	Date	2014-09-18	Yes	`string`
`appid`	App ID		Yes	`string`
`token`	Token		Yes	`string`
`lang`	Optional. Defaults to Chinese; returns English when set to "en".	EN	No	`string`
`fid`	Flight ID		No	`string`

Remark: lang is optional; defaults to Chinese when not provided.

Query mode 5: Query by Flight Number + Departure (Optional) + Arrival + Arrival Date

Parameter	Description	Example	Required	Type
`appid`	App ID		Yes	`string`
`token`	Token		Yes	`string`
`fnum`	Either "flight number" or "origin + destination" is required (choose one)	GX8915	No	`string`
`dep`	Either "flight number" or "origin + destination" is required (choose one)	HAK	No	`string`
`arr`	Either "flight number" or "origin + destination" is required (choose one)	YIH	No	`string`
`arrDate`	Arrival Date	2024-08-19	Yes	`string`
`lang`	Optional. Defaults to Chinese; returns English when set to "en".	EN	No	`string`
`fid`	Flight ID		No	`string`

Remark: lang is optional; defaults to Chinese when not provided.

Response fields:

Parameter	Description	Example	Type
`fcategory`	0: domestic=domestic; 1: domestic=international; 2: domestic=regional; 3: regional=international; 4: international=international; 5: unknown; = indicates the round trip	0	`string`
`ftype`	Aircraft Type Code	B738	`string`
`fservice`	J: passenger aircraft; F: cargo aircraft	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:50: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:42:12	`string`
`FlightDeptimeDate`	Actual Departure Time	2023-12-22 08:28:00	`string`
`FlightArrtimeDate`	Actual Arrival Time	2023-12-22 11:43:00	`string`
`FlightIngateTime`	On-Block Actual Time	2023-12-22 11:57:00	`string`
`FlightOutgateTime`	Off-Block Actual Time	2023-12-22 08:09: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`	check-in started, check-in ended, boarding started, final boarding call, boarding ended	check-in	`string`
`BoardGateTime`	0 = transport mode is walking; 1 = transport mode is airport train	1	`string`
`ArrStandGate`	Inbound Aircraft Stand	212	`string`
`DepStandGate`	Departure Aircraft Stand	309	`string`
`DelayReason`	This field may have a value only for delayed flights	ATC flow control restrictions	`string`
`Food`	B=breakfast; BR=brunch; C=alcohol(free); D=dinner; E=hospitality; F=food(buy); G=food&drink(buy); H=hot meal; K=continental breakfast; L=lunch; M=meal; O=cold meal; P=alcohol(buy); R=refreshments(free); S=snack/brunch; V=refreshments(buy); N=no meal	M	`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`
`VeryZhunReadyDeptimeDate`	VariFlight Estimated Departure Time	2023-12-22 08:29:00	`string`
`VeryZhunReadyArrtimeDate`	VariFlight Estimated Arrival Time	2023-12-22 11:43:18	`string`
`FlightState`	Scheduled, Delayed, Cancelled, Diverted, Returned, Departed, Arrived, Div-Departed, Div-Cancelled, Div-Arrived, Ret-Departed, Ret-Cancelled, Ret-Arrived, Cancelled Early, Circling, Circled, Climbing, Cruising, Descending, Arriving, Crashed, Lost Contact	schedule	`string`
`FlightStateNum`	Flight Status Value	1	`number`
`FlightHTerminal`	Departure Terminal	T1	`string`
`FlightTerminal`	Arrival Terminal	T1	`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`
`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`
`TodayTimeRate`	only present when the flight has not yet taken off		`string`
`OntimeRate`	Historical Departure 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`	Weather, visibility, wind force, PM2.5, temperature	Snow Shower to Cloudy\|\|\|89\|-4/-10	`string`
`ArrWeather`	Weather, visibility, wind force, PM2.5, temperature	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`
`ChangePlane`	0 = no aircraft change, 1 = aircraft change, -1 = unknown	0	`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`
`ArrAirportLat`	Arrival Airport Latitude	23.387861	`string`
`ArrAirportLon`	Arrival Airport Longitude	113.29734	`string`
`ArrTerminalLat`	Arrival Terminal Latitude	23.393169	`string`
`ArrTerminalLon`	Arrival Terminal Longitude	113.309858	`string`
`FlightDepAirport`	Departure Airport Name	Yantai Penglai	`string`
`FlightArrAirport`	Arrival Airport Name	Guangzhou Baiyun	`string`
`dst_timezone`	Destination Time Zone	28800	`string`
`org_timezone`	Departure Time Zone	28800	`string`
`StopAirportCode`	Stopover Airport IATA Code		`string`
`StopCity`	Stopover City		`string`
`StopFlag`	0 = nonstop; 1 = 1 stop; 2 = 2 stops; n = n stops	1	`string`
`ShareFlag`	0: not codeshare; 1: codeshare	1	`string`
`VirtualFlag`	0: non-virtual flight; 1: virtual flight; empty for future flights	0	`string`
`LegFlag`	0: scheduled leg; 1: leg generated by diversion; 2: leg generated by return	0	`string`
`ShareFlightNo`	Flight number of the actual operating flight		`string`
`FlightCancelTime`	Update time		`string`
`FillFlightNo`	This field may exist only for cancelled flights		`string`
`AlternateDeptime`	Diverted Actual Departure Time	2026-09-14 17:59:00	`string`
`alternate_info`	the following diversion fields are only returned for diverted flights		`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`	originally scheduled destination	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`
`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`
`ArrOnCargodoorTime`	Arrival Cargo Door Open Time		`string`
`ArrOffCargodoorTime`	Arrival Cargo Door Close Time		`string`
`DepOnCargodoorTime`	Takeoff Cargo Door Open Time		`string`
`DepOffCargodoorTime`	Departure Cargo Door Close Time		`string`
`depctry`	Departure Country Alpha-2 Code	CN	`string`
`arrctry`	Arrival Country Alpha-2 Code	CN	`string`
`depcontinent`	Departure Country Continent	亚洲	`string`
`depprov`	Departure Airport Province	新疆	`string`
`arrcontinent`	Arrival Country Continent	亚洲	`string`
`arrprov`	Arrival Airport Province	广东	`string`
`fid`	Only some customers have data for this field; the user passes it in the request parameters and it is returned as-is		`string`
`FillFlightInfo`	Data is returned only when a recovery flight exists.		`object`
`FlightNo`	Replacement Flight Number	9C668Q	`string`
`FlightDepcode`	Extra Flight Departure Airport IATA Code	URC	`string`
`FlightArrcode`	Replacement Flight Arrival Airport IATA Code	AAT	`string`
`FlightState`	Recovery Flight Status	schedule	`string`
`FlightDeptimePlanDate`	Replacement Flight Scheduled Departure Time	2025-11-14 12:30:00	`string`
`FlightArrtimePlanDate`	Extra Flight Scheduled Arrival Time	2025-11-14 13:40:00	`string`
`FlightDeptimeDate`	Replacement Flight Actual Departure Time	2025-11-14 12:30:00	`string`
`FlightArrtimeDate`	Replacement Flight Actual Departure Time	2025-11-14 13:40:00	`string`

Response examples:

Successful response:

[ {
  "fcategory" : "0",
  "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:50: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:42:12",
  "FlightDeptimeDate" : "2023-12-22 08:28:00",
  "FlightArrtimeDate" : "2023-12-22 11:43:00",
  "FlightIngateTime" : "2023-12-22 11:57:00",
  "FlightOutgateTime" : "2023-12-22 08:09:00",
  "CheckinTable" : "C",
  "CheckDoor" : "gate 4",
  "BoardGate" : "15",
  "ReachExit" : "W1",
  "BaggageID" : "7",
  "BoardState" : "check-in",
  "BoardGateTime" : "1",
  "ArrStandGate" : "212",
  "DepStandGate" : "309",
  "DelayReason" : "ATC flow control restrictions",
  "Food" : "M",
  "LastCheckinTime" : "2023-12-22 07:45:00",
  "EstimateBoardingStartTime" : "",
  "EstimateBoardingEndTime" : "",
  "VeryZhunReadyDeptimeDate" : "2023-12-22 08:29:00",
  "VeryZhunReadyArrtimeDate" : "2023-12-22 11:43:18",
  "FlightState" : "schedule",
  "FlightStateNum" : 1,
  "FlightHTerminal" : "T1",
  "FlightTerminal" : "T1",
  "FlightDep" : "Yantai",
  "FlightArr" : "Guangzhou",
  "deptel" : "0535-5134352",
  "arrtel" : "020-96158",
  "airlinetel" : "95369",
  "FlightWaitData" : 0,
  "bridge" : "not utilize aerobridge",
  "arr_bridge" : "utilize aerobridge",
  "TodayTimeRate" : "",
  "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",
  "ChangePlane" : "0",
  "AssistFlightState" : "arrival",
  "DepAirportLat" : "37.660556",
  "DepAirportLon" : "120.979167",
  "DepTerminalLat" : "37.664518",
  "DepTerminalLon" : "120.99807",
  "ArrAirportLat" : "23.387861",
  "ArrAirportLon" : "113.29734",
  "ArrTerminalLat" : "23.393169",
  "ArrTerminalLon" : "113.309858",
  "FlightDepAirport" : "Yantai Penglai",
  "FlightArrAirport" : "Guangzhou Baiyun",
  "dst_timezone" : "28800",
  "org_timezone" : "28800",
  "StopAirportCode" : "",
  "StopCity" : "",
  "StopFlag" : "1",
  "ShareFlag" : "1",
  "VirtualFlag" : "0",
  "LegFlag" : "0",
  "ShareFlightNo" : "",
  "FlightCancelTime" : "",
  "FillFlightNo" : "",
  "alternate_info" : [ {
    "AlternateDeptime" : "2026-09-14 17:59:00",
    "AlternateStatus" : "arrival",
    "AlternateDepCity" : "Guilin Liangjiang",
    "AlternateArrCity" : "Guangzhou Baiyun",
    "AlternateDepAirport" : "KWL",
    "AlternateArrAirport" : "CAN",
    "AlternateDeptimePlan" : "2026-09-14 16:32:00",
    "AlternateArrtimePlan" : "2026-09-14 17:02:00",
    "AlternateArrtime" : "2026-09-14 18:59:00",
    "AlternateDepTimezone" : "28800",
    "AlternateArrTimezone" : "28800"
  } ],
  "ArrOnCargodoorTime" : "",
  "ArrOffCargodoorTime" : "",
  "DepOnCargodoorTime" : "",
  "DepOffCargodoorTime" : "",
  "depctry" : "CN",
  "arrctry" : "CN",
  "depcontinent" : "亚洲",
  "depprov" : "新疆",
  "arrcontinent" : "亚洲",
  "arrprov" : "广东",
  "fid" : "",
  "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"
  }
} ]

Error response:

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

Response group 2

Query mode 1: Query by Airport IATA Code + Date + In/Outbound Flag

Parameter	Description	Example	Required	Type
`appid`	Application Identifier		Yes	`string`
`token`	API Token		Yes	`string`
`airport`	Airport IATA code	PEK	Yes	`string`
`status`	DEP: Departure; ARR: Arrival	DEP	No	`string`
`page`	Defaults to 1	1	No	`number`
`perpage`	Records per page. Default 20; capped at 100 if greater.	100	No	`number`
`date`	Flight Date	2024-09-28	Yes	`string`
`lang`	Optional. Defaults to Chinese; returns English when set to "en".	en	No	`string`
`fid`	Flight identifier		No	`string`

Query mode 2: Query by Airport IATA Code + Date + In/Outbound Flag + Time Range

Parameter	Description	Example	Required	Type
`appid`	Application Identifier		Yes	`string`
`token`	API Token		Yes	`string`
`airport`	PEK	PEK	Yes	`string`
`status`	DEP: Departure; ARR: Arrival	DEP	No	`string`
`page`	Defaults to 1	1	No	`number`
`perpage`	Default 20; capped at 100 if greater	100	No	`number`
`date`	Flight Date	2024-09-28	Yes	`string`
`startAt`	Period Start Time	09:00	Yes	`string`
`endAt`	Period End Time	16:00	Yes	`string`
`lang`	Sets the language for the response. Chinese is the default, use en for English	en	No	`string`
`fid`	Flight identifier		No	`string`

Query mode 3: Query by Departure Airport + Date + Arrival City

Parameter	Description	Example	Required	Type
`appid`	App ID		Yes	`string`
`token`	Token		Yes	`string`
`arrcity`	Arrival City IATA Code	BJS	Yes	`string`
`date`	Departure Date	2024-09-28	Yes	`string`
`dep`	Departure Airport IATA Code	SHA	Yes	`string`
`lang`	Optional. Defaults to Chinese; returns English when set to "en".	en	No	`string`
`page`	Defaults to 1	1	No	`number`
`perpage`	Default 20; capped at 100 if greater	100	No	`number`

Query mode 4: Query by Departure City + Date + Arrival Airport

Parameter	Description	Example	Required	Type
`appid`	App ID		Yes	`string`
`token`	Token		Yes	`string`
`arr`	Arrival Airport IATA Code	SHA	Yes	`string`
`date`	Departure Date	2024-09-28	Yes	`string`
`depcity`	Departure City IATA Code	BJS	Yes	`string`
`lang`	Optional. Defaults to Chinese; returns English when set to "en".	en	No	`string`
`page`	Defaults to 1	1	No	`number`
`perpage`	Default 20; capped at 100 if greater	100	No	`number`

Response fields:

Parameter	Description	Example	Type
`count`	Total data entries	1670	`number`
`totalpage`	Total number of pages	10	`number`
`page`	Page number	1	`number`
`perpage`	The number of data entries per page defaults to 20. When it exceeds 100, it defaults back to 100 (Optional parameter)	20	`number`
`data`	Returned Data		`array`
`ftype`	Aircraft Type Code	B738	`string`
`fservice`	J: passenger aircraft; F: cargo aircraft	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:50: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:42:12	`string`
`FlightDeptimeDate`	Actual Departure Time	2023-12-22 08:28:00	`string`
`FlightArrtimeDate`	Actual Arrival Time	2023-12-22 11:43:00	`string`
`FlightIngateTime`	On-Block Actual Time	2023-12-22 11:57:00	`string`
`FlightOutgateTime`	Off-Block Actual Time	2023-12-22 08:09: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`	check-in started, check-in ended, boarding started, final boarding call, boarding ended	check-in	`string`
`BoardGateTime`	0 = transport mode is walking; 1 = transport mode is airport train	1	`string`
`ArrStandGate`	Inbound Aircraft Stand	212	`string`
`DepStandGate`	Departure Aircraft Stand	309	`string`
`DelayReason`	This field may have a value only for delayed flights	ATC flow control restrictions	`string`
`Food`	B=breakfast; BR=brunch; C=alcohol(free); D=dinner; E=hospitality; F=food(buy); G=food&drink(buy); H=hot meal; K=continental breakfast; L=lunch; M=meal; O=cold meal; P=alcohol(buy); R=refreshments(free); S=snack/brunch; V=refreshments(buy); N=no meal	M	`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`
`VeryZhunReadyDeptimeDate`	VariFlight Estimated Departure Time	2023-12-22 08:29:00	`string`
`VeryZhunReadyArrtimeDate`	VariFlight Estimated Arrival Time	2023-12-22 11:43:18	`string`
`FlightState`	Types: Scheduled,Delayed,Cancelled,Diverted,Returned,Departed,Arrived,Div-Departed,Div-Cancelled,Div-Arrived,Ret-Departed,Ret-Cancelled,Ret-Arrived, Cancelled Early,Circling,Circled,Climbing,Cruising,Descending,Arriving,Crashed,Lost Contact	schedule	`string`
`FlightStateNum`	Flight Status Value	1	`number`
`FlightHTerminal`	Departure Terminal	T1	`string`
`FlightTerminal`	Arrival Terminal	T1	`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`
`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`
`TodayTimeRate`	only present when the flight has not yet taken off		`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`	Weather, visibility, wind force, PM2.5, temperature	Snow Shower to Cloudy\|\|\|89\|-4/-10	`string`
`ArrWeather`	Weather, visibility, wind force, PM2.5, temperature	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`
`ChangePlane`	0 = no aircraft change, 1 = aircraft change, -1 = unknown	0	`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`
`ArrAirportLat`	Arrival Airport Latitude	23.387861	`string`
`ArrAirportLon`	Arrival Airport Longitude	113.29734	`string`
`ArrTerminalLat`	Arrival Terminal Latitude	23.393169	`string`
`ArrTerminalLon`	Arrival Terminal Longitude	113.309858	`string`
`FlightDepAirport`	Departure Airport Name	Yantai Penglai	`string`
`FlightArrAirport`	Arrival Airport Name	Guangzhou Baiyun	`string`
`dst_timezone`	Destination Time Zone	28800	`string`
`org_timezone`	Departure Time Zone	28800	`string`
`StopAirportCode`	Stopover Airport IATA Code		`string`
`StopCity`	Stopover City		`string`
`StopFlag`	0 = nonstop; 1 = 1 stop; 2 = 2 stops; n = n stops	1	`string`
`ShareFlag`	0: not codeshare; 1: codeshare	1	`string`
`VirtualFlag`	0: non-virtual flight; 1: virtual flight; empty for future flights	0	`string`
`LegFlag`	0: scheduled leg; 1: leg generated by diversion; 2: leg generated by return	0	`string`
`ShareFlightNo`	Flight number of the actual operating flight		`string`
`FlightCancelTime`	Update time		`string`
`FillFlightNo`	This field may exist only for cancelled flights		`string`
`alternate_info`	the following diversion fields are only returned for diverted flights		`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`	originally scheduled destination	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`
`ArrOnCargodoorTime`	Arrival Cargo Door Open Time		`string`
`ArrOffCargodoorTime`	Arrival Cargo Door Close Time		`string`
`DepOnCargodoorTime`	Takeoff Cargo Door Open Time		`string`
`DepOffCargodoorTime`	Departure Cargo Door Close Time		`string`
`depctry`	Departure Country Alpha-2 Code	CN	`string`
`arrctry`	Arrival Country Alpha-2 Code	CN	`string`
`depcontinent`	Departure Country Continent	亚洲	`string`
`depprov`	Departure Airport Province	新疆	`string`
`arrcontinent`	Arrival Country Continent	亚洲	`string`
`arrprov`	Arrival Airport Province	广东	`string`
`fcategory`	0: domestic=domestic; 1: domestic=international; 2: domestic=regional; 3: regional=international; 4: international=international; 5: unknown; = indicates the round trip	0	`string`
`fid`	Flight identifier		`string`
`FillFlightInfo`	the recovery flight info group may only have a value for cancelled flights.		`object`
`FlightNo`	Replacement Flight Number	9C668Q	`string`
`FlightDepcode`	Extra Flight Departure Airport IATA Code	URC	`string`
`FlightArrcode`	Replacement Flight Arrival Airport IATA Code	AAT	`string`
`FlightState`	Recovery Flight Status	schedule	`string`
`FlightDeptimePlanDate`	Extra Flight Scheduled Takeoff Time	2025-11-14 12:30:00	`string`
`FlightArrtimePlanDate`	Extra Flight Scheduled Arrival Time	2025-11-14 13:40:00	`string`
`FlightDeptimeDate`	Replacement Flight Actual Departure Time	2025-11-14 12:30:00	`string`
`FlightArrtimeDate`	Recovery Flight Actual Arrival Time	2025-11-14 13:40:00	`string`

Response examples:

Successful response:

{
  "count" : 1670,
  "totalpage" : 10,
  "page" : 1,
  "perpage" : 20,
  "data" : [ {
    "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:50: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:42:12",
    "FlightDeptimeDate" : "2023-12-22 08:28:00",
    "FlightArrtimeDate" : "2023-12-22 11:43:00",
    "FlightIngateTime" : "2023-12-22 11:57:00",
    "FlightOutgateTime" : "2023-12-22 08:09:00",
    "CheckinTable" : "C",
    "CheckDoor" : "gate 4",
    "BoardGate" : "15",
    "ReachExit" : "W1",
    "BaggageID" : "7",
    "BoardState" : "check-in",
    "BoardGateTime" : "1",
    "ArrStandGate" : "212",
    "DepStandGate" : "309",
    "DelayReason" : "ATC flow control restrictions",
    "Food" : "M",
    "LastCheckinTime" : "2023-12-22 07:45:00",
    "EstimateBoardingStartTime" : "",
    "EstimateBoardingEndTime" : "",
    "VeryZhunReadyDeptimeDate" : "2023-12-22 08:29:00",
    "VeryZhunReadyArrtimeDate" : "2023-12-22 11:43:18",
    "FlightState" : "schedule",
    "FlightStateNum" : 1,
    "FlightHTerminal" : "T1",
    "FlightTerminal" : "T1",
    "FlightDep" : "Yantai",
    "FlightArr" : "Guangzhou",
    "deptel" : "0535-5134352",
    "arrtel" : "020-96158",
    "airlinetel" : "95369",
    "FlightWaitData" : 0,
    "bridge" : "not utilize aerobridge",
    "arr_bridge" : "utilize aerobridge",
    "TodayTimeRate" : "",
    "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",
    "ChangePlane" : "0",
    "AssistFlightState" : "arrival",
    "DepAirportLat" : "37.660556",
    "DepAirportLon" : "120.979167",
    "DepTerminalLat" : "37.664518",
    "DepTerminalLon" : "120.99807",
    "ArrAirportLat" : "23.387861",
    "ArrAirportLon" : "113.29734",
    "ArrTerminalLat" : "23.393169",
    "ArrTerminalLon" : "113.309858",
    "FlightDepAirport" : "Yantai Penglai",
    "FlightArrAirport" : "Guangzhou Baiyun",
    "dst_timezone" : "28800",
    "org_timezone" : "28800",
    "StopAirportCode" : "",
    "StopCity" : "",
    "StopFlag" : "1",
    "ShareFlag" : "1",
    "VirtualFlag" : "0",
    "LegFlag" : "0",
    "ShareFlightNo" : "",
    "FlightCancelTime" : "",
    "FillFlightNo" : "",
    "alternate_info" : [ {
      "AlternateStatus" : "arrival",
      "AlternateDepCity" : "Guilin Liangjiang",
      "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"
    } ],
    "ArrOnCargodoorTime" : "",
    "ArrOffCargodoorTime" : "",
    "DepOnCargodoorTime" : "",
    "DepOffCargodoorTime" : "",
    "depctry" : "CN",
    "arrctry" : "CN",
    "depcontinent" : "亚洲",
    "depprov" : "新疆",
    "arrcontinent" : "亚洲",
    "arrprov" : "广东",
    "fcategory" : "0",
    "fid" : "",
    "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"
    }
  } ]
}

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. missing `appid`, invalid `token`, or invalid flight number / date / origin / destination format)
`4`	No data permission (interface not enabled, disabled or expired, or invalid request method)
`10`	No data available (including the case where all records are filtered out by data permissions)
`500`	Unknown error (internal server error)

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

Supplementary Notes

• Airport departure/arrival (full-listing) queries are paginated by default: page starts at 1; perpage defaults to 20 and is capped at 1000 (larger values are treated as 1000). Responses contain count, totalpage, page, perpage and data (the array of records); a page beyond totalpage returns error_code = 10.
• Flight numbers are normalized automatically: leading zeros after the airline code are stripped (e.g. CA0123 → CA123); 3-letter airline codes are converted to 2-letter IATA codes; 4-letter ICAO airport codes in dep/arr are converted to 3-letter IATA codes.
• fid is a caller-defined identifier; when provided, it is echoed back verbatim in the response.
• Pass lang=EN for English responses.