Find next week's releases and the latest figure for a story

Get the latest figure for the story

Each series has a country endpoint: /v1/economics/{country}/inflation, /cpi, /unemployment and /gdp-growth. Without a period parameter they return the latest period. This request asks for United States inflation.

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"
}

Two dates sit in this response and they mean different things. period is the reference month the figure measures, 2026-09, which is September. released_on is the day the figure came out, 2026-10-14. A story filed in October says prices rose 3.7 percent in the year to September. The October release date would give the wrong month.

The three rate fields are separate measures. year_over_year is 3.7, month_over_month is 0.6 and year_to_date is 4.0, all in percent. Name the one you quote in the sentence, since each answers a different question.

The same call for the other series

GDP growth uses a quarter for period, so 2026-Q3 means the third quarter. Use quarter_over_quarter when you write about growth from the previous quarter and year_over_year when you compare with the same quarter a year earlier.

Put the new number next to the old one

Each release in the calendar lists values[].previous, the figure a new release will be compared with. On the day of a release, a story can quote the previous value from the calendar and the new value from the country endpoint after it publishes. Check transformation on the calendar value, such as year_over_year, so the two numbers are the same kind of figure.

Build a briefing: the week's releases plus the latest figures

The script asks the calendar for the United States from 9 to 13 November, prints each release in New York time, then fetches the latest inflation, unemployment and GDP figures and writes the reference period in words.

1. Get an API key Get an API key at signup and keep it in NARWHAL_API_KEY.
2. List the week GET /v1/economics/calendar does not return the releases in time order. The script keeps those with an at time, sorts them and converts to the publisher's timezone.
3. Fetch each latest figure One call per series. The say function turns 2026-09 into September 2026 and 2026-Q3 into the third quarter of 2026, so the sentence uses period and never the month of released_on.
   Python, a weekly briefing for a story

   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

The Consumer prices release on Tuesday 10 November covers 2026-10, so it is the October figure. Until it is out, the newest inflation figure is still the September one with released_on 2026-10-14. After it publishes, the endpoint returns the new period without any change to your request.

Write the reference period correctly

• Take the month or quarter from period, never from released_on. The inflation figure came out in October and describes September.
• Say which comparison you quote: year_over_year, month_over_month, year_to_date or quarter_over_quarter. The field name is the label.
• Use released_on for a line such as figures published on that day, so readers see how fresh the number is.

Why does the calendar period differ from the latest figure?

The calendar period is the month a release will cover, and the latest figure is the last release already published. In the briefing output the calendar lists consumer prices for 2026-10 while the inflation endpoint returns 2026-09. Check both before writing that a figure is the newest.

What is the difference between the inflation and cpi endpoints?

/inflation returns rates of change in percent. /cpi returns the index level in value and the base in index_base. Quote the rate in a headline and the index level only when the story is about the index itself.

Do all countries report unemployment for the same kind of period?

No. The United States returned 2026-09 for unemployment, a month, while Germany returned 2026-Q2, a quarter. Read period for every country before you compare figures in one sentence.