按国家和日期搭建经济日历

使用 API 完成操作

发布日期请使用经济日历。每个发布项都有时间、国家和名称字段，以及所属期间、主题、状态和时区。如果你的产品或仪表板需要比打印出来的日程更多的细节，就把这些字段与发布项一起保存。

1. 设置你的 API 密钥 获取免费密钥，并保存在 NARWHAL_API_KEY 环境变量中。脚本会读取该变量，并把密钥以 Authorization: Bearer YOUR_KEY 的形式发送到 https://api.narwhalapi.com。Narwhal 的 REST 和 MCP 使用同一个密钥。
2. 选择国家和日期 重复传入 countries 参数，并带上 start_date 和 end_date。示例使用 USA、GBR 和 JPN，日期为 2026 年 11 月 9 日至 13 日。想要不同的日程时，修改国家列表和日期参数即可；请求仍指向 /v1/economics/calendar。
3. 获取并排序发布项 在环境变量中准备好密钥后运行 Python 脚本。它会收集所有分页中的发布项，筛选出带有 at 的记录，并把时间、国家和名称一起排序。打印出的日程使用 UTC 时间，最后给出所请求日期范围内的发布数量。
   Python：三个国家一周的发布项

   import os
   import requests
   
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   
   
   def calendar(countries, start, end):
       cursor = None
       while True:
           params = {
               "countries": countries,
               "start_date": start,
               "end_date": end,
               "limit": 100,
           }
           if cursor:
               params["cursor"] = cursor
           r = requests.get(
               "https://api.narwhalapi.com/v1/economics/calendar",
               params=params,
               headers=HEADERS,
               timeout=10,
           )
           r.raise_for_status()
           body = r.json()
           yield from body["releases"]
           cursor = body.get("next_cursor")
           if not cursor:
               return
   
   
   rows = sorted(
       (x["at"], x["country"], x["name"])
       for x in calendar(["USA", "GBR", "JPN"], "2026-11-09", "2026-11-13")
       if "at" in x
   )
   for at, country, name in rows:
       print(at, country, name)
   print(len(rows), "releases")

4. 选择要显示的字段 在更完整的日历中显示 at（UTC）、country、name、period、topic、status 和 timezone。脚本只打印时间、国家和名称。需要区分同一发布的不同版本时，请保留 stage。在数值公布之前 values 数组为空，所以已安排的发布可以在有数值之前就出现。

使用网站、日历应用或表格

要在 Narwhal 网站上查看发布项，请打开经济日历。每个国家都有各自的经济日历页面，想不写请求直接查看某个国家的日程时，这是最直接的方式。

日历订阅源会在你的日历应用里显示同样的发布项。请参照在经济数据发布前收到提醒了解这种方式。如果你更喜欢表格，它可以保存脚本的输出：UTC 时间、国家和发布名称。表格方式从 API 输出开始；想不写代码查看日程时，可以使用网站和订阅源。

不同情况应选哪种方法

为什么英国的 GDP 出现了两次？

同一发布的两个版本可能在同一时间发布，用 stage 可以区分。例如，首次估计值和月度数据可能安排在同一时间。该字段还能区分快速估计、初值、首次和终值等版本，所以只看发布名称和时间，各版本可能看起来一模一样。

在名称旁边显示 stage 或 release_id，以区分各个条目。2026 年 11 月 12 日 07:00 UTC，英国的日程中包含两次 GDP。显示该日程时要保留这两个条目，并在每个名称旁边显示版本或标识符。

一次请求会返回多少个发布项？

每页最多返回 100 个发布项。用 limit 设置页大小，并传入 cursor 继续读取结果。一页只是所请求日程的一部分；请通过 next_cursor 判断同一国家和日期范围内是否还有更多发布项需要收集。

一直读取到 next_cursor 为 null 或为空为止。如果 API 返回 409 cursor_expired，请不带游标重新发起请求。重新请求时要保持原来的国家和日期选择，这样才能从头取得你所要的日程。

日历中可以包含哪些国家？

省略 countries 会返回所有已覆盖的国家，也可以传入最多 50 个国家代码。欧元区请使用 EMU。

Python 示例传入了国家列表，它会变成请求中重复的 countries 参数。想要覆盖所有国家的日历时，把该参数从请求中去掉。保留日期范围，并先收集全部分页，再按 UTC 时间对发布项排序。

计算示例：2026 年 11 月 9 日至 13 日

对于 2026 年 11 月 9 日至 13 日，先数美国的条目：批发贸易、消费者价格、工资与收入、首次申请失业金人数、石油库存、公共财政和生产者价格，美国共 7 项。日本在同一日期范围内有家庭支出和国际收支 2 项。

再单独数英国的 GDP 条目。加上建筑业产出、商品和服务贸易、工业生产和服务业产出，英国在 2026 年 11 月 9 日至 13 日共 6 项。把各国的数量相加，就得到该日程的总数。

按日期顺序阅读 UTC 时间。2026 年 11 月 9 日，美国批发贸易在 15:00，日本家庭支出在 23:30，日本国际收支在 23:50。2026 年 11 月 10 日，美国消费者价格与工资与收入同在 13:30。2026 年 11 月 12 日，美国首次申请失业金人数在 13:30，石油库存在 17:00，公共财政在 19:00。美国生产者价格在 2026 年 11 月 13 日 13:30。

2026 年 11 月 9 日至 13 日最繁忙的一个小时是 11 月 12 日 07:00 UTC，英国的 6 项发布全部集中在这一刻。在排序后的日程中，这一组包含两个版本的 GDP，以及建筑业产出、商品和服务贸易、工业生产和服务业产出。