Country data API reference
A country profile, an inflation calculator and the ISO 4217 currency list
Overview
Three small routes that answer questions people ask by name. The country profile puts one country's currency, ISO codes and latest headline figures in one call. The inflation calculator says what an amount from one month is worth in another. The currency list is the ISO 4217 list. Every request needs a Bearer key, and REST and MCP draw on one credit balance.
A country is its ISO 3166 alpha-3 code, such as USA or IDN. The profile copies no data: each figure is the newest value of the route that serves it (GDP, population, inflation, policy rate, credit rating), and carries its own unit, date and source, so you can tell a quarter from a year. The corporate tax rate is from Damodaran's table of corporate marginal tax rates, built from the PwC summaries (January 2026 update); it is also readable as the any-series source damodaran:corporate-tax-rate/.
The inflation calculator multiplies the amount by the consumer price index of the to month over the index of the from month, to four decimal places. The answer names both months and both index values, so the result can be checked by hand. Leave to out to use the newest month we hold.
Base URL: https:/. Each route below is an MCP tool of its own, with the same parameters.
What every account gets
| What | Every account |
|---|---|
| Country profile | One Economics call |
| Inflation calculator | One Economics call |
| Currency list | One Markets call |
See pricing for what a call costs. A request is charged at the price of its API unless a route says otherwise; the dividends, splits and registrations calendars are Companies data, $10 per 1,000 calls.
- A figure we do not hold for the country is null, never a guess.
vat_andrate minimum_are null for every country until a source for them is stored.wage inflationis null in months where no year-on-year rate exists, which is the case for the United States in the example here: the October 2025 index was never published.- A policy rate that is a range, such as the US federal funds target range, has
valuenull and giveslower_andbound upper_.bound - GDP is the latest quarter at an annual rate where the country has quarterly GDP, and the latest year otherwise;
dateandnotesay which. It is in the country's own currency, not converted. - The calculator uses the consumer price index the CPI route serves for the country, so it covers the countries and months that route covers. If the index changed base between the two months, the call is 404 not_found, because one index cannot be divided by another. Inflation of a month that is not yet published is not estimated.
- The currency list holds the codes in circulation. Withdrawn codes (such as BGN, HRK, CUC, SLL and ZWL) are not listed. Decimals are the ISO minor units. Symbols are the usual local sign, not part of ISO 4217.
- A country with no figures at all is 404 not_found and is not charged. These figures are republished from public sources, for analysis, not financial, investment, legal or tax advice.
Endpoints
Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.
Get Country Profile
GET /v1/economics/{country}/profile
MCP: tool economics_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
country | path | Yes | string |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
country | string | Always | |
alpha2 | string | Always | |
numeric | string | Always | |
name | string | Always | Name as our symbol list holds it. |
currency | object | Always | Currency of the prices. |
currency.code | string | Always | |
currency.name | string | Always | Name as our symbol list holds it. |
currency.symbol | string | Always | Ticker on that exchange. |
currency.decimals | integer | Always | |
gdp | object | Always | |
gdp.value | string | Always | |
gdp.lower_ | string | Optional | |
gdp.upper_ | string | Optional | |
gdp.unit | string | Always | |
gdp.date | string | Always | |
gdp.source | object | Always | |
gdp.source.publisher | string | Always | |
gdp.source.distributor | string | Optional | |
gdp.note | string | Optional | |
population | object | Always | |
population.value | string | Always | |
population.lower_ | string | Optional | |
population.upper_ | string | Optional | |
population.unit | string | Always | |
population.date | string | Always | |
population.source | object | Always | |
population.source.publisher | string | Always | |
population.source.distributor | string | Optional | |
population.note | string | Optional | |
inflation | object | Always | |
inflation.value | string | Always | |
inflation.lower_ | string | Optional | |
inflation.upper_ | string | Optional | |
inflation.unit | string | Always | |
inflation.date | string | Always | |
inflation.source | object | Always | |
inflation.source.publisher | string | Always | |
inflation.source.distributor | string | Optional | |
inflation.note | string | Optional | |
policy_ | object | Always | |
policy_ | string | Always | |
policy_ | string | Optional | |
policy_ | string | Optional | |
policy_ | string | Always | |
policy_ | string | Always | |
policy_ | object | Always | |
policy_ | string | Always | |
policy_ | string | Optional | |
policy_ | string | Optional | |
credit_ | object | Always | |
credit_ | string | Always | |
credit_ | string | Optional | |
credit_ | string | Optional | |
credit_ | string | Always | |
credit_ | string | Always | |
credit_ | object | Always | |
credit_ | string | Always | |
credit_ | string | Optional | |
credit_ | string | Optional | |
corporate_ | object | Always | |
corporate_ | string | Always | |
corporate_ | string | Optional | |
corporate_ | string | Optional | |
corporate_ | string | Always | |
corporate_ | string | Always | |
corporate_ | object | Always | |
corporate_ | string | Always | |
corporate_ | string | Optional | |
corporate_ | string | Optional | |
vat_ | object | Always | |
vat_ | string | Always | |
vat_ | string | Optional | |
vat_ | string | Optional | |
vat_ | string | Always | |
vat_ | string | Always | |
vat_ | object | Always | |
vat_ | string | Always | |
vat_ | string | Optional | |
vat_ | string | Optional | |
minimum_ | object | Always | |
minimum_ | string | Always | |
minimum_ | string | Optional | |
minimum_ | string | Optional | |
minimum_ | string | Always | |
minimum_ | string | Always | |
minimum_ | object | Always | |
minimum_ | string | Always | |
minimum_ | string | Optional | |
minimum_ | string | Optional |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/economics/USA/profile"{
"country": "USA",
"alpha2": "US",
"numeric": "840",
"name": "United States",
"currency": {
"code": "USD",
"name": "US Dollar",
"symbol": "$",
"decimals": 2
},
"gdp": {
"value": "33010036000000",
"unit": "USD",
"date": "2026-Q3",
"source": {
"publisher": "U.S. Bureau of Economic Analysis"
},
"note": "Quarterly GDP at an annual rate."
},
"population": {
"value": "341784857",
"unit": "person",
"date": "2025",
"source": {
"publisher": "UN Population Division (World Population Prospects), national statistical offices, Eurostat, U.S. Census Bureau, Pacific Community: mid-year estimates",
"distributor": "World Bank, World Development Indicators (CC BY 4.0)"
}
},
"inflation": null,
"policy_rate": {
"value": null,
"lower_bound": "3.75",
"upper_bound": "4.00",
"unit": "percent",
"date": "2026-09-17",
"source": {
"publisher": "federal_reserve"
}
},
"credit_rating": {
"value": "Aa1",
"unit": "Moody's scale",
"date": "2026-01",
"source": {
"publisher": "Aswath Damodaran, NYU Stern, country risk table (Moody's scale)"
}
},
"corporate_tax_rate": {
"value": "25.63",
"unit": "percent",
"date": "2026-01",
"source": {
"publisher": "Damodaran, corporate marginal tax rates by country (PwC, January 2026 update)"
}
},
"vat_rate": null,
"minimum_wage": null
}Get Inflation Calculator
GET /v1/economics/{country}/inflation/calculator
MCP: tool economics_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
country | path | Yes | string | |
amount | query | Yes | string | |
from | query | Yes | string | |
to | query | No | string |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
country | string | Always | |
amount | string | Always | |
from | string | Always | |
to | string | Always | |
result | string | Always | |
cumulative_ | string | Always | |
from_ | object | Always | |
from_ | string | Always | |
from_ | string | Always | |
from_ | string | Always | The base the index is 100 (or its base value) at. |
to_ | object | Always | |
to_ | string | Always | |
to_ | string | Always | |
to_ | string | Always | The base the index is 100 (or its base value) at. |
source | object | Optional | |
source.publisher | string | Always | |
source.distributor | string | Always |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/economics/USA/inflation/calculator?amount=100&from=2020-01"{
"country": "USA",
"amount": "100",
"from": "2020-01",
"to": "2026-10",
"result": "130.8329",
"cumulative_inflation_percent": "30.8329",
"from_index": {
"period": "2020-01",
"value": "257.971",
"index_base": "1982-84=100"
},
"to_index": {
"period": "2026-10",
"value": "337.511",
"index_base": "1982-84=100"
}
}List Currencies
GET /v1/fx/currencies
The example shows four of the currencies, and only some of the countries of the euro and the dollar. The real answer lists every currency by code, with every country that uses it.
MCP: tool fx_.
Parameters
This route takes no parameters.
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
currencies | list of object | Always | |
currencies[].code | string | Always | |
currencies[].numeric | string | Always | |
currencies[].name | string | Always | Name as our symbol list holds it. |
currencies[].symbol | string | Always | Ticker on that exchange. |
currencies[].decimals | integer | Always | |
currencies[].countries | list of string | Always | |
currencies[].source | string | Always |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/fx/currencies"{
"currencies": [
{
"code": "EUR",
"numeric": "978",
"name": "Euro",
"symbol": "€",
"decimals": 2,
"countries": [
"DEU",
"FRA",
"ITA"
],
"source": "ISO 4217 (SIX Group, the maintenance agency), country use from ISO 3166-1"
},
{
"code": "IDR",
"numeric": "360",
"name": "Rupiah",
"symbol": "Rp",
"decimals": 2,
"countries": [
"IDN"
],
"source": "ISO 4217 (SIX Group, the maintenance agency), country use from ISO 3166-1"
},
{
"code": "JPY",
"numeric": "392",
"name": "Yen",
"symbol": "¥",
"decimals": 0,
"countries": [
"JPN"
],
"source": "ISO 4217 (SIX Group, the maintenance agency), country use from ISO 3166-1"
},
{
"code": "USD",
"numeric": "840",
"name": "US Dollar",
"symbol": "$",
"decimals": 2,
"countries": [
"USA",
"ECU",
"PAN"
],
"source": "ISO 4217 (SIX Group, the maintenance agency), country use from ISO 3166-1"
}
]
}Errors
Errors use the shared problem shape with a request_. See Errors and credits for the shape and the credit headers. Failed requests are not charged.
| Code | Status | Meaning |
|---|---|---|
invalid_ | 400 | A parameter is missing, unknown, repeated or outside its range. |
not_ | 404 | No consumer price index is held for the country and period, the index changed base between the two months, or no profile figure is held for the country. Not charged. |
insufficient_ | 402 | Your credit balance is less than the request costs. |
economics_ | 503 | The stored data cannot answer right now. Not charged. |
Was this page helpful?