瀏覽全部文件

貿易涵蓋範圍路由 API 參考

讀取各國的貿易路由由哪個來源提供資料、收錄了什麼,以及收錄的起訖月份。

概覽

GET /v1/trade/coverage

GET /v1/trade/coverage 為每個國家回傳一列資料:由誰提供夥伴國路由與產品路由的資料、目前提供資料的來源、所有已收錄的來源,以及已收錄的月份。它是「貿易國家」頁面概括回答之問題的即時答案。

在以某國為基礎進行開發之前,請先呼叫它。answers_with 是目前未帶 basis 的請求所採用的來源,tiers_held 列出所有有資料列的 basis 值。傳入 country 可取得單一列,省略則取得所有國家。此呼叫免費。MCP 工具為 trade_get_coverage,參數相同。

請求

英國的涵蓋範圍,以及實際回應:

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_with 為 own)並收錄產品(products_tier 為 own)。first_period 與 latest_period 是來自該機構的已收錄月份。

參數

參數位置類型必填預設值允許值與意義
countryquery字串否所有國家一個 ISO 3166-1 alpha-3 代碼(大寫),或以 EMU 代表歐元區。省略時,回應為每個國家各一列。不是國家的代碼會回傳 400,沒有資料列的國家會回傳 404。

回應

回應只有一個欄位 countries,為清單。每一項包含下列欄位。

欄位含義
country國家,或以 EMU 代表歐元區。
partners_tier依 Narwhal 直接收錄的資料,由誰提供夥伴國路由的資料:own,即該國自有的海關或統計機構;或 partner_reported,即對調流向的其他國家申報,適用於 Narwhal 沒有該國自有機構數字的情況。
partner_coverage列出所有夥伴國時為 all;發布機構僅列示其主要夥伴國與一列其餘合計時為 top_n。partners_tier 為 partner_reported 時為 null。
products_tier由誰提供產品路由的資料:own;或在該國沒有自有產品檔案時為 partner_reported。UN Comtrade 僅有夥伴國總額,因此從不提供產品資料。
answers_with目前夥伴國與產品路由所採用的來源,依此順序:該國自有機構(own)、其向 UN Comtrade 提交的申報(third_party)、其他國家的申報(partner_reported,絕非官方數字)。其他國家的申報,只有在至少 200 個申報國有關於該國的資料列時,才會排在 UN Comtrade 之前,這超過 Narwhal 所收錄的數量,因此它們排在最後。依章查詢時,UN Comtrade 沒有任何資料,因此由 partner_reported 提供資料。Narwhal 沒有該國任何資料時為 null。
tiers_held目前有資料列的所有來源:可為此國家提供資料的 basis 值。
first_periodNarwhal 從該國自有機構收錄的第一個月份。沒有時為 null。
latest_periodNarwhal 從該國自有機構收錄的最新月份。沒有時為 null。
comtrade_latest_period該國向 UN Comtrade 申報的最新月份。沒有時為 null。
third_party_latest_periodNarwhal 從 UN Comtrade 為該國收錄的最新月份。沒有時為 null。
comtrade_periods該國向 UN Comtrade 申報的月份數。
comtrade_latest_year該國向 UN Comtrade 申報的最新年份。
has_headline該國發布貨物貿易的月度總額時為 true。
has_services該國發布服務貿易時為 true。
has_tariff_book有國家關稅稅則可用時為 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_tier 為 own,products_tier 為 partner_reported:加拿大的夥伴國資料來自加拿大統計局,依章劃分的產品資料則來自其他國家的申報。

未涵蓋的國家

真實存在但沒有數字的國家代碼會回傳 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_id。缺少或無效的金鑰(401)、餘額低於該次呼叫的價格(402)以及每分鐘請求過多(429),是所有路由共有的帳戶錯誤:請見「錯誤與額度」。

狀態代碼發生時機
400invalid_querycountry 不是國家代碼。
404country_not_coveredNarwhal 在任何來源中都沒有該國的貿易資料列。

API 錯誤 處理:錯誤碼、額度與重試 · 貿易數據 API 參考 · 貿易國家

此頁面對你有幫助嗎?