任意序列 API 參考文件

搜尋世界銀行和加拿大統計局的目錄，並依 ID 讀取序列，包含方案限制、快取與錯誤處理說明。

透過四項操作，依 ID 存取世界銀行和加拿大統計局的資料序列。你可以搜尋目錄、讀取序列定義或觀測值，或一次取得最多 50 個序列的最新值。

REST 與 MCP 共用結構描述、金鑰及配額。依 ID 即時讀取的世界銀行與加拿大統計局數列不提供修訂歷史。Pro 金鑰可透過支援的各國歷史資料路由與依 ID 查詢數列的路由讀取歷史版本，詳見經濟 API 參考文件中的「依 ID 查詢數列歷史資料」。

操作

操作	REST 路徑	MCP 工具	回傳內容
搜尋目錄	`GET /v1/economics/catalogue`	`economics_search_catalogue`	符合查詢條件的序列和資料表。
讀取序列	`GET /v1/economics/catalogue/series`	`economics_read_catalogue_series`	單一序列的定義。
讀取觀測值	`GET /v1/economics/catalogue/series/observations`	`economics_read_catalogue_observations`	單一序列的數值，由舊到新排列。
最新數值	`GET /v1/economics/catalogue/latest`	`economics_read_catalogue_latest_batch`	1 至 50 個序列各自的最新值。

來源鍵值可能包含斜線，因此請透過 id 查詢參數傳入序列 ID。

每個請求都需要 Bearer 金鑰。身分驗證

序列 ID

序列 ID 使用小寫格式 <source>:<key>。

來源	格式	範例	頻率
世界銀行，世界發展指標	`wdi:<indicator>/<iso3>`	`wdi:ny.gdp.mktp.cd/idn`	年度
加拿大統計局	`statcan:v<vector>`	`statcan:v41690973`	月、季、年

世界銀行的搜尋結果包含 id_template，例如 wdi:ny.gdp.mktp.cd/{country}。請將 {country} 替換為小寫的 ISO 3166-1 alpha-3 國家代碼。索引僅收錄以 CC BY 4.0 授權發布的指標；其他指標會回傳 404 not_found。

加拿大統計局的搜尋結果以資料表為單位。每筆結果都有 id_template statcan:v{vector}，標題則包含資料表編號，例如資料表 10-10-0106-01。請在加拿大統計局的該資料表網頁上找到序列的向量編號，再填入範本。目前沒有可列出資料表向量的路由。

加拿大統計局中，頻率為日、週、多年、會計年度或會計季度的向量會回傳 404 not_found。

搜尋目錄

搜尋使用 Narwhal 的索引，不會呼叫來源。所有方案皆可使用，每次計為一次呼叫。

q：搜尋文字，2 至 100 個字元。
source：wdi 或 statcan。
country：大寫的 ISO alpha-3 代碼。
frequency：daily、monthly、quarterly 或 annual。
limit：1 至 100；預設為 25。
cursor：上一頁的 next_cursor。

每筆結果都包含 source、title，以及 id 或 id_template 其中一項。若已知，也會包含 frequency、unit_label、country、first_period 和 last_period。最後一頁的 next_cursor 為 null。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=gdp&source=wdi&limit=2" \
  --header "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"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue?q=consumer%20price&source=statcan&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "results": [
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Consumer Price Index (CPI) statistics, alternative measures, unadjusted and seasonally adjusted, Bank of Canada (Statistics Canada table 10-10-0106-01)",
      "frequency": "monthly",
      "country": "CAN",
      "first_period": "1979-11",
      "last_period": "2026-09"
    },
    {
      "id_template": "statcan:v{vector}",
      "source": "statcan",
      "title": "Inter-city indexes of price differentials of consumer goods and services, annual (Statistics Canada table 18-10-0003-01)",
      "frequency": "annual",
      "country": "CAN",
      "first_period": "2000",
      "last_period": "2019"
    }
  ],
  "next_cursor": "eyJhIjoic3RhdGNhbjp0MTgxMDAwMDMiLCJxIjoiNGQxYjFkOWQwN2FlNTBhMiJ9"
}

讀取序列

回傳單一序列的定義，包含起始和結束期別，不含觀測值。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=wdi:ny.gdp.mktp.cd/idn" \
  --header "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",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "first_period": "1967",
  "last_period": "2025"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series?id=statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "first_period": "1914-01",
  "last_period": "2026-09"
}

讀取觀測值

回傳單一序列的數值及其定義，數值依時間由舊到新排列。

id：序列 ID。
start 和 end：包含端點的範圍界限，使用序列的期別格式 YYYY、YYYY-MM 或 YYYY-Qn。兩個界限必須使用相同格式。
limit：1 至 1000；預設為 100。
cursor：上一頁的 next_cursor。

Narwhal 會先套用 start 和 end，再套用方案的歷史資料範圍。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=wdi:ny.gdp.mktp.cd/idn&limit=3" \
  --header "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",
  "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
  "licence_url": "https://creativecommons.org/licenses/by/4.0/",
  "fetched_at": "2026-10-27T03:37:35Z",
  "observations": [
    {
      "period": "1967",
      "value": "5667756627.92093"
    },
    {
      "period": "1968",
      "value": "7076465299.81141"
    },
    {
      "period": "1969",
      "value": "8337423312.88344"
    }
  ],
  "next_cursor": "eyJhIjoiMTk2OSIsInEiOiI2ZDM2OTAzMzcyMGJmYmU1In0"
}

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/series/observations?id=statcan:v41690973&start=2026-07&limit=3" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "statcan:v41690973",
  "title": "Canada;All-items",
  "frequency": "monthly",
  "unit": "extended",
  "unit_label": "2002=100",
  "seasonal_adjustment": "not_stated",
  "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
  "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
  "fetched_at": "2026-10-27T12:30:59Z",
  "observations": [
    {
      "period": "2026-07",
      "value": "169.9",
      "released_on": "2026-08-17"
    },
    {
      "period": "2026-08",
      "value": "169.8",
      "released_on": "2026-09-14"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19"
    }
  ],
  "next_cursor": null
}

來源未發布數值的年份或月份會省略，不會補值。每筆觀測值都有 period 和以十進位字串表示的 value；來源有提供時，也會包含 released_on 和 status。

單次請求取得最新值

以逗號分隔的 ids 清單傳入 1 至 50 個不重複的 ID。回應會回傳各序列的最新觀測值和定義。missing 清單會列出來源無法識別或沒有觀測值的 ID。

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/catalogue/latest?ids=wdi:ny.gdp.mktp.cd/idn,statcan:v41690973" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "observations": [
    {
      "period": "2025",
      "value": "1445642584163.81",
      "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",
      "attribution": "World Bank, World Development Indicators, CC BY 4.0. Values normalised by Narwhal.",
      "licence_url": "https://creativecommons.org/licenses/by/4.0/",
      "fetched_at": "2026-10-27T03:37:35Z"
    },
    {
      "period": "2026-09",
      "value": "170.0",
      "released_on": "2026-10-19",
      "id": "statcan:v41690973",
      "title": "Canada;All-items",
      "frequency": "monthly",
      "unit": "extended",
      "unit_label": "2002=100",
      "seasonal_adjustment": "not_stated",
      "attribution": "Contains information licensed under the Open Government Licence - Canada. Source: Statistics Canada. Values normalised by Narwhal.",
      "licence_url": "https://open.canada.ca/en/open-government-licence-canada",
      "fetched_at": "2026-10-27T12:30:59Z"
    }
  ],
  "missing": []
}

批次請求會一次計入用量，每個回傳的序列計為一次呼叫。

方案限制

所有方案皆可使用這四項操作。各方案分別設定未快取來源擷取的每日上限，以及可存取的歷史資料範圍。

限制	免費	Basic	Pro
每個 UTC 日的未快取擷取次數	10	100	1,000
歷史資料範圍	最近 12 個月	最近 5 年	完整歷史資料

每個方案至少都包含年度序列最新 5 筆觀測值，以及季度序列最新 4 筆觀測值，即使這些觀測值超出方案的歷史資料範圍。Narwhal 會比較歷史資料範圍與這些最新觀測值，採用包含筆數較多的一方。

請求範圍若完全早於方案的歷史資料範圍，會回傳 403 plan_upgrade_required。對於年度和季度序列，Narwhal 會先載入序列再執行此檢查，以套用最低觀測值筆數。

資料即時提供，沒有延遲。

呼叫次數、快取與過期資料

每次成功的搜尋、序列、觀測值或單一序列最新值請求，皆計為一次呼叫。批次請求則依回傳的序列數計算，每個序列計為一次呼叫。

過期資料回應，以及 400、404 和 503 回應，皆不計入用量。

Narwhal 從來源讀取序列後，會將其快取。已快取的序列一律直接回應，不會擷取來源；只有未快取的序列才會使用擷取次數。世界銀行序列的快取時間為 24 小時至 7 天。加拿大統計局序列的快取時間依頻率而定：月資料為 6 小時、季資料為 12 小時、年資料為 24 小時。

帳戶用完每日擷取次數後，需要再次擷取來源的請求會回傳 429 fetch_limit_reached。其 Retry-After 標頭會提供距離 00:00 UTC 的剩餘時間。若仍有該序列的舊副本，Narwhal 會回傳該副本並標示 stale: true，且不計入用量。

若來源無法使用且沒有快取副本，Narwhal 會回傳 503 upstream_busy，並附上 Retry-After。來源的速率限制絕不會直接轉為 429 回應。

欄位

序列回應包含以下欄位。

欄位	含義
`id`	序列 ID。
`title`	來源提供的序列標題。
`country`	ISO alpha-3 代碼，來源有提供時才包含。
`frequency`	`daily`、`monthly`、`quarterly` 或 `annual`。
`unit`	固定為 `extended`。
`unit_label`	以來源原文表示的單位。世界銀行序列使用指標名稱，例如 `GDP (current US$)`。
`scale, currency`	僅在來源有註明時包含。Narwhal 絕不會依 `scale` 換算數值。
`seasonal_adjustment`	`seasonally_adjusted`、`not_seasonally_adjusted`、`not_applicable` 或 `not_stated`。
`base_period`	指數基期，來源有註明時才包含。
`attribution, licence_url`	必須保留的來源標示，以及來源授權條款的連結。
`fetched_at`	Narwhal 讀取來源的時間。
`stale`	僅在無法連線至來源，且 Narwhal 回傳最後保留的副本時，才為 `true`。
`first_period, last_period`	起始和結束期別，包含於序列定義中。

錯誤

狀態與代碼	含義
`400 invalid_series_id`	ID 的來源格式無效。詳細資訊會指出世界銀行應使用 `<indicator>/<iso3 country>`，加拿大統計局應使用 `v<vector number>`。
`400 invalid_query`	參數無效。例如批次請求超過 50 個 ID、ID 重複，或 `start` 和 `end` 使用不同的期別格式。
`403 plan_upgrade_required`	請求範圍的結束時間早於方案的歷史資料範圍。
`404 not_found`	來源或索引無法識別該序列，或序列的頻率不受支援。Narwhal 會將此結果快取 24 小時。
`404 not_covered`	ID 指定的來源不受支援。
`429 fetch_limit_reached`	帳戶已用完當日 UTC 的擷取配額。`Retry-After` 會提供距離 00:00 UTC 的剩餘時間。
`503 upstream_busy`	來源無法使用，且沒有快取副本。請等待 `Retry-After` 指定的時間後再試。

錯誤採用共用的問題回應結構，並包含 request_id。錯誤與配額

世界銀行資料 API · 加拿大統計局資料 API

來源標示

每個回應都會在 attribution 中列出機構名稱，並在 licence_url 中提供其授權條款連結。世界銀行指標採用 CC BY 4.0，加拿大統計局資料採用加拿大開放政府授權條款。Narwhal 會將數值標準化；凡顯示這些數值之處，請保留來源標示。

經濟數據 API 參考 · MCP