在发布之前查看数据的发布时间、所属期间和前值

查询某个国家的一条数据发布

用 GET /v1/economics/calendar 按国家和日期向日历发起请求。下面的请求查询日本 11 月 20 日。

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/calendar?countries=JPN&start_date=2026-11-20&end_date=2026-11-20&limit=100"

{
  "releases": [
    {
      "release_id": "6c00d274-da35-4ed4-bcc1-574101544a03",
      "revision": 3,
      "country": "JPN",
      "series_id": "jpn-consumer-prices",
      "name": "Consumer prices",
      "topic": "consumer_prices",
      "family": "prices",
      "period": "2026-10",
      "status": "scheduled",
      "at": "2026-11-19T23:30:00Z",
      "timezone": "Asia/Tokyo",
      "values": [
        {
          "measure": "core_core_cpi_yoy",
          "concept": "cpi_ex_fresh_food_energy",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.4",
          "not_seasonally_adjusted": true
        },
        {
          "measure": "core_cpi_yoy",
          "concept": "cpi_ex_fresh_food",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.1",
          "not_seasonally_adjusted": true
        },
        {
          "measure": "cpi_mom",
          "concept": "cpi",
          "unit": "percent",
          "transformation": "month_over_month",
          "previous": "0.4"
        },
        {
          "measure": "cpi_yoy",
          "concept": "cpi",
          "unit": "percent",
          "transformation": "year_over_year",
          "previous": "2.1",
          "not_seasonally_adjusted": true
        }
      ]
    }
  ],
  "next_cursor": null
}

这条发布是日本的消费者物价，period 为 2026-10，数据覆盖 10 月。at 为 2026-11-19T23:30:00Z，timezone 为 Asia/Tokyo。values 中每一项都有 measure 和 previous 值；cpi_yoy 的前值是 2.1，cpi_mom 的前值是 0.4。这些数值是字符串，比较之前请先转换成数字。

transformation 说明数值是如何得出的：cpi_yoy 为 year_over_year，cpi_mom 为 month_over_month。四项指标中有三项带有 not_seasonally_adjusted: true，所以在拿预测值与前值比较之前，请先检查这个标记。

请求指定的是 11 月 20 日，但 at 按 UTC 是 11 月 19 日。日期窗口按发布方的当地日历计算，而 UTC 的 23:30 在东京是次日早上 08:30。

挑出接下来的高关注度数据发布并转换时间

日历没有重要性评级，所以哪些算高关注度由你自己决定。下面的脚本使用一份由 topic 值组成的关注清单，只保留仍为 scheduled 且带有 at 时间的发布，排序后取前三条。

1. 设置关注清单和你自己的时区 把你交易的主题放进一个集合。脚本关注消费者物价、GDP、劳动力、就业和工资，并换算成交易员所在的时区 America/New_York。
2. 请求一段时间窗口 指定一个国家和一段日期范围。脚本取日本 11 月 16 日至 29 日，limit 为 100。
3. 过滤、排序与转换 datetime.fromisoformat 读取 UTC 时间戳，astimezone 把它转换成 timezone 字段给出的发布方时区和交易员所在的时区。前值取自 values[].previous。
   Python，接下来关注的三条数据发布

   import os
   from datetime import datetime
   from zoneinfo import ZoneInfo
   import requests
   
   BASE = "https://api.narwhalapi.com"
   
   WATCH = {"consumer_prices", "gdp", "labour_force", "employment", "wages"}
   MY_TZ = ZoneInfo("America/New_York")
   
   r = requests.get(
       f"{BASE}/v1/economics/calendar",
       params={"countries": "JPN", "start_date": "2026-11-16", "end_date": "2026-11-29", "limit": 100},
       headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"},
       timeout=10,
   )
   r.raise_for_status()
   
   picked = [
       x for x in r.json()["releases"]
       if x.get("topic") in WATCH and x["status"] == "scheduled" and "at" in x
   ]
   for x in sorted(picked, key=lambda x: x["at"])[:3]:
       utc = datetime.fromisoformat(x["at"].replace("Z", "+00:00"))
       local = utc.astimezone(ZoneInfo(x["timezone"]))
       mine = utc.astimezone(MY_TZ)
       prev = ", ".join(f"{v['measure']} {v['previous']}" for v in x["values"] if "previous" in v)
       print(x["name"], x["period"])
       print("  UTC  ", utc.strftime("%a %d %b %H:%M"))
       print("  Tokyo", local.strftime("%a %d %b %H:%M"))
       print("  NYC  ", mine.strftime("%a %d %b %H:%M"))
       print("  previous:", prev or "none listed")

GDP 2026-Q3
  UTC   Sun 15 Nov 23:50
  Tokyo Mon 16 Nov 08:50
  NYC   Sun 15 Nov 18:50
  previous: none listed
Consumer prices 2026-10
  UTC   Thu 19 Nov 23:30
  Tokyo Fri 20 Nov 08:30
  NYC   Thu 19 Nov 18:30
  previous: core_core_cpi_yoy 2.4, core_cpi_yoy 2.1, cpi_mom 0.4, cpi_yoy 2.1
Wages and earnings 2026-09
  UTC   Tue 24 Nov 23:30
  Tokyo Wed 25 Nov 08:30
  NYC   Tue 24 Nov 18:30
  previous: average_cash_earnings_yoy 3.9, real_wages_yoy 1.6

GDP 这一行在 UTC 下显示为 Sun 15 Nov 23:50，尽管窗口从 11 月 16 日开始，因为它在东京是 11 月 16 日周一 08:50。它的前值一行显示「none listed」，是因为这条 GDP 发布的 values 列表为空。只要没有 previous，脚本就输出一个占位符，所以缺少一个数值不会使循环中断。

同一时刻在三个时钟上的读数

东京比 UTC 快 9 小时，23:30 加 9 小时就是次日 08:30。那一天纽约比 UTC 慢 5 小时，23:30 减 5 小时就是 18:30。脚本使用 zoneinfo，它会自动应用夏令时规则，所以无需保存偏移量。

稍后再次读取同一条发布

每条发布都有一个 release_id。GET /v1/economics/calendar/{release_id} 会返回这一条发布，并多出 version 和 observed_at 两个字段，后者表示 Narwhal 最近一次在发布方日历中看到这条发布的时间。用它来刷新你正在关注的那条发布的行，而不必下载整个窗口的数据。

数据公布后，status 会从 scheduled 变为 published，此时数值里可以在 previous 之外带有 actual。有些发布还带有 stage，例如 flash、advance、preliminary 或 final。把它显示在名称旁边，免得把初步估计误当作最终值。

日历会按重要性给数据发布排序吗？

不会。发布带有 prices、labour 或 gdp 之类的 family，以及 consumer_prices 之类的 topic，但没有评级。请用这两个字段构建关注清单，并使用 .get("topic")，因为有些发布没有 topic。

为什么有些数据发布没有前值？

values 始终存在，但可能是空列表，某项指标也可能没有 previous。上面的日本 GDP 发布就是空列表。当一次发布修订了此前的数字时，previous_revised_from 保存被替换的数字。

如果某条发布没有确切时间怎么办？

这类发布没有 at，而是带有 date、between 或 by 之一。脚本需要时间戳才能转换，所以会跳过它们。如果你也想看到这些行，就输出 date，并把时间标为未知，不要凭空猜一个。