瀏覽全部文件

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

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

請求

浏览經济數據發布日曆 →

兩項操作都使用你的 Narwhal Bearer 金鑰。Each successful request costs one call on the Calendars API code, $2 per 1,000 calls. 產品概覽 →

列出發布事件
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
}
欄位規則
namename 是 Narwhal 從封閉清單中選取的標準英文名稱,例如 Producer prices 或 Labour force survey,不含日期。
series_idseries_id是Narwhal為序列指派的永久ID,所有版本共用,例如tur-producer-prices。它是短識別字而非UUID,因此/v1/economics/series/*路由不接受該值。序列尚未分類時不提供此欄位。
topictopic 表示該序列衡量的內容,在各國之間保持一致,例如 consumer_prices、labour_force、gdp、merchandise_trade 或 policy_rate。序列尚未分類時沒有此欄位,且可能新增主題。
stagestage 表示該次發布包含的是某一期間數據的哪個版次:flash、advance、first、second、third、preliminary 或 final。僅有單一版次的發布不含此欄位。
at / date / between / by日期未知,或估計範圍只有下限時,不回傳時間欄位。at 是確切的發布時間,date 是時間未定的發布日期,between 是包含首尾日期的可能範圍 [from, to],by 是最晚可能日期。by 是截止日期,並不保證當天發布。所有時間戳記均為UTC;timezone 是發布機構的IANA時區。
period / valuesperiod 為該次發布的統計期間,詳細程度以發布機構提供的資訊為準:2026-09(月)、2026-Q3(季)、2018-04/2018-06(滾動區間)、2026-09-12(日或週)或 2025(年)。發布機構未註明統計期間時,省略此欄位。values 一律存在,數值公布前為空;詳見下方的「數值」。
date_basisdate_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.
meetingmeeting 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

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 以及 exchange closures reference (英文)。

數值

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"
    }
  ]
}
欄位規則
measuremeasure 識別發布中的指標,例如 producer_price_change_mom。
conceptconcept 表示數據衡量的內容,例如 gdp 或 cpi,因此同一項數據在每個國家都有相同的 concept。搭配 transformation 和 annualization 一起閱讀,即可進行同口徑比較。
noticenotice 包含發布機構要求每次存取時提供的來源使用條款,例如歐洲央行的條款。請將其與發布資料一併顯示。沒有此類條款時,省略此欄位。
periodperiod 僅在數值對應的統計期間與該次發布的 period 不同時出現。例如,持續申領失業救濟人數對應的是該次發布統計週的前一週。
unitunit 為 percent(值 1.2 表示 1.2%)、index(附帶 index_base,例如 2015=100)、thousands、currency、ratio(例如求人倍率)或 balance(調查的淨差額,單位為點,並非百分比)。
currency / scalecurrency(ISO 4217 代碼)和 scale(units、thousands、millions、hundred_millions 或 billions)僅在 unit 為 currency 時出現。數值採用發布方標示的數量級。
transformationtransformation 為 month_over_month、year_over_year、quarter_over_quarter、three_month_on_three_month 或 change(以千為單位的水準差值,例如就業人數變化)。水準值省略此欄位。
annualized / not_seasonally_adjustedannualized 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 / previousactual 為該次發布統計期間的數值;previous 為前一期數值。兩者均由發布機構公布,從不由 Narwhal 計算。發布資料中未註明的數值會省略;下一次發布會將先前的 actual 作為 previous 提供。
consensusconsensus 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.
provisionalprovisional 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_statusvalue_status 僅在缺少 actual 時出現:pending_capture 表示預定時間已過、數值尚未擷取;unavailable 表示該次發布已公布或取消,但未提供該數值。

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

此頁面對你有幫助嗎?