经济数据发布 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`。

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