貿易涵蓋範圍路由 API 參考
讀取各國的貿易路由由哪個來源提供資料、收錄了什麼,以及收錄的起訖月份。
概覽
GET /
GET / 為每個國家回傳一列資料:由誰提供夥伴國路由與產品路由的資料、目前提供資料的來源、所有已收錄的來源,以及已收錄的月份。它是「貿易國家」頁面概括回答之問題的即時答案。
在以某國為基礎進行開發之前,請先呼叫它。answers_ 是目前未帶 basis 的請求所採用的來源,tiers_ 列出所有有資料列的 basis 值。傳入 country 可取得單一列,省略則取得所有國家。此呼叫免費。MCP 工具為 trade_,參數相同。
請求
英國的涵蓋範圍,以及實際回應:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/coverage?country=GBR"{
"countries": [
{
"country": "GBR",
"partners_tier": "own",
"partner_coverage": "all",
"products_tier": "own",
"answers_with": "own",
"tiers_held": [
"own",
"partner_reported"
],
"first_period": "2010-01",
"latest_period": "2026-09",
"comtrade_latest_period": "2026-08",
"third_party_latest_period": null,
"comtrade_periods": 200,
"comtrade_latest_year": 2025,
"has_headline": true,
"has_services": true,
"has_tariff_book": true
}
]
}英國的自有機構提供資料(answers_ 為 own)並收錄產品(products_ 為 own)。first_ 與 latest_ 是來自該機構的已收錄月份。
參數
| 參數 | 位置 | 類型 | 必填 | 預設值 | 允許值與意義 |
|---|---|---|---|---|---|
country | query | 字串 | 否 | 所有國家 | 一個 ISO 3166-1 alpha-3 代碼(大寫),或以 EMU 代表歐元區。省略時,回應為每個國家各一列。不是國家的代碼會回傳 400,沒有資料列的國家會回傳 404。 |
回應
回應只有一個欄位 countries,為清單。每一項包含下列欄位。
| 欄位 | 含義 |
|---|---|
country | 國家,或以 EMU 代表歐元區。 |
partners_ | 依 Narwhal 直接收錄的資料,由誰提供夥伴國路由的資料:own,即該國自有的海關或統計機構;或 partner_,即對調流向的其他國家申報,適用於 Narwhal 沒有該國自有機構數字的情況。 |
partner_ | 列出所有夥伴國時為 all;發布機構僅列示其主要夥伴國與一列其餘合計時為 top_。partners_ 為 partner_ 時為 null。 |
products_ | 由誰提供產品路由的資料:own;或在該國沒有自有產品檔案時為 partner_。UN Comtrade 僅有夥伴國總額,因此從不提供產品資料。 |
answers_ | 目前夥伴國與產品路由所採用的來源,依此順序:該國自有機構(own)、其向 UN Comtrade 提交的申報(third_)、其他國家的申報(partner_,絕非官方數字)。其他國家的申報,只有在至少 200 個申報國有關於該國的資料列時,才會排在 UN Comtrade 之前,這超過 Narwhal 所收錄的數量,因此它們排在最後。依章查詢時,UN Comtrade 沒有任何資料,因此由 partner_ 提供資料。Narwhal 沒有該國任何資料時為 null。 |
tiers_ | 目前有資料列的所有來源:可為此國家提供資料的 basis 值。 |
first_ | Narwhal 從該國自有機構收錄的第一個月份。沒有時為 null。 |
latest_ | Narwhal 從該國自有機構收錄的最新月份。沒有時為 null。 |
comtrade_ | 該國向 UN Comtrade 申報的最新月份。沒有時為 null。 |
third_ | Narwhal 從 UN Comtrade 為該國收錄的最新月份。沒有時為 null。 |
comtrade_ | 該國向 UN Comtrade 申報的月份數。 |
comtrade_ | 該國向 UN Comtrade 申報的最新年份。 |
has_ | 該國發布貨物貿易的月度總額時為 true。 |
has_ | 該國發布服務貿易時為 true。 |
has_ | 有國家關稅稅則可用時為 true。 |
更多範例
自有機構僅提供夥伴國總額的國家
加拿大,其自有機構僅提供夥伴國總額:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/coverage?country=CAN"{
"countries": [
{
"country": "CAN",
"partners_tier": "own",
"partner_coverage": "top_n",
"products_tier": "partner_reported",
"answers_with": "own",
"tiers_held": [
"own",
"partner_reported"
],
"first_period": "2010-01",
"latest_period": "2026-09",
"comtrade_latest_period": "2026-08",
"third_party_latest_period": null,
"comtrade_periods": 200,
"comtrade_latest_year": 2025,
"has_headline": true,
"has_services": true,
"has_tariff_book": true
}
]
}partners_ 為 own,products_ 為 partner_:加拿大的夥伴國資料來自加拿大統計局,依章劃分的產品資料則來自其他國家的申報。
未涵蓋的國家
真實存在但沒有數字的國家代碼會回傳 404,且免費:
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/trade/coverage?country=ATA"{
"type": "https://narwhalapi.com/problems/country-not-covered",
"title": "Country not covered",
"status": 404,
"detail": "ATA is not in the trade coverage list.",
"code": "country_not_covered",
"request_id": "c16523b6-7d27-4e1b-a2c3-f7e2acead523"
}來源
此路由回報各來源,不會選擇其一。各來源是什麼、何時提供資料,請見「貿易國家」頁面。
貨幣
此路由不回傳金額,因此不適用貨幣。
分頁
此路由沒有分頁。未帶 country 的請求會在一個回應中回傳所有國家。
價格
此路由免費。不收取任何呼叫費用,但帳戶仍需要金鑰。
錯誤
這些錯誤使用共用的問題格式,並附有 request_。缺少或無效的金鑰(401)、餘額低於該次呼叫的價格(402)以及每分鐘請求過多(429),是所有路由共有的帳戶錯誤:請見「錯誤與額度」。
| 狀態 | 代碼 | 發生時機 |
|---|---|---|
400 | invalid_query | country 不是國家代碼。 |
404 | country_not_covered | Narwhal 在任何來源中都沒有該國的貿易資料列。 |
此頁面對你有幫助嗎?