domestic-flight-schedule
China Domestic Flight Schedule API
Filter China domestic flight schedules by city, airline or flight number and read planned times and reference operating days.
Usage Cost
15 coins/call
Quick Start
Use a unified response envelope and call directly from your backend.
https://openapi.toolkk.com/v1/domestic-flight-schedulecURL Example
curl --request GET \
--url 'https://openapi.toolkk.com/v1/domestic-flight-schedule' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{\n "START_CITY": "北京",\n "END_CITY": "上海",\n "PAGE_NUM": "1"\n}'Python Example
import os
import requests
url = "https://openapi.toolkk.com/v1/domestic-flight-schedule"
payload = {
"START_CITY": "北京",
"END_CITY": "上海",
"PAGE_NUM": "1"
}
headers = {
"Content-Type": "application/json",
"X-API-Key": os.getenv("TOOLKK_API_KEY", "YOUR_API_KEY"),
}
response = requests.get(url, headers=headers, params=payload, timeout=30)
response.raise_for_status()
print(response.json())Go Example
package main
import (
"bytes"
"fmt"
"io"
"net/http"
)
func main() {
endpoint := "https://openapi.toolkk.com/v1/domestic-flight-schedule"
payload := []byte("{\n \"START_CITY\": \"北京\",\n \"END_CITY\": \"上海\",\n \"PAGE_NUM\": \"1\"\n}")
req, err := http.NewRequest("GET", endpoint, bytes.NewBuffer(payload))
if err != nil {
panic(err)
}
req.Header.Set("Content-Type", "application/json")
req.Header.Set("X-API-Key", "YOUR_API_KEY")
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, err := io.ReadAll(resp.Body)
if err != nil {
panic(err)
}
fmt.Println(string(body))
}Java Example
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
public class ToolkkExample {
public static void main(String[] args) throws Exception {
String payload = "{\n \"START_CITY\": \"北京\",\n \"END_CITY\": \"上海\",\n \"PAGE_NUM\": \"1\"\n}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://openapi.toolkk.com/v1/domestic-flight-schedule"))
.method("GET", HttpRequest.BodyPublishers.ofString(payload))
.header("Content-Type", "application/json")
.header("X-API-Key", "YOUR_API_KEY")
.build();
HttpResponse<String> response = HttpClient.newHttpClient()
.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
}
}PHP Example
<?php
$endpoint = 'https://openapi.toolkk.com/v1/domestic-flight-schedule';
$payload = "{\n \"START_CITY\": \"北京\",\n \"END_CITY\": \"上海\",\n \"PAGE_NUM\": \"1\"\n}";
$ch = curl_init($endpoint);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'GET',
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-API-Key: YOUR_API_KEY',
],
CURLOPT_POSTFIELDS => $payload,
]);
$response = curl_exec($ch);
if ($response === false) {
throw new RuntimeException(curl_error($ch));
}
curl_close($ch);
echo $response;Response Example
{
"索引条件": {
"索引字符串": "北京_海南航空"
},
"索引状态": "一切都如您的神机妙算,天下均在您的掌握之中",
"索引总数量": "64",
"索引总页数": "2",
"索引页容量": "25",
"索引页序号": "1",
"索引实体信息": [
{
"出发城市": "北京",
"抵达城市": "广州",
"航班号": "HU7719",
"航空公司": "海南航空",
"机型": "",
"开始时间": "17:55",
"结束时间": "20:20",
"起飞机场": "广州白云国际机场T1",
"抵达机场": "郑州新郑国际机场T2",
"本周参考航班": "一,三,五,日",
"准点率": "95%",
"数据编码": "089EB9712FDF9F7F2AF34056B05A21BB"
}
]
}Examples illustrate the response structure. Actual results depend on the API response.
- Authentication
- Send X-API-Key in request headers
- Rate limit
- 60 req/min
- Timeout
- 30000 ms
Send your API Key in the X-API-Key header from your backend.
Check both HTTP status and business fields before treating a call as successful.
Use retries and backoff together with rate limits in high-frequency scenarios.
Request Fields
Send requests from your server with the key in the X-API-Key header.
Request Fields
Fields are read from the API schema. Missing descriptions and examples are marked as unspecified.
| Path | Type | Required | Description | Sample |
|---|---|---|---|---|
| START_CITY | string | No | 出发城市,如:北京 | 北京 |
| END_CITY | string | No | 抵达城市,如:上海 | 上海 |
| AIRLINE_COMPANY | string | No | 航空公司,如:海南航空 | 海南航空 |
| PLANE_ID | string | No | 航班号,如:CA1104 | CA1104 |
| PAGE_NUM | string | Yes | 搜索结果页码序列,如:1 | 1 |
Request Example
{
"START_CITY": "北京",
"END_CITY": "上海",
"PAGE_NUM": "1"
}- Authentication
- Send X-API-Key in request headers
- Rate limit
- 60 req/min
- Timeout
- 30000 ms
Response Fields
Examples illustrate the response structure. Actual results depend on the API response.
Response Fields
Fields are read from the API schema. Missing descriptions and examples are marked as unspecified.
| Path | Type | Required | Description | Sample |
|---|---|---|---|---|
| 索引条件 | object | No | Unspecified | Unspecified |
| 索引条件.索引字符串 | string | No | Unspecified | 北京_海南航空 |
| 索引状态 | string | No | Unspecified | 一切都如您的神机妙算,天下均在您的掌握之中 |
| 索引总数量 | string | No | Unspecified | 64 |
| 索引总页数 | string | No | Unspecified | 2 |
| 索引页容量 | string | No | Unspecified | 25 |
| 索引页序号 | string | No | Unspecified | 1 |
| 索引实体信息 | array | No | Unspecified | Unspecified |
| 索引实体信息[] | object | Unspecified | Unspecified | Unspecified |
| 索引实体信息[].出发城市 | string | No | Unspecified | 北京 |
| 索引实体信息[].抵达城市 | string | No | Unspecified | 广州 |
| 索引实体信息[].航班号 | string | No | Unspecified | HU7719 |
| 索引实体信息[].航空公司 | string | No | Unspecified | 海南航空 |
| 索引实体信息[].机型 | string | No | Unspecified | Unspecified |
API overview
Capabilities, use cases, limitations, and frequently asked questions.
What the API provides
Find China domestic flight schedule records using departure city, arrival city, airline or flight number. Results include route details, airline, aircraft, planned departure and arrival times, reference operating days and on-time rate, together with pagination statistics. Use these records to build a shortlist for a journey.
Where to use it
Travel applications can present route options, while corporate travel tools can compare planned departure times. A pickup service can identify flight numbers before checking their status for a specific date. Sorting, deduplication, itinerary matching and notifications remain application responsibilities.
Calling and interpreting results
Send query parameters to the GET endpoint shown in the request tab. PAGE_NUM starts at 1. City, airline and flight-number filters are optional; supplied filters apply together. Start with a city pair before adding narrower conditions. Check the business response code, then read the record list and pagination values. Numeric statistics may arrive as strings and need validation before arithmetic.
Scope and limitations
There is no date input, so a schedule record does not establish that a flight will operate on a particular day. Planned times, operating days and on-time rates are references. Confirm changes with the airline or airport. NO_RESULTS means the supplied filters found no matching records; it does not establish that a route has been discontinued.
Frequently asked questions
Why did adding filters remove every result?
Filters apply together. Check that the airline matches the flight number, or retry with just the city pair and page number.