呼叫價格
15 匠幣/次
快速接入
保持統一返回結構,直接透過服務端發起請求即可接入。
https://openapi.toolkk.com/v1/flight-list-querycURL 示例
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 示例
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 示例
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 示例
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 示例
<?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;響應示例
{
"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
}
]
}範例用於理解回傳結構,實際結果以介面回傳為準。
- 鑑權方式
- 請求頭傳入 X-API-Key
- 預設限流
- 60 次/分鐘
- 超時時間
- 30000 ms
服務端呼叫時,將 API Key 放在 X-API-Key 請求頭中。
建議按 response code 與業務欄位雙重判斷呼叫結果。
高頻呼叫場景請結合速率限制與重試策略使用。
請求欄位
從伺服器發起請求,並在 X-API-Key 標頭中傳入金鑰。
請求欄位
欄位來自介面結構定義。未提供的說明和範例會標為未標註。
| 欄位路徑 | 型別 | 必填 | 說明 | 示例值 |
|---|---|---|---|---|
| START_CITY | string | 是 | 出发城市,如:北京 | 北京 |
| START_DATE | string | 是 | 出发日期,如:20190208 | 20261009 |
| END_CITY | string | 是 | 抵达城市,如:上海 | 上海 |
| END_DATE | string | 否 | 返程日期,如:20190208,若无返回日期,则填写出发日期 | 20261009 |
請求示例
{
"START_CITY": "北京",
"START_DATE": "20261009",
"END_CITY": "上海",
"END_DATE": "20261009"
}- 鑑權方式
- 請求頭傳入 X-API-Key
- 預設限流
- 60 次/分鐘
- 超時時間
- 30000 ms
響應欄位
範例用於理解回傳結構,實際結果以介面回傳為準。
響應欄位
欄位來自介面結構定義。未提供的說明和範例會標為未標註。
| 欄位路徑 | 型別 | 必填 | 說明 | 示例值 |
|---|---|---|---|---|
| START_CITY | string | 否 | 未標註 | 北京 |
| START_DATE | string | 否 | 未標註 | 20190202 |
| END_CITY | string | 否 | 未標註 | 上海 |
| END_DATE | string | 否 | 未標註 | 20190202 |
| FLIGHTS | array | 否 | 未標註 | 未標註 |
| FLIGHTS[] | object | 未標註 | 未標註 | 未標註 |
| FLIGHTS[].START_AIRPORT_CH | string | 否 | 未標註 | 南苑机场 |
| FLIGHTS[].START_AIRPORT_EN | string | 否 | 未標註 | NAY |
| FLIGHTS[].START_TERMINAL_EN | string | 否 | 未標註 | 未標註 |
| FLIGHTS[].START_DATE | string | 否 | 未標註 | 20190202 |
| FLIGHTS[].START_TIME | string | 否 | 未標註 | 21:00 |
| FLIGHTS[].END_AIRPORT_CH | string | 否 | 未標註 | 浦东机场 |
| FLIGHTS[].END_AIRPORT_EN | string | 否 | 未標註 | PVG |
| FLIGHTS[].END_TERMINAL_EN | string | 否 | 未標註 | T1 |
| FLIGHTS[].END_DATE | string | 否 |
介面簡介
介面功能、應用情境、使用限制與常見問題。
介面功能
依出發城市、抵達城市與日期查詢中國國內航班清單。每筆航班可提供航班號、航空公司、機場、航廈、機型、計畫起降日期與時間,以及參考最低票價。結果適合呈現城市間出行的候選航班,讓使用者先比較時間安排及價格線索。
使用情境
旅遊工具可產生候選航班卡片;企業差旅服務可依計畫時間及參考價格作初步篩選;客服頁面可展示航線資料。價格排序、幣別或稅費說明、行程配對及連接購票入口由呼叫端處理,不能把回傳清單直接視為已確認可售的座位庫存。
呼叫與解讀
以 GET 查詢參數提供 START_CITY、END_CITY 與 START_DATE,END_DATE 為選填。日期採八位年月日,完整規則以請求分頁為準。確認業務回傳碼後讀取 FLIGHTS 陣列,搭配每筆起降日期與時間顯示跨日航程;回傳的城市與日期可用來核對查詢條件。
範圍與限制
FLIGHT_LOWEST_PRICE 僅為參考最低票價,不代表目前可售艙位、含稅總價或最後成交金額;缺少價格不等於免費。此介面不提供訂單、付款、開票、退改票或即時運航狀態查詢。價格與計畫時間可能變動,購票及出行前須向航空公司或銷售通路確認。
常見問題
能按最低票價直接訂票嗎?
不能。這個數值只適合初步比較,售價、稅費及退改條件須在購票通路再次確認。
不同起降日期代表來回票嗎?
不能如此認定。日期用來解讀各筆航班,介面沒有建立來回訂單或組合行程的功能。
為何沒有 FLIGHTS_STATUS?
Product 已移除該查詢標記,避免來源宣傳文字進入業務回應;航班清單仍保留。