浏览全部文档

经济数据发布 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 表示该次发布已公布或取消,但未提供该数值。

这些字段今后可能会增加新的取值,因此客户端应接受无法识别的值。

此页面对你有帮助吗?