經濟數據發布 API 參考

列出已排程的發布事件，並取得保留原始時程精確度的不可變發布版本。

請求

兩項操作都使用你的 Narwhal Bearer 金鑰。產品概覽 →

列出發布事件

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-10-01&end_date=2026-10-31&limit=25" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

GET /v1/economics/calendar/{release_id} 取得一個發布事件。新增 version_id 以選擇特定的不可變版本。

參數

參數	規則
`countries`	選填的 ISO alpha-3 代碼。若要查詢多個國家，請重複使用此查詢參數，最多 50 個國家。
`start_date / end_date`	選填的日期範圍，包含首尾日期。預設從今天前 30 天至今天後 335 天；範圍最長為 366 天。
`view`	`view` 為 `compact`（預設）時每次發布回傳一個精簡項目，為 `full` 時回傳與 `GET /v1/economics/calendar/{release_id}` 相同的物件。完整檢視包含所有欄位：版本、修訂、時程詳情、數值時間戳記、季節調整以及修訂前的數值。
`limit / cursor`	頁面大小為 1–100，預設值為100。使用 `next_cursor` 和相同的篩選條件繼續查詢。
`release_id / version_id`	發布事件詳情使用 UUID 路徑 ID，以及選填的 UUID 版本 ID。

回應範例

清單回應範例。詳情操作會回傳單一發布事件物件，包含相同欄位。

200 OK

{
  "status": "ok",
  "snapshot": "calendar-snapshot-20260914",
  "as_of": "2026-09-14T08:00:00Z",
  "releases": [
    {
      "release_id": "00000000-0000-4000-8000-000000000201",
      "series_id": "usa-consumer-prices",
      "country": "USA",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "title": "Consumer Price Index",
      "period": "2026-09",
      "status": "scheduled",
      "at": "2026-10-14T12:30:00Z",
      "timezone": "America/New_York"
    }
  ],
  "next_cursor": null
}

欄位	規則
`title / name`	`title` 是發布機構自己的標題，保留其原有語言與措辭。`name` 是 Narwhal 從固定清單中選取的標準英文名稱，例如 `Producer prices` 或 `Labour force survey`，不含日期。
`series_id`	`series_id` 是 Narwhal 為該序列指派的永久 ID，所有版次共用，例如 `tur-producer-prices`。序列尚未分類時不會出現此欄位。
`topic`	`topic` 表示該序列衡量的內容，在各國之間保持一致，例如 `consumer_prices`、`labour_force`、`gdp`、`merchandise_trade` 或 `policy_rate`。序列尚未分類時沒有此欄位，且可能新增主題。
`stage`	`stage` 表示該次發布包含的是某一期間數據的哪個版次：`flash`、`advance`、`first`、`second`、`third`、`preliminary` 或 `final`。僅有單一版次的發布不含此欄位。
`at / date / between / by`	確定日期後會出現一個時間欄位：`at` 是確切的發布時間，`date` 是未設定時間的發布日期，`between` 是以 `[from, to]` 表示的可能日期範圍（含起訖日），`by` 是最晚可能的日期，即截止日期而非承諾日期。所有時間戳記均為 UTC；`timezone` 是發布機構的 IANA 時區，在完整檢視中，`schedule.local_date` 是該時區下的發布日期。
`period / values`	`period` 是該次發布涵蓋的期間。`values` 在數據公布後出現，包含 `measure`、`unit`、`transformation`、`actual` 和 `previous`，金額另含 `currency` 和 `scale`。

清單預設回傳精簡項目，欄位僅在有值時出現；傳入 view=full 可取得所有欄位。部分發布機構在其發布旁列出的研究文章與重複資料集不包含在內。

時程與狀態的意義

family 是以下值之一： gdp, prices, labour, trade, yield_curve, policy_rate, activity, survey, housing, money，或 public_finance。 status 是 scheduled, published，或 cancelled。

日程 precision 是 exact, date, estimated_range, deadline，或 unknown。請保留來源時區與可用的起訖範圍；截止日期是最晚日期，並非承諾的發布日期。 observed_at 和 officially_published_at 描述不同事件，並且可以為 null。

取消與改期會保留為明確的版本。請勿將未知時間填為午夜。

Narwhal 行事曆中歐洲中央銀行和加拿大央行的發布日期與時間來自各自銀行的網站，可在相應網站免費取得。每個回應中的每筆歐洲中央銀行發布紀錄都包含 notice 欄位，註明來源為歐洲中央銀行，並說明相關資訊可在 https://www.ecb.europa.eu 免費取得。

發布日曆涵蓋範圍

下列國家提供選定的官方發布時程。涵蓋範圍依發布機構及經濟數據序列而異；納入清單不代表每項指標都有時程。請依國家與日期範圍篩選清單請求，查看該快照中可用的發布事件。

有發布時程的國家 · 35

空結果表示該快照中的查詢沒有列出發布事件。這不保證發布方沒有即將發布的事件。國定假日和銀行休息日屬於不同的日曆資料集。

數值

財經日曆 API 中的每次發布都包含一個 indicators 陣列。每個指標包含發布方公布的數值：actual 對應本次發布本身的統計期間，previous 對應前一期。Narwhal 從不計算這些數值。以下欄位說明每個數值的統計期間、單位、轉換方式及年率換算情況。

欄位	規則
`period / previous_period`	`period` 表示數值涵蓋的統計期間：一個月（`2026-08`）、一季（`2026-Q3`）、截至指定日期的一週（`2026-09-26`），或滾動三個月（`2026-06/2026-08`，分別為起始月和結束月）。`previous_period` 以相同格式表示前一期。在每週發布的數據中，某個數值可能涵蓋本次發布本身所屬週的前一週，例如持續申領失業救濟金人數。
`unit`	`unit` 為 `percent`、`index`（附帶 `index_base`，例如 `2015=100`）、`thousands`、`currency`、`ratio`（例如職缺數與求職人數之比），或 `balance`（調查淨差額，以點數表示，而非百分比）。
`currency / scale`	`currency`（ISO 4217 代碼）和 `scale`（`units`、`thousands`、`millions`、`hundred_millions` 或 `billions`）僅在 `unit` 為 `currency` 時出現。數值採用發布方標示的數量級。
`transformation`	`transformation` 為 `level`、`month_over_month`、`year_over_year`、`quarter_over_quarter`、`three_month_on_three_month`，或 `change`（水準值之差，以千為單位，例如就業人數變動）。
`annualization`	`annualization` 一律存在，其值為 `annualized`（例如以年率表示的美國 GDP 成長率）或 `not_annualized`。
`actual / previous`	`actual` 是本次發布本身統計期間的數值；`previous` 是前一期的數值。兩者均由發布方公布，Narwhal 從不計算。如果發布內容未註明前一期數值，`previous` 可能為 `null`；下一次發布則會將先前的 `actual` 作為其 `previous`。

這些欄位日後可能會新增可用值，因此用戶端應接受無法辨識的值。