Browse all documentation

Sheet links

Every address that answers as a table, how the table is built, what a link costs and what a cell shows when something is wrong.

A sheet link is a Narwhal address that answers with a table a spreadsheet can read. It is a normal GET address with format=csv and a Sheets key at the end.

Address
https://api.narwhalapi.com/v1/fx/rates/USD?currencies=EUR,IDR&format=csv&key=YOUR_SHEETS_KEY
Answer
currency,rate,timestamp,stale
EUR,0.90718,2026-11-15T16:00:00Z,false
IDR,18222.7,2026-11-15T16:00:00Z,false

Parameters

ParameterRequiredMeaning
format=csvyesAnswer as a table.
keyyesA Sheets key from Team and keys in your dashboard. An API key is refused here.
the route's ownas the route saysThe same parameters as the JSON call, for example start, end, currencies, countries.

Addresses

Replace the words in braces. Country is a three-letter code such as USA.

DataAddress after https://api.narwhalapi.com
Holidays in a year/v1/calendars/holidays/{country}/{year}
Next holiday/v1/calendars/holidays/{country}/next
Release calendar/v1/economics/calendar
CPI, latest and history/v1/economics/{country}/cpi, /cpi/observations
Inflation/v1/economics/{country}/inflation, /inflation/observations
GDP/v1/economics/{country}/gdp, /gdp/observations
GDP growth/v1/economics/{country}/gdp-growth, /gdp-growth/observations
Unemployment/v1/economics/{country}/unemployment, /unemployment/observations
Labour force participation/v1/economics/{country}/labour-force-participation, /observations
Trade/v1/economics/{country}/trade, /trade/observations
Any series/v1/economics/series/{series_id}/observations
Policy rate/v1/economics/{country}/central-bank/policy-rate, /policy-rate/history
Rate decisions/v1/economics/{country}/central-bank/decisions
Central bank reserves/v1/economics/{country}/central-bank/reserves
Equity risk premium, all countries/v1/economics/equity-risk-premium
Equity risk premium, one country/v1/economics/{country}/equity-risk-premium, /history
Commodity prices, all/v1/commodities/spot
One commodity/v1/commodities/spot/{commodity}/{currency}, /bars
Exchange rates/v1/fx/rates/{base}, /observations, /bars
Rate decision odds/v1/predictions/policy-paths/{authority}, /history

How the table is built

  • One header row, then one row per item. A call that returns one thing gives one row.
  • A nested field becomes a column with a dot, such as value.actual.
  • A list of plain values is joined with ;.
  • An empty value is an empty cell. True and false are true and false.
  • Numbers keep the exact text the API sends.
  • The release calendar gives one row per release, sorted by time. value_count says how many figures a release has; the row shows the first.
  • A call with no rows gives an empty answer.

What a link costs

A link is the address with your key. Its first load on a day costs what that call normally costs. Every other load of the same link that day is free. Days change at midnight UTC. Changing anything in the address makes a new link.

What a cell shows when something is wrong

The cell shows one line. The answer has HTTP status 200 so a spreadsheet displays it; the real status is in the x-narwhal-status header.

Line in the cellReal status
Narwhal: this Sheets key is switched off or not valid. Copy a new link from https://narwhalapi.com/dashboard.401
Narwhal: this is an API key, not a Sheets key. Make a Sheets key at https://narwhalapi.com/dashboard and use it in the link.401
Narwhal: a Sheets key reads data routes only, and the link must end in format=csv.403
Narwhal: out of credit. Add credit at https://narwhalapi.com/dashboard and refresh this sheet.402
Narwhal: too many requests. This sheet will update on its next refresh.429
Narwhal: bad parameter. (what is wrong)400 or 422

Next

Was this page helpful?