世界銀行資料 API

API由 Narwhal API 提供

Narwhal API 透過各國專屬的 ID 讀取年度世界發展指標，例如 wdi:ny.gdp.mktp.cd/idn，代表以當期美元計價的印尼 GDP。搜尋指標後，即可使用同一把 API 金鑰讀取其定義、觀測值或最新數值。

依國家讀取年度指標

使用 wdi:<indicator>/<iso3> 讀取某個國家的 WDI 指標，並須遵守下列授權限制。兩個部分皆使用小寫字母。國家部分為 ISO 3166-1 alpha-3 代碼，例如印尼的 idn。

WDI 序列為年度資料。回應保留指標的單位標籤，觀測值為十進位字串。缺少資料的年份會省略，絕不補值。序列不提供修訂歷程或歷次發布版本。

搜尋指標

使用 q 搜尋目錄，並以 source=wdi 限定結果。所有方案皆可搜尋，且搜尋不會向來源發出請求。查詢文字接受 2 至 100 個字元；limit 接受 1 至 100 筆結果，預設為 25。

搜尋 WDI 指標
curl "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"
搜尋回應
{
  "results": [
    {
      "id_template": "wdi:bg.gsr.nfsv.gd.zs/{country}",
      "source": "wdi",
      "title": "Trade in services (% of GDP)",
      "frequency": "annual",
      "unit_label": "Trade in services (% of GDP)"
    },
    {
      "id_template": "wdi:bm.klt.dinv.wd.gd.zs/{country}",
      "source": "wdi",
      "title": "Foreign direct investment, net outflows (% of GDP)",
      "frequency": "annual",
      "unit_label": "Foreign direct investment, net outflows (% of GDP)"
    }
  ],
  "next_cursor": "eyJhIjoid2RpOmJtLmtsdC5kaW52LndkLmdkLnpzIiwicSI6IjBhOTNhNWZiMmE1NzkzY2EifQ"
}

以所需的國家代碼取代結果中 id_template 的 {country}。對應的 MCP 工具為 economics_search_catalogue。

讀取序列

在 id 查詢參數中傳入完整 ID，包含斜線。請先讀取定義，確認標題、頻率與單位標籤。印尼 GDP 的來源單位標籤為 GDP (current US$)。

讀取印尼 GDP 中繼資料
curl "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"
部分定義欄位
{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "title": "GDP (current US$), Indonesia",
  "country": "IDN",
  "frequency": "annual",
  "unit": "extended",
  "unit_label": "GDP (current US$)",
  "seasonal_adjustment": "not_stated",
  "first_period": "1967",
  "last_period": "2025"
}

請另外讀取觀測值。年度的 start 與 end 邊界使用 YYYY，且包含起訖年度。觀測資料每頁最多接受 1,000 筆記錄。在 MCP 中，使用 economics_read_catalogue_series 讀取定義，使用 economics_read_catalogue_observations 讀取數值。

讀取 GDP 觀測值
curl "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"
Pro 請求的部分觀測資料回應欄位
{
  "id": "wdi:ny.gdp.mktp.cd/idn",
  "observations": [
    {"period": "1967", "value": "5667756627.92093"},
    {"period": "1968", "value": "7076465299.81141"},
    {"period": "1969", "value": "8337423312.88344"}
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

一次讀取多個國家的資料

在 ids 參數中傳入 1 至 50 個不重複的序列 ID，以逗號分隔，即可讀取其最新觀測值。保持指標部分不變並更換國家代碼，即可請求各國的相同指標。

讀取印尼與日本的最新 GDP
curl "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,wdi:ny.gdp.mktp.cd/jpn" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

每個回傳的序列計為一次呼叫，整批一次計費。比較數值時，請檢查每筆觀測資料的 period。MCP 工具為 economics_read_catalogue_latest_batch。

查看各方案限制

未快取資料的擷取額度以每個帳戶、每個 UTC 日計算。只有序列不在快取中時才需要擷取；每日額度用盡後，仍可讀取已快取的序列。

限制免費BasicPro
每日未快取擷取次數101001,000
歷史資料範圍最近 12 個月最近 5 年完整歷史資料
年度觀測值最低保留筆數最新 5 筆最新 5 筆最新 5 筆

年度資料可存取範圍為方案的歷史資料範圍或最新 5 筆觀測值，以涵蓋較多資料者為準。若查詢範圍完全早於允許的歷史資料範圍，會回傳 403 plan_upgrade_required。

額度用盡後，若請求需要擷取資料，會回傳 429 fetch_limit_reached，並以 Retry-After 指示等待至 00:00 UTC。帳戶已達上限但有保留副本時，會回傳該副本且不計費。

保留授權條款與來源標示

目錄收錄 1,489 個採用 CC BY 4.0 的世界銀行 WDI 指標。另有九個採用其他授權條款的指標，其 ID 請求會遭拒絕，且不提供資料。

每個序列回應皆包含 attribution 與 licence_url。使用資料時，請一併保留世界銀行的來源標示與 CC BY 4.0 授權條款。回應也包含 fetched_at，讓你能在記錄觀測期間的同時，記錄 Narwhal 擷取序列的時間。

如何依國家代碼取得世界銀行指標？

搜尋指標，取得其 id_template，再以小寫的 ISO 3166-1 alpha-3 代碼取代 {country}。例如，印尼的 GDP 序列為 wdi:ny.gdp.mktp.cd/idn。

讀取定義或觀測值時，將完整 ID 作為 id 參數傳入。儲存或比較序列時，請讓國家代碼與指標保持在一起。

世界銀行資料的時效性如何？

WDI 觀測資料為年度資料，Narwhal 會將序列快取 24 小時至 7 天。未命中快取時，Narwhal 會在方案每日額度內向來源擷取資料。

請分別檢查觀測資料的 period 與 fetched_at：前者標明衡量的年度，後者記錄擷取時間。若無法連線至來源，可回傳保留的副本，並標示 stale: true。

發布於 。

後續步驟