所有 API

经济日历 API

跟踪计划中的经济数据发布及其发布状态。为 GDP、价格、劳动力、贸易和收益率曲线构建发布日历,避免将不确定的日程当作确切时间。

在线94.13% uptime, last 30天674 ms 典型响应

首次请求

列出某个月的发布

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-10-01&end_date=2026-10-31" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
响应示例
{
  "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
}

查找央行利率决议

curl --request GET \
  --url "https://api.narwhalapi.com/v1/economics/calendar?countries=USA&start_date=2026-12-09&end_date=2026-12-09" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"
响应示例
{
  "releases": [
    {
      "release_id": "52e78613-4f51-4cc8-b8dd-a4c3cc798c50",
      "revision": 1,
      "country": "USA",
      "series_id": "usa-monetary-policy-press-conference",
      "name": "Monetary policy press conference",
      "topic": "policy_communication",
      "family": "policy_rate",
      "status": "scheduled",
      "at": "2026-12-09T19:30:00Z",
      "timezone": "America/New_York",
      "values": []
    },
    {
      "release_id": "ed7bb0f9-6b9b-4e27-9b43-d891742ec3d4",
      "revision": 1,
      "country": "USA",
      "series_id": "usa-policy-rate-decision",
      "name": "Policy rate decision",
      "topic": "policy_rate",
      "family": "policy_rate",
      "status": "scheduled",
      "at": "2026-12-09T19:00:00Z",
      "timezone": "America/New_York",
      "values": []
    }
  ],
  "next_cursor": null
}

日历订阅

curl --request POST \
  --url "https://api.narwhalapi.com/v1/calendars/subscriptions" \
  --header "Authorization: Bearer $NARWHAL_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"countries":["USA"],"start_date":"2026-09-01","end_date":"2026-12-31","include_releases":true,"include_holidays":true}'
响应示例
{
  "subscription_id": "00000000-0000-4000-8000-000000000301",
  "url": "https://api.narwhalapi.com/v1/calendars/subscriptions/EXAMPLE_TOKEN.ics",
  "expires_at": "2027-10-22T09:00:00Z"
}

端点

GET列出发布事件/v1/economics/calendar

列出日期范围内的数据发布事件

参数

  • countries可选

    ISO alpha-3 代码,如 USA。多个国家可重复该参数,最多 50 个。

  • start_date可选

    时间窗口的第一天。默认从今天前 30 天开始。

  • end_date可选

    时间窗口的最后一天。默认到今天后 335 天结束。窗口最长 366 天。

  • limit可选

    每页的发布数量,1 到 100。默认为 100。

  • cursor可选

    使用 next_cursor 和相同的筛选条件继续。

列表中的每次发布

  • release_id字符串

    要查看详情的发布。

  • name字符串

    Narwhal 的标准英文名称,如 Producer prices。不含日期。

  • topic字符串

    该序列衡量的内容,在每个国家都相同,如 consumer_prices 或 gdp。

  • period字符串

    该发布所涵盖的期间,如 2026-09 或 2026-Q3。

  • status字符串

    发布所处的状态,如 scheduled。

  • at / date / between / by字符串

    发布机构给出的时间:确切时间、某一天、一段日期范围或截止日期。日期未知时为 None。

  • values数组

    已发布的数据。发布之前数组为空。


完整参考文档 →
GET获取单次发布/v1/economics/calendar/{release_id}

读取一次数据发布的信息,可通过 version_id 选择版本

参数

  • release_id必填

    该发布的 UUID。

  • version_id可选

    较早版本的 UUID。省略则返回当前版本。

该次发布

  • version字符串

    不可变的版本,可作为 version_id 传回。

  • name字符串

    Narwhal 的标准英文名称,如 Producer prices。不含日期。

  • topic字符串

    该序列衡量的内容,在每个国家都相同,如 consumer_prices 或 gdp。

  • period字符串

    该发布所涵盖的期间,如 2026-09 或 2026-Q3。

  • status字符串

    发布所处的状态,如 scheduled。

  • at / date / between / by字符串

    发布机构给出的时间:确切时间、某一天、一段日期范围或截止日期。日期未知时为 None。

  • values数组

    已发布的数据。发布之前数组为空。


完整参考文档 →

使用场景

下次 CPI 发布日期

查明下一次美国 CPI 何时发布,按 UTC 和纽约时间显示。

阅读指南 →

发布前提醒

通过日历订阅源或每日脚本,在发布前收到提醒。

阅读指南 →

按你的时区显示发布时间

把 UTC 发布时间换算成当地时间,并处理夏令时。

阅读指南 →

FOMC 会议与会议纪要

列出已排定的 FOMC 利率决议和会议纪要。

阅读指南 →

覆盖范围

共114个国家。其中43个直接从发布机构读取发布日程,其余71个使用第三方日历的日期,并标为参考日期。

显示全部 114 个国家

来源

55个官方发布机构:统计局、部委和央行。发布机构自己的日期和数据始终优先于第三方日历。

  • Instituto Nacional de Estadística y Censos (INDEC)阿根廷
  • Australian Bureau of Statistics (ABS)澳大利亚
  • Statistics Austria奥地利
  • Eurostat7个国家
  • Statbel比利时
  • National Bank of Belgium比利时
  • Banco Central do Brasil巴西
  • National Statistical Institute (NSI)保加利亚
  • Statistics Canada加拿大
  • Central Bank of Chile (BCCh)智利
  • National Statistics Institute of Chile (INE)智利
  • Croatian Bureau of Statistics (CBS)克罗地亚
显示全部 55 个来源
  • Czech Statistical Office (ČSÚ)捷克
  • Statistics Denmark丹麦
  • Statistics Estonia爱沙尼亚
  • European Commission (DG ECFIN)欧元区
  • Statistics Finland芬兰
  • Finnish Customs (Tulli)芬兰
  • National Institute of Statistics and Economic Studies (INSEE)法国
  • French Customs法国
  • Federal Statistical Office of Germany (Destatis)德国
  • Hellenic Statistical Authority (ELSTAT)希腊
  • Hungarian Central Statistical Office (KSH)匈牙利
  • Statistics Iceland冰岛
  • Ministry of Statistics and Programme Implementation (MoSPI)印度
  • Central Statistics Office (CSO)爱尔兰
  • Italian National Institute of Statistics (Istat)意大利
  • Statistics Bureau of Japan日本
  • Cabinet Office of Japan日本
  • Japan Customs日本
  • Central Statistical Bureau of Latvia (CSB)拉脱维亚
  • State Data Agency of Lithuania立陶宛
  • STATEC卢森堡
  • Department of Statistics Malaysia (DOSM)马来西亚
  • INEGI墨西哥
  • Statistics Netherlands (CBS)荷兰
  • Stats NZ新西兰
  • Statistics Norway (SSB)挪威
  • Statistics Poland波兰
  • Statistics Portugal (INE)葡萄牙
  • National Bank of Romania (BNR)罗马尼亚
  • Federal State Statistics Service (Rosstat)俄罗斯
  • Bank of Russia俄罗斯
  • Singapore Department of Statistics (SingStat)新加坡
  • Singapore government open-data publications新加坡
  • Statistical Office of the Republic of Slovenia (SURS)斯洛文尼亚
  • National Statistics Institute of Spain (INE)西班牙
  • Spanish Tax Agency (AEAT)西班牙
  • Statistics Sweden (SCB)瑞典
  • Directorate-General of Budget, Accounting and Statistics (DGBAS)台湾
  • Turkish Statistical Institute (TurkStat)土耳其
  • Office for National Statistics (ONS)英国
  • Bureau of Labor Statistics (BLS)美国
  • Bureau of Economic Analysis (BEA)美国
  • US Census Bureau美国

相关 API

节假日 API

按国家列出的官方公共假日,区分全国与地区范围。

探索 API →

经济数据 API

关于价格、劳动、产出、贸易和利率的官方指标。

探索 API →

价格

预付额度,每1,000次调用2美元,没有套餐或档位。

查看价格 →

常见问题

每次发布都有确切时间吗?

不是。发布机构可能仅指定日期、范围或截止日期。响应通过顶层的 at、date、between 或 by 字段保留该精度。

可以获取较早版本吗?

在发布详情请求中使用 version_id 参数选择不可变版本。

有免费的经济日历 API 吗?

有。每个 Narwhal 账户每月都有10美元免费额度,无需绑卡,也没有期限。一次日历请求算一次调用,每1,000次调用2美元,所以免费额度每月可调用5,000次。

日历包含市场共识预测吗?

有,前提是第三方日历有该预测。每个值会在前值旁带上市场共识,发布后再带上实际值。市场共识是预测而不是已公布的数字,没有已知预测时不会出现。没有重要性评级。

发布时间使用哪个时区?

精确的发布时间(at 字段)为 UTC。timezone 字段给出发布机构自己的 IANA 时区,例如 Asia/Jakarta,便于显示当地时间。只有日期的发布没有时间。

日历能返回多少历史数据?

一次请求最多覆盖366天的区间。默认从今天前30天到今天后335天。更长的范围请按区间逐段获取。内容有变化的发布会保留旧版本,用 version_id 读取。

能以 ICS 订阅源获取日历吗?

能。创建日历订阅后,Narwhal 会返回一个私有的 .ics 链接,日历应用可订阅。它可包含发布、公共假日或两者,覆盖1至50个国家,区间最长366天。创建一次算一次调用。

AI 智能体能通过 MCP 读取日历吗?

能。Narwhal MCP 服务器提供 economics_list_releases 和 economics_get_release,与 REST 端点的两个操作相同。

速率限制是多少?

账户只有免费额度时每分钟50次请求,持有付费额度后每分钟500次。同一网络地址每分钟限120次。429 响应带有 Retry-After,且不收费。

使用数据之前应该检查什么?

预定发布并不保证在准确的预定时刻公布。请保留时间精度和时区,并明确处理已取消的发布。预定发布时间与 Narwhal 观察到该次发布的时间代表不同的事件。