flight-query
Flight Information & Fare Lookup
Search a route and departure date for flight times, provider status, aircraft, terminals and adult, child or infant reference fares.
Usage Cost
25 coins/call
Quick Start
Use a unified response envelope and call directly from your backend.
https://openapi.toolkk.com/v1/flight-querycURL Example
curl --request GET \
--url 'https://openapi.toolkk.com/v1/flight-query' \
--header 'Content-Type: application/json' \
--header 'X-API-Key: YOUR_API_KEY' \
--data '{\n "departure": "HGH",\n "arrival": "WUH",\n "departureDate": "2026-09-30"\n}'Python Example
import os
import requests
url = "https://openapi.toolkk.com/v1/flight-query"
payload = {
"departure": "HGH",
"arrival": "WUH",
"departureDate": "2026-09-30"
}
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-query"
payload := []byte("{\n \"departure\": \"HGH\",\n \"arrival\": \"WUH\",\n \"departureDate\": \"2026-09-30\"\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 \"departure\": \"HGH\",\n \"arrival\": \"WUH\",\n \"departureDate\": \"2026-09-30\"\n}";
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://openapi.toolkk.com/v1/flight-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-query';
$payload = "{\n \"departure\": \"HGH\",\n \"arrival\": \"WUH\",\n \"departureDate\": \"2026-09-30\"\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
{
"success": true,
"code": "200",
"message": "成功",
"data": {
"list": [
{
"arrivalCityCode": "WUH",
"duration": "1小时40分",
"departureCityCode": "HGH",
"price": {
"discountRate": 0.74,
"adultPrice": "670.00",
"childPrice": "460.00",
"infantPrice": "无"
},
"airlineCode": "GJ",
"departureDateTime": "2026-06-30 20:40:00",
"arrivalDateTime": "2026-06-30 22:20:00",
"state": "航班计划",
"departureAirportCode": "HGH",
"aircraftName": "波音737(中)",
"departureTerminal": "T4",
"arrivalAirportCode": "WUH",
"flightType": "direct",
"flightNo": "GJ3072",
"departureCityName": "杭州",
"arrivalCityName": "武汉",
"aircraftCode": "73H",
"departureAirportName": "萧山国际机场",
"airlineName": "长龙航空",
"arrivalAirportName": "天河国际机场",
"segments": []
}
]
}
}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 |
|---|---|---|---|---|
| departure | string | Yes | 出发城市或机场三字码 | HGH |
| arrival | string | Yes | 到达城市或机场三字码 | WUH |
| departureDate | string | No | 选填;省略时使用服务商当天日期 | 2026-09-30 |
Request Example
{
"departure": "HGH",
"arrival": "WUH",
"departureDate": "2026-09-30"
}- 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 |
|---|---|---|---|---|
| success | boolean | No | Unspecified | true |
| code | string | No | Unspecified | 200 |
| message | string | No | Unspecified | 成功 |
| data | object | No | Unspecified | Unspecified |
| data.list | array | No | Unspecified | [{"arrivalCityCode":"WUH","duration":"1小时40分","departureCityCode":"HGH","price":{"discountRate":0.74,"adultPrice":"670.00","childPrice":"460.00","infantPrice":"无"},"airlineCode":"GJ","departureDateTime":"2026-06-30 20:40:00","arrivalDateTime":"2026-06-30 22:20:00","state":"航班计划","departureAirportCode":"HGH","aircraftName":"波音737(中)","departureTerminal":"T4","arrivalAirportCode":"WUH","flightType":"direct","flightNo":"GJ3072","departureCityName":"杭州","arrivalCityName":"武汉","aircraftCode":"73H","departureAirportName":"萧山国际机场","airlineName":"长龙航空","arrivalAirportName":"天河国际机场","segments":[]}] |
| data.list[] | object | Unspecified | Unspecified | Unspecified |
Response Example
{
"success": true,
"code": "200",
"message": "成功",
"data": {
"list": [
{
"arrivalCityCode": "WUH",
"duration": "1小时40分",
"departureCityCode": "HGH",
"price": {
"discountRate": 0.74,
"adultPrice": "670.00",
"childPrice": "460.00",
"infantPrice": "无"
},
"airlineCode": "GJ",
"departureDateTime": "2026-06-30 20:40:00",
"arrivalDateTime": "2026-06-30 22:20:00",
"state": "航班计划",
"departureAirportCode": "HGH",
"aircraftName": "波音737(中)",
"departureTerminal": "T4",
"arrivalAirportCode": "WUH",
"flightType": "direct",
"flightNo": "GJ3072",
"departureCityName": "杭州",
"arrivalCityName": "武汉",
"aircraftCode": "73H",
"departureAirportName": "萧山国际机场",
"airlineName": "长龙航空",
"arrivalAirportName": "天河国际机场",
"segments": []
}
]
}
}API overview
Capabilities, use cases, limitations, and frequently asked questions.
Flight Information & Fare Lookup
Search a route and departure date for flight times, provider status, aircraft, terminals and adult, child or infant reference fares.
GET /v1/flight-query
Request parameters
| Parameter | Type | Description |
|---|---|---|
| departure | string | Required: departure city or airport code, e.g. HGH or BJS |
| arrival | string | Required: arrival city or airport code, e.g. WUH |
| departureDate | string | Optional: YYYY-MM-DD; omitted means the provider's current date |
Response data
Successful responses contain a flight array at data.list. Fields include flightNo, airlineCode/airlineName, , airport codes and names, , raw provider , , , and supplied .