為報導查詢下週發布的數據和最新數值

取得報導所需的最新數值

每個序列都有對應的國家端點：/v1/economics/{country}/inflation、/cpi、/unemployment 和 /gdp-growth。不帶 period 參數時回傳最新一期。下面的請求查詢美國通膨。

curl -s -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/USA/inflation"

{
  "country": "USA",
  "period": "2026-09",
  "year_over_year": "3.7",
  "month_over_month": "0.6",
  "year_to_date": "4.0",
  "released_on": "2026-10-14"
}

這份回應裡有兩個含義不同的日期。period 是該數值所衡量的參考月份，即 2026-09，也就是 9 月。released_on 是數值公布的日期，即 2026-10-14。10 月發稿的報導應寫成：截至 9 月的一年裡，物價上漲了 3.7%。如果取 10 月的發布日期，月份就錯了。

三個變化率欄位是各自獨立的指標：year_over_year 為 3.7，month_over_month 為 0.6，year_to_date 為 4.0，單位均為百分比。每個欄位回答的問題不同，所以在行文中要點明引用的是哪一個。

其他序列的同類呼叫

GDP 成長使用季度作為 period，所以 2026-Q3 表示第三季。寫與上一季相比的成長時用 quarter_over_quarter，與去年同期相比時用 year_over_year。

把新數值與舊數值並列

日曆中的每項發布都帶有 values[].previous，即新發布將與之比較的數值。發布當天，報導可以引用日曆中的 previous 值，以及公布後從國家端點取得的新值。請核對日曆數值的 transformation（例如 year_over_year），確保兩個數字屬於同一類。

產生簡報：本週發布數據加最新數值

該腳本向日曆請求 11 月 9 日至 13 日的美國數據，按紐約時間列印每項發布，再取得通膨、失業率和 GDP 的最新數值，並用文字寫出參考期。

1. 取得 API 金鑰 在註冊頁取得 API 金鑰，並儲存在 NARWHAL_API_KEY 中。
2. 列出本週發布 GET /v1/economics/calendar 不會按時間順序回傳發布數據。腳本保留帶有 at 時間的項目，排序後轉換為發布機構的 timezone。
3. 取得各序列的最新數值 每個序列呼叫一次。say 函式把 2026-09 轉成 2026 年 9 月，把 2026-Q3 轉成 2026 年第三季，因此句子用的是 period，絕不會用 released_on 的月份。
   Python，報導用的每週簡報

   import os
   from datetime import datetime
   from zoneinfo import ZoneInfo
   import requests
   
   API = "https://api.narwhalapi.com"
   HEADERS = {"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}
   MONTHS = ["January", "February", "March", "April", "May", "June", "July",
             "August", "September", "October", "November", "December"]
   QUARTERS = {"Q1": "first", "Q2": "second", "Q3": "third", "Q4": "fourth"}
   
   
   def get(path, **params):
       r = requests.get(f"{API}/v1/economics/{path}", headers=HEADERS, params=params, timeout=10)
       r.raise_for_status()
       return r.json()
   
   
   def say(period):
       year, part = period.split("-")
       if part in QUARTERS:
           return f"the {QUARTERS[part]} quarter of {year}"
       return f"{MONTHS[int(part) - 1]} {year}"
   
   
   week = get("calendar", countries="USA", start_date="2026-11-09", end_date="2026-11-13", limit=100)
   for x in sorted((x for x in week["releases"] if "at" in x), key=lambda x: x["at"]):
       local = datetime.fromisoformat(x["at"].replace("Z", "+00:00")).astimezone(ZoneInfo(x["timezone"]))
       print(local.strftime("%a %d %b %H:%M"), x["name"], "|", x.get("period", "no period"))
   
   for series in ("inflation", "unemployment", "gdp-growth"):
       d = get(f"USA/{series}")
       figures = {k: v for k, v in d.items() if k not in ("country", "period", "released_on")}
       print(series, figures, "for", say(d["period"]), "released", d["released_on"])

Mon 09 Nov 10:00 Wholesale trade | 2026-09
Tue 10 Nov 08:30 Wages and earnings | 2026-10
Tue 10 Nov 08:30 Consumer prices | 2026-10
Thu 12 Nov 08:30 Jobless claims | 2026-11-07
Thu 12 Nov 12:00 Petroleum inventories | no period
Thu 12 Nov 14:00 Public finances | 2026-10
Fri 13 Nov 08:30 Producer prices | 2026-10
inflation {'year_over_year': '3.7', 'month_over_month': '0.6', 'year_to_date': '4.0'} for September 2026 released 2026-10-14
unemployment {'rate': '4.2'} for September 2026 released 2026-10-02
gdp-growth {'year_over_year': '2.1', 'quarter_over_quarter': '0.832'} for the third quarter of 2026 released 2026-10-29

11 月 10 日（週二）發布的消費者物價數據對應 2026-10，是 10 月的數值。在它公布之前，最新的通膨數值仍是 released_on 為 2026-10-14 的 9 月數據。公布之後，無須修改請求，端點就會回傳新的一期。

正確寫出參考期

• 月份或季度要取自 period，絕不要取自 released_on。通膨數值在 10 月公布，但反映的是 9 月。
• 要說明引用的是哪種比較：year_over_year、month_over_month、year_to_date 或 quarter_over_quarter。欄位名稱就是標籤。
• 在「數據於當日公布」這類句子裡使用 released_on，讀者就能看出數值有多新。

為什麼日曆中的期間與最新數值的期間不同？

日曆中的 period 是該項發布將要涵蓋的月份，而最新數值是已經公布的最近一次發布。在簡報輸出裡，日曆列出的消費者物價對應 2026-10，而通膨端點回傳的是 2026-09。在寫某個數值是最新之前，請先核對兩者。

inflation 和 cpi 端點有什麼差別？

/inflation 回傳以百分比表示的變化率。/cpi 在 value 中回傳指數水準，在 index_base 中回傳基期。標題裡引用變化率，只有當報導本身講指數時才引用指數水準。

所有國家的失業率都按同一種期間發布嗎？

不是。美國的失業率回傳的是 2026-09，是一個月；而德國回傳的是 2026-Q2，是一個季度。要在同一句話裡比較數值，請先查看每個國家的 period。