記事のために、来週の発表予定と最新値を調べる

記事で使う最新値を取得する

各系列には国別エンドポイントがあります。/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月までの1年間で3.7%上昇したと書きます。10月の発表日から月を取ると誤りになります。

三つの変化率フィールドは別々の指標です。year_over_year は3.7、month_over_month は0.6、year_to_date は4.0で、いずれも単位はパーセントです。それぞれ答える問いが違うので、引用する指標は文中で明示してください。

他の系列での同じ呼び出し

GDP成長率では period が四半期になるので、2026-Q3 は第3四半期を意味します。前期からの成長を書くときは quarter_over_quarter、1年前の同じ四半期と比べるときは year_over_year を使います。

新しい数値を前回の数値と並べる

カレンダーの各発表には values[].previous があり、新しい発表と比較される前回の数値です。発表当日の記事では、カレンダーの previous の値と、公表後に国別エンドポイントから得た新しい値を並べて引用できます。2つの数値が同じ種類になるよう、カレンダー値の transformation（year_over_year など）を確認してください。

ブリーフィングを作る：今週の発表予定と最新値

このスクリプトは、カレンダーから11月9日〜13日の米国分を取得し、各発表をニューヨーク時間で出力します。続いてインフレ率、失業率、GDPの最新値を取得し、基準期間を文章で書き出します。

1. APIキーを取得 サインアップ で API キーを取得し、NARWHAL_API_KEY に保存します。
2. 今週の発表を一覧にする GET /v1/economics/calendar は発表を時刻順に返しません。スクリプトは at の時刻を持つものだけを残して並べ替え、発表元の timezone に変換します。
3. 各系列の最新値を取得する 系列ごとに1回呼び出します。say 関数は 2026-09 を2026年9月に、2026-Q3 を2026年第3四半期に変換するので、文には 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（四半期）で返りました。1つの文で数値を比べる前に、国ごとに period を確認してください。