Calculate CPI year over year and month over month

Get CPI rates with the API

1. Set up your API key Get a free key and keep it in an environment variable called NARWHAL_API_KEY. Requests use the base URL https://api.narwhalapi.com and the header Authorization: Bearer YOUR_KEY; REST and MCP share the same key.
2. Read the ready-made inflation rates Use the inflation endpoint for year_over_year, month_over_month, year_to_date and released_on. The rates are decimal strings expressed in percent, so use the returned rate directly when you need the headline figure for its period.
   curl, the ready-made rates

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

3. Calculate a rate from index levels The CPI observations endpoint returns period and value rows with index_base set to 1982-84=100. This script looks up the previous month and the same month a year earlier by period, then calculates a rate when the required observations are available.
   Python, month over month from index levels

   import os
   import requests
   
   r = requests.get("https://api.narwhalapi.com/v1/economics/USA/cpi/observations",
                    params={"start": "2025-09", "limit": 24},
                    headers={"Authorization": f"Bearer {os.environ['NARWHAL_API_KEY']}"}, timeout=10)
   r.raise_for_status()
   cpi = {o["period"]: float(o["value"]) for o in r.json()["observations"]}
   
   latest = max(cpi)                                    # "2026-09"
   year, month = latest.split("-")
   prev_month = f"{year}-{int(month) - 1:02d}" if month != "01" else f"{int(year) - 1}-12"
   prev_year = f"{int(year) - 1}-{month}"
   
   print("MoM %.2f%%" % ((cpi[latest] / cpi[prev_month] - 1) * 100))
   print("YoY %.2f%%" % ((cpi[latest] / cpi[prev_year] - 1) * 100) if prev_year in cpi else "year-ago month not in range")

4. Read the periods returned A start date before your plan window moves up to the window's first day without an error, so the response can begin later than requested. Free includes the last 12 months, Basic includes 5 years and Pro includes full history; the first returned period tells you where your calculation can begin.

For month over month, divide this month's CPI by last month's CPI, subtract one and multiply by 100. For year over year, use the same month a year earlier as the denominator. On Free, that year-ago level is outside the window, so use year_over_year from the inflation endpoint, which returns both headline rates on every plan.

For a custom span, such as 3 months or since a date, divide the ending index by the starting index and subtract one. Multiply by 100 for a percent result. Choose the starting period to match the comparison you want, and use index levels when the ready-made monthly or annual rate does not match that span.

A 403 plan_upgrade_required response applies when the whole requested range ends before the window, or when you request a single date or period outside it. An early start date alone does not cause that response.

Calculate CPI changes in a sheet or read the rates without code

In Google Sheets, format column A as Plain text through Format, Number, Plain text before pasting periods. Sheets can turn 2026-09 into a date, which makes a text lookup miss. Put the period text in column A and its CPI value in column B. Use the same period-and-value arrangement for the formula in Excel.

=VLOOKUP("2026-09",A:B,2,FALSE)/VLOOKUP("2026-08",A:B,2,FALSE)-1

Format the result as percent. Look up each month by its period rather than assuming adjacent rows are adjacent months: a missing observation can otherwise shift the comparison. Year over year needs the same month a year earlier, so a Free key's levels cannot supply that calculation. Use the ready-made year_over_year value instead. The Narwhal inflation pages also show the rates for each country.

To calculate September 2026 year to date in a sheet, look up September 2026 and December 2025 by period and use those levels in the same division. The denominator changes to the December level; the subtraction and percent formatting stay the same.

Choose the CPI option for your calculation

Why does my CPI calculation differ from the published rate?

Publishers round the index and the rate separately, so a calculation from index levels can differ in the second decimal. For September 2026, dividing 336.940 by 334.980 produces the monthly rate in the worked example. The Python calculation displays two decimal places; the API's monthly rate uses one decimal place. Keep the calculation and the returned rate's precision in mind when comparing those figures.

What if a CPI month is missing?

Never interpolate a missing month. For the September 2026 example, the US series begins in November 2025, and the October 2025 observation is absent from the series. Do not assume the response contains 13 contiguous monthly rows. A wider request does not make an absent observation available; keep lookups tied to the period you need.

For the September 2026 example, the Python script prints the monthly rate to two decimal places and, on Free, year-ago month not in range. Basic or Pro supplies the year-over-year calculation for that example. Use the inflation endpoint for the headline annual rate when the year-ago level is unavailable.

Can I annualise a monthly CPI rate?

Yes. Use (1 + MoM)^12 - 1, with MoM expressed as a decimal, to turn a monthly rate into an annual one. For September 2026, the monthly calculation in the worked example gives the annualised result listed there. Year over year uses the actual index from the same month a year earlier, so keep that calculation separate from annualising a monthly rate.

Worked example: US CPI for September 2026

Start with September 2026 CPI of 336.940 and August 2026 CPI of 334.980. Divide the September level by the August level, subtract one and multiply by 100 to calculate month over month. For year to date, use December 2025 CPI of 324.054 as the denominator and apply the same formula.

The inflation response for September 2026 has released_on set to 2026-10-14. Read its year_over_year field for the annual headline rate; the December comparison above is year to date. If CPI falls over your chosen span, the calculated rate is negative and describes a fall in prices.