flight-list-query
China Domestic Flight List and Reference Fare API
Find China domestic candidate flights by cities and date, with airports, planned times and reference lowest fares.
Usage Cost
15 coins/call
Quick Start
Use a unified response envelope and call directly from your backend.
https://openapi.toolkk.com/v1/flight-list-querycURL Example
curl --request GET \
--url 'https://openapi.toolkk.com/v1/flight-list-query' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{\n "START_CITY": "北京",\n "START_DATE": "20261009",\n "END_CITY": "上海",\n "END_DATE": "20261009"\n}'Python Example
import os
import requests
url = "https://openapi.toolkk.com/v1/flight-list-query"
payload = {
"START_CITY": "北京",
"START_DATE": "20261009",
"END_CITY": "上海",
"END_DATE": "20261009"
}
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/flight-list-query"
payload := []byte("{\n \"START_CITY\": \"北京\",\n \"START_DATE\": \"20261009\",\n \"END_CITY\": \"上海\",\n \"END_DATE\": \"20261009\"\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 \"START_DATE\": \"20261009\",\n \"END_CITY\": \"上海\",\n \"END_DATE\": \"20261009\"\n}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://openapi.toolkk.com/v1/flight-list-query"))
.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/flight-list-query';
$payload = "{\n \"START_CITY\": \"北京\",\n \"START_DATE\": \"20261009\",\n \"END_CITY\": \"上海\",\n \"END_DATE\": \"20261009\"\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
{
"START_CITY": "北京",
"START_DATE": "20190202",
"END_CITY": "上海",
"END_DATE": "20190202",
"FLIGHTS": [
{
"START_AIRPORT_CH": "南苑机场",
"START_AIRPORT_EN": "NAY",
"START_TERMINAL_EN": "",
"START_DATE": "20190202",
"START_TIME": "21:00",
"END_AIRPORT_CH": "浦东机场",
"END_AIRPORT_EN": "PVG",
"END_TERMINAL_EN": "T1",
"END_DATE": "20190202",
"END_TIME": "23:25",
"FLIGHT_AIR_TIME": "浦东机场",
"FLIGHT_AIR_IS_MORROW": "0",
"FLIGHT_ID": "KN5987",
"FLIGHT_PLANE_STYLE": "73V",
"FLIGHT_PLANE_CN": "中型机",
"FLIGHT_PLANE_TYPE": "2",
"FLIGHT_AIRWAYS_EN": "KN",
"FLIGHT_AIRWAYS_CH": "联合航空",
"FLIGHT_LOWEST_PRICE": 342
}
]
}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 | Yes | 出发城市,如:北京 | 北京 |
| START_DATE | string | Yes | 出发日期,如:20190208 | 20261009 |
| END_CITY | string | Yes | 抵达城市,如:上海 | 上海 |
| END_DATE | string | No | 返程日期,如:20190208,若无返回日期,则填写出发日期 | 20261009 |
Request Example
{
"START_CITY": "北京",
"START_DATE": "20261009",
"END_CITY": "上海",
"END_DATE": "20261009"
}- 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 |
|---|---|---|---|---|
| START_CITY | string | No | Unspecified | 北京 |
| START_DATE | string | No | Unspecified | 20190202 |
| END_CITY | string | No | Unspecified | 上海 |
| END_DATE | string | No | Unspecified | 20190202 |
| FLIGHTS | array | No | Unspecified | Unspecified |
| FLIGHTS[] | object | Unspecified | Unspecified | Unspecified |
| FLIGHTS[].START_AIRPORT_CH | string | No | Unspecified | 南苑机场 |
| FLIGHTS[].START_AIRPORT_EN | string | No | Unspecified | NAY |
| FLIGHTS[].START_TERMINAL_EN | string | No | Unspecified | Unspecified |
| FLIGHTS[].START_DATE | string | No | Unspecified | 20190202 |
| FLIGHTS[].START_TIME | string | No | Unspecified | 21:00 |
| FLIGHTS[].END_AIRPORT_CH | string | No | Unspecified | 浦东机场 |
| FLIGHTS[].END_AIRPORT_EN | string | No | Unspecified |
API overview
Capabilities, use cases, limitations, and frequently asked questions.
What the API provides
Query China domestic flight candidates using departure city, arrival city and date. Flight records can include flight number, airline, airports, terminals, aircraft, planned departure and arrival dates and times, and a reference lowest fare. Use the list for an initial comparison of travel options.
Where to use it
Travel applications can build candidate cards, corporate travel tools can shortlist flights by planned time and reference price, and support pages can show route details. Sorting, itinerary matching, currency and tax explanations, and links to a booking channel are application responsibilities. Treat the results as planning information.
Calling and interpreting results
Send START_CITY, END_CITY and START_DATE as GET query parameters; END_DATE is optional. Dates use an eight-digit year, month and day. Check the business response code, then read FLIGHTS. Use each record’s departure and arrival dates together with its times to display overnight journeys. Returned city and date fields help check the query context.
Scope and limitations
FLIGHT_LOWEST_PRICE is a reference lowest fare, not confirmed seat availability, a tax-inclusive total or a guaranteed checkout price. A missing price is not a free ticket. This endpoint does not create orders, take payment, issue tickets, manage changes or provide operational flight status. Reconfirm prices and schedules with the airline or sales channel before booking and travel.