---
title: "財經日曆 API 參考文件 | Narwhal API"
description: "查閱本頁的財經日曆 API 參考文件，了解已排定的經濟數據公布的時程、發布變更及已公布結果的詳細資訊，並可使用同一組 Narwhal API 金鑰，透過 REST 與 MCP 存取。"
url: "https://narwhalapi.com/zh-tw/docs/api/economic-calendar"
---

# 財經日曆 API：經濟數據公布參考文件

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

## 請求

[浏览經济數據發布日曆 →](https://narwhalapi.com/zh-tw/economics/calendar.md)

兩項操作都使用你的 Narwhal Bearer 金鑰。Each successful request costs one call on the Calendars API code, $2 per 1,000 calls. [產品概覽 →](https://narwhalapi.com/zh-tw/api/economic-calendar.md)

列出發布事件

```
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 天。 |
| `limit / cursor` | 頁面大小為 1–100，預設值為100。使用 `next_cursor` 和相同的篩選條件繼續查詢。 |
| `release_id / version_id` | 發布事件詳情使用 UUID 路徑 ID，以及選填的 UUID 版本 ID。 |

未知的 `release_id` 回傳 `404 not_found`。格式錯誤、遭竄改或與篩選條件不符的游標回傳 `400 invalid_cursor`。超過30分鐘的游標或無法使用的快照回傳 `409 cursor_expired`。請移除過期游標後重新請求。

## 回應範例

清單回應範例。詳情操作會回傳單一發布事件物件，除了相同欄位，還包含 `version` 和 `observed_at`。

200 OK

```
{
  "releases": [
    {
      "release_id": "00000000-0000-4000-8000-000000000201",
      "revision": 0,
      "country": "USA",
      "series_id": "usa-consumer-prices",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "family": "prices",
      "period": "2026-09",
      "status": "scheduled",
      "at": "2026-10-14T12:30:00Z",
      "timezone": "America/New_York",
      "values": []
    }
  ],
  "next_cursor": null
}
```

| 欄位 | 規則 |
| --- | --- |
| `name` | `name` 是 Narwhal 從封閉清單中選取的標準英文名稱，例如 `Producer prices` 或 `Labour force survey`，不含日期。 |
| `series_id` | `series_id`是Narwhal為序列指派的永久ID，所有版本共用，例如`tur-producer-prices`。它是短識別字而非UUID，因此`/v1/economics/series/*`路由不接受該值。序列尚未分類時不提供此欄位。 |
| `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` 是最晚可能日期。`by` 是截止日期，並不保證當天發布。所有時間戳記均為UTC；`timezone` 是發布機構的IANA時區。 |
| `period / values` | `period` 為該次發布的統計期間，詳細程度以發布機構提供的資訊為準：`2026-09`（月）、`2026-Q3`（季）、`2018-04/2018-06`（滾動區間）、`2026-09-12`（日或週）或 `2025`（年）。發布機構未註明統計期間時，省略此欄位。`values` 一律存在，數值公布前為空；詳見下方的「數值」。 |
| `date_basis` | `date_basis` is `indicative` when the date comes from a third-party calendar and not from the publisher. An indicative date can still move. It is absent when the publisher or the central bank set the date. The publisher's date always wins over the third-party calendar. |
| `meeting` | `meeting` is set on a central bank's policy meeting and holds the meeting's days from the bank's own calendar. `kind` is `scheduled` (the date is on the bank's calendar for the year), `unscheduled` or `extraordinary`. `starts_on` is the first day of a multi-day meeting, when the bank gives it, and `ends_on` is the last day, the day the decision is announced. |
| `revision / version / observed_at` | 每次發布詳細資料變更時，`revision` 都會遞增。從未修訂時為 0。`GET /v1/economics/calendar/{release_id}` 也會傳回 `version` 和 `observed_at`。`version` 為不可變版本，可作為 `version_id` 傳回；`observed_at` 為 Narwhal 最後一次在發布機構日曆中觀測到該次發布的時間。 |

欄位僅在有值時出現。部分發布機構在發布日曆中同時列出的研究文章和重複資料集不包含在內。

## 時程與狀態的意義

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

發布時間由最上層的 `at`、`date`、`between` 或 `by` 欄位表示。請保留 `timezone` 和現有的範圍界限；`by` 表示截止日期，並非承諾在該日公布。`observed_at` 為 Narwhal 最後一次在發布機構日曆中觀測到該次發布的時間。

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

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

## Consensus, indicative dates and central bank meetings

Besides the publishers' own schedules, the calendar carries a third-party calendar. It adds a `consensus` forecast to figures, dates for releases the publishers do not list, and the days of central bank policy meetings. The publisher's date and figure always win over the third-party calendar.

This request returns the Bank Indonesia policy rate decision with a `meeting` object and a `consensus` on each rate, and a bank lending release whose date is `indicative`. Nothing is published yet, so `actual` is absent.

Policy rate meeting and indicative date

```
curl --request GET \\
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=IDN&start_date=2026-11-18&end_date=2026-11-18" \\
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

200 OK

```
{
  "releases": [
    {
      "release_id": "7c9f64b5-bc4c-4875-9757-a5a3be9796dd",
      "revision": 1,
      "country": "IDN",
      "series_id": "idn-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "scheduled",
      "date": "2026-11-18",
      "timezone": "Asia/Jakarta",
      "values": [
        {
          "measure": "deposit_facility_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "5",
          "consensus": "5"
        },
        {
          "measure": "lending_facility_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "6.5",
          "consensus": "6.75"
        },
        {
          "measure": "policy_rate",
          "period": "2026-11",
          "unit": "percent",
          "previous": "5.75",
          "consensus": "6"
        }
      ],
      "meeting": {
        "kind": "scheduled",
        "ends_on": "2026-11-18"
      }
    },
    {
      "release_id": "ff160cc0-f950-4bde-8f98-73dbb6ff6423",
      "revision": 1,
      "country": "IDN",
      "series_id": "idn-bank-lending",
      "name": "Bank lending",
      "topic": "money_credit",
      "family": "money",
      "period": "2026-10",
      "status": "scheduled",
      "date_basis": "indicative",
      "at": "2026-11-18T07:30:00Z",
      "timezone": "Asia/Jakarta",
      "values": [
        {
          "measure": "bank_credit_yoy",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "13.26"
        }
      ]
    }
  ],
  "next_cursor": null
}
```

After a decision, a figure from the third-party calendar shows as `provisional` until the publisher's own release confirms it. This answer is the Bank Negara Malaysia decision of 5 November 2026.

Provisional figure

```
curl --request GET \\
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=MYS&start_date=2026-11-05&end_date=2026-11-05" \\
  --header "Authorization: Bearer $NARWHAL_API_KEY"
```

200 OK

```
{
  "releases": [
    {
      "release_id": "007f2565-07af-43df-b778-0abef890689a",
      "revision": 1,
      "country": "MYS",
      "series_id": "mys-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "published",
      "date_basis": "indicative",
      "at": "2026-11-05T07:00:00Z",
      "timezone": "Asia/Kuala_Lumpur",
      "values": [
        {
          "measure": "policy_rate",
          "period": "2026-11",
          "unit": "percent",
          "actual": "2.75",
          "previous": "2.75",
          "consensus": "2.75",
          "provisional": true
        }
      ]
    }
  ],
  "next_cursor": null
}
```

Treat `date_basis: indicative` and `provisional` as signs that a date or a figure can still change.

## 發布日曆涵蓋範圍

The calendar covers 114 countries as of 13 November 2026. Official release schedules from statistical offices and central banks come first. A third-party calendar adds countries and releases that the publishers do not list in a form Narwhal can read. A date that comes only from the third-party calendar carries `date_basis` `indicative`。Coverage varies by publisher and economic series; inclusion does not mean every indicator has a schedule. Filter the list request by country and date window to see the releases available in that snapshot.

Countries in the calendar · 114

`AGO` `ALB` `ARE` `ARG` `ARM` `AUS` `AUT` `AZE` `BEL` `BGD` `BGR` `BHR` `BIH` `BLR` `BRA` `BWA` `CAN` `CHE` `CHL` `CHN` `COL` `CPV` `CRI` `CYP` `CZE` `DEU` `DNK` `DOM` `ECU` `EGY` `EMU` `ESP` `EST` `FIN` `FRA` `GBR` `GEO` `GHA` `GRC` `GTM` `HKG` `HRV` `HUN` `IDN` `IND` `IRL` `ISL` `ISR` `ITA` `JAM` `JOR` `JPN` `KAZ` `KEN` `KGZ` `KOR` `LBN` `LKA` `LSO` `LTU` `LUX` `LVA` `MAC` `MAR` `MDA` `MEX` `MKD` `MLT` `MNE` `MNG` `MOZ` `MUS` `MWI` `MYS` `NAM` `NGA` `NLD` `NOR` `NZL` `OMN` `PAK` `PER` `PHL` `PNG` `POL` `PRT` `PRY` `PSE` `ROU` `RUS` `RWA` `SAU` `SGP` `SLV` `SRB` `SUR` `SVK` `SVN` `SWE` `SWZ` `SYC` `THA` `TUN` `TUR` `TWN` `UGA` `UKR` `URY` `USA` `UZB` `VNM` `ZAF` `ZMB` `ZWE`

Countries with a release calendar page · 114

- 阿爾巴尼亞 · ALB
- 安哥拉 · AGO
- 阿根廷 · ARG
- 亞美尼亞 · ARM
- [澳大利亞 · AUS](https://narwhalapi.com/zh-tw/economics/australia.md)
- [奧地利 · AUT](https://narwhalapi.com/zh-tw/economics/austria.md)
- 亞塞拜然 · AZE
- 巴林 · BHR
- 孟加拉 · BGD
- 白俄羅斯 · BLR
- [比利時 · BEL](https://narwhalapi.com/zh-tw/economics/belgium.md)
- 波士尼亞與赫塞哥維納 · BIH
- 波札那 · BWA
- 巴西 · BRA
- 保加利亞 · BGR
- 維德角 · CPV
- [加拿大 · CAN](https://narwhalapi.com/zh-tw/economics/canada.md)
- [智利 · CHL](https://narwhalapi.com/zh-tw/economics/chile.md)
- 中國 · CHN
- [哥倫比亞 · COL](https://narwhalapi.com/zh-tw/economics/colombia.md)
- 哥斯大黎加 · CRI
- [克羅埃西亞 · HRV](https://narwhalapi.com/zh-tw/economics/croatia.md)
- 賽普勒斯 · CYP
- [捷克 · CZE](https://narwhalapi.com/zh-tw/economics/czechia.md)
- [丹麥 · DNK](https://narwhalapi.com/zh-tw/economics/denmark.md)
- 多明尼加共和國 · DOM
- 厄瓜多 · ECU
- 埃及 · EGY
- 薩爾瓦多 · SLV
- [愛沙尼亞 · EST](https://narwhalapi.com/zh-tw/economics/estonia.md)
- 史瓦帝尼 · SWZ
- 歐元區 · EMU
- [芬蘭 · FIN](https://narwhalapi.com/zh-tw/economics/finland.md)
- [法國 · FRA](https://narwhalapi.com/zh-tw/economics/france.md)
- 喬治亞 · GEO
- [德國 · DEU](https://narwhalapi.com/zh-tw/economics/germany.md)
- 迦納 · GHA
- 希臘 · GRC
- 瓜地馬拉 · GTM
- 香港 · HKG
- 匈牙利 · HUN
- 冰島 · ISL
- 印度 · IND
- 印度尼西亞 · IDN
- [愛爾蘭 · IRL](https://narwhalapi.com/zh-tw/economics/ireland.md)
- 以色列 · ISR
- [義大利 · ITA](https://narwhalapi.com/zh-tw/economics/italy.md)
- 牙買加 · JAM
- [日本 · JPN](https://narwhalapi.com/zh-tw/economics/japan.md)
- 約旦 · JOR
- 哈薩克 · KAZ
- 肯亞 · KEN
- 吉爾吉斯 · KGZ
- [拉脫維亞 · LVA](https://narwhalapi.com/zh-tw/economics/latvia.md)
- 黎巴嫩 · LBN
- 賴索托 · LSO
- [立陶宛 · LTU](https://narwhalapi.com/zh-tw/economics/lithuania.md)
- [盧森堡 · LUX](https://narwhalapi.com/zh-tw/economics/luxembourg.md)
- 澳門 · MAC
- 馬拉威 · MWI
- [馬來西亞 · MYS](https://narwhalapi.com/zh-tw/economics/malaysia.md)
- 馬爾他 · MLT
- 模里西斯 · MUS
- [墨西哥 · MEX](https://narwhalapi.com/zh-tw/economics/mexico.md)
- 摩爾多瓦 · MDA
- 蒙古 · MNG
- 蒙特內哥羅 · MNE
- 摩洛哥 · MAR
- 莫三比克 · MOZ
- 納米比亞 · NAM
- [荷蘭 · NLD](https://narwhalapi.com/zh-tw/economics/netherlands.md)
- [紐西蘭 · NZL](https://narwhalapi.com/zh-tw/economics/new-zealand.md)
- 奈及利亞 · NGA
- 北馬其頓 · MKD
- [挪威 · NOR](https://narwhalapi.com/zh-tw/economics/norway.md)
- 阿曼 · OMN
- [巴基斯坦 · PAK](https://narwhalapi.com/zh-tw/economics/pakistan.md)
- 巴勒斯坦 · PSE
- 巴布亞紐幾內亞 · PNG
- 巴拉圭 · PRY
- 秘魯 · PER
- [菲律賓 · PHL](https://narwhalapi.com/zh-tw/economics/philippines.md)
- [波蘭 · POL](https://narwhalapi.com/zh-tw/economics/poland.md)
- [葡萄牙 · PRT](https://narwhalapi.com/zh-tw/economics/portugal.md)
- 羅馬尼亞 · ROU
- 俄羅斯 · RUS
- 盧安達 · RWA
- [沙烏地阿拉伯 · SAU](https://narwhalapi.com/zh-tw/economics/saudi-arabia.md)
- 塞爾維亞 · SRB
- 塞席爾 · SYC
- [新加坡 · SGP](https://narwhalapi.com/zh-tw/economics/singapore.md)
- 斯洛伐克 · SVK
- [斯洛維尼亞 · SVN](https://narwhalapi.com/zh-tw/economics/slovenia.md)
- 南非 · ZAF
- 南韓 · KOR
- [西班牙 · ESP](https://narwhalapi.com/zh-tw/economics/spain.md)
- 斯里蘭卡 · LKA
- 蘇利南 · SUR
- [瑞典 · SWE](https://narwhalapi.com/zh-tw/economics/sweden.md)
- [瑞士 · CHE](https://narwhalapi.com/zh-tw/economics/switzerland.md)
- 臺灣 · TWN
- 泰國 · THA
- 突尼西亞 · TUN
- 土耳其 · TUR
- 烏干達 · UGA
- 烏克蘭 · UKR
- 阿拉伯聯合大公國 · ARE
- [英國 · GBR](https://narwhalapi.com/zh-tw/economics/united-kingdom.md)
- [美國 · USA](https://narwhalapi.com/zh-tw/economics/united-states.md)
- 烏拉圭 · URY
- 烏茲別克 · UZB
- 越南 · VNM
- 尚比亞 · ZMB
- 辛巴威 · ZWE

An empty result means no releases are listed for that query in the snapshot. It does not guarantee that the publisher has no upcoming releases. Central bank meeting dates are served in this calendar as `meeting`。Public holidays, including bank holidays, and exchange closures are separate calendar datasets: see the [public holidays reference](https://narwhalapi.com/zh-tw/docs/api/calendars.md) 以及 [exchange closures reference (英文)](https://narwhalapi.com/docs/api/calendars/exchange-closures.md)。

## 數值

Each release in the economic release calendar API includes a `values` array, empty until figures are published. Each value is a figure printed by the publisher: `actual` for the release's own period and `previous` for the period before. An `actual` that comes from a third-party calendar is marked `provisional`. Narwhal never computes these figures.

已發布數值範例

```
{
  "values": [
    {
      "measure": "producer_price_change_mom",
      "unit": "percent",
      "transformation": "month_over_month",
      "actual": "0",
      "previous": "0.1",
      "previous_revised_from": "0.2"
    }
  ]
}
```

| 欄位 | 規則 |
| --- | --- |
| `measure` | `measure` 識別發布中的指標，例如 `producer_price_change_mom`。 |
| `concept` | `concept` 表示數據衡量的內容，例如 gdp 或 cpi，因此同一項數據在每個國家都有相同的 concept。搭配 `transformation` 和 `annualization` 一起閱讀，即可進行同口徑比較。 |
| `notice` | `notice` 包含發布機構要求每次存取時提供的來源使用條款，例如歐洲央行的條款。請將其與發布資料一併顯示。沒有此類條款時，省略此欄位。 |
| `period` | `period` 僅在數值對應的統計期間與該次發布的 `period` 不同時出現。例如，持續申領失業救濟人數對應的是該次發布統計週的前一週。 |
| `unit` | `unit` 為 `percent`（值 1.2 表示 1.2%）、`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` 為 `month_over_month`、`year_over_year`、`quarter_over_quarter`、`three_month_on_three_month` 或 `change`（以千為單位的水準差值，例如就業人數變化）。水準值省略此欄位。 |
| `annualized / not_seasonally_adjusted` | `annualized` is `true` when the figure is at an annual rate, as with U.S. GDP growth. `not_seasonally_adjusted` is `true` when the figure is not seasonally adjusted. If `annualized` is absent, the figure is not annualized. If `not_seasonally_adjusted` is absent, the figure is seasonally adjusted, or, on a figure from a third-party calendar, the source does not say. |
| `actual / previous` | `actual` 為該次發布統計期間的數值；`previous` 為前一期數值。兩者均由發布機構公布，從不由 Narwhal 計算。發布資料中未註明的數值會省略；下一次發布會將先前的 `actual` 作為 `previous` 提供。 |
| `consensus` | `consensus` is the expected figure for the period, from a third-party calendar. It is a forecast and not a published figure. It is absent when no forecast is known, and it can appear on a value whose `actual` the publisher printed. |
| `provisional` | `provisional` is `true` when `actual` has not been confirmed by the publisher's own release. The figure comes from a third-party calendar and can change when the publisher publishes. It is absent otherwise. |
| `previous_revised_from` | 當本次發布修訂了 `previous` 時，`previous_revised_from` 為先前首次公布的數值。 |
| `value_status` | `value_status` 僅在缺少 `actual` 時出現：`pending_capture` 表示預定時間已過、數值尚未擷取；`unavailable` 表示該次發布已公布或取消，但未提供該數值。 |

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

此頁面對你有幫助嗎?
