Browse all documentation

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/<iso3>.

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://api.narwhalapi.com. Each route below is an MCP tool of its own, with the same parameters.

What every account gets

WhatEvery account
Country profileOne Economics call
Inflation calculatorOne Economics call
Currency listOne 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_rate and minimum_wage are null for every country until a source for them is stored.
  • inflation is 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 value null and gives lower_bound and upper_bound.
  • GDP is the latest quarter at an annual rate where the country has quarterly GDP, and the latest year otherwise; date and note say 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_get_country_profile.

Parameters

ParameterWhereRequiredTypeMeaning
countrypathYesstring

Response fields

FieldTypeSentMeaning
countrystringAlways
alpha2stringAlways
numericstringAlways
namestringAlwaysName as our symbol list holds it.
currencyobjectAlwaysCurrency of the prices.
currency.codestringAlways
currency.namestringAlwaysName as our symbol list holds it.
currency.symbolstringAlwaysTicker on that exchange.
currency.decimalsintegerAlways
gdpobjectAlways
gdp.valuestringAlways
gdp.lower_boundstringOptional
gdp.upper_boundstringOptional
gdp.unitstringAlways
gdp.datestringAlways
gdp.sourceobjectAlways
gdp.source.publisherstringAlways
gdp.source.distributorstringOptional
gdp.notestringOptional
populationobjectAlways
population.valuestringAlways
population.lower_boundstringOptional
population.upper_boundstringOptional
population.unitstringAlways
population.datestringAlways
population.sourceobjectAlways
population.source.publisherstringAlways
population.source.distributorstringOptional
population.notestringOptional
inflationobjectAlways
inflation.valuestringAlways
inflation.lower_boundstringOptional
inflation.upper_boundstringOptional
inflation.unitstringAlways
inflation.datestringAlways
inflation.sourceobjectAlways
inflation.source.publisherstringAlways
inflation.source.distributorstringOptional
inflation.notestringOptional
policy_rateobjectAlways
policy_rate.valuestringAlways
policy_rate.lower_boundstringOptional
policy_rate.upper_boundstringOptional
policy_rate.unitstringAlways
policy_rate.datestringAlways
policy_rate.sourceobjectAlways
policy_rate.source.publisherstringAlways
policy_rate.source.distributorstringOptional
policy_rate.notestringOptional
credit_ratingobjectAlways
credit_rating.valuestringAlways
credit_rating.lower_boundstringOptional
credit_rating.upper_boundstringOptional
credit_rating.unitstringAlways
credit_rating.datestringAlways
credit_rating.sourceobjectAlways
credit_rating.source.publisherstringAlways
credit_rating.source.distributorstringOptional
credit_rating.notestringOptional
corporate_tax_rateobjectAlways
corporate_tax_rate.valuestringAlways
corporate_tax_rate.lower_boundstringOptional
corporate_tax_rate.upper_boundstringOptional
corporate_tax_rate.unitstringAlways
corporate_tax_rate.datestringAlways
corporate_tax_rate.sourceobjectAlways
corporate_tax_rate.source.publisherstringAlways
corporate_tax_rate.source.distributorstringOptional
corporate_tax_rate.notestringOptional
vat_rateobjectAlways
vat_rate.valuestringAlways
vat_rate.lower_boundstringOptional
vat_rate.upper_boundstringOptional
vat_rate.unitstringAlways
vat_rate.datestringAlways
vat_rate.sourceobjectAlways
vat_rate.source.publisherstringAlways
vat_rate.source.distributorstringOptional
vat_rate.notestringOptional
minimum_wageobjectAlways
minimum_wage.valuestringAlways
minimum_wage.lower_boundstringOptional
minimum_wage.upper_boundstringOptional
minimum_wage.unitstringAlways
minimum_wage.datestringAlways
minimum_wage.sourceobjectAlways
minimum_wage.source.publisherstringAlways
minimum_wage.source.distributorstringOptional
minimum_wage.notestringOptional
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/USA/profile"
Example response
{
  "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_get_inflation_calculator.

Parameters

ParameterWhereRequiredTypeMeaning
countrypathYesstring
amountqueryYesstring
fromqueryYesstring
toqueryNostring

Response fields

FieldTypeSentMeaning
countrystringAlways
amountstringAlways
fromstringAlways
tostringAlways
resultstringAlways
cumulative_inflation_percentstringAlways
from_indexobjectAlways
from_index.periodstringAlways
from_index.valuestringAlways
from_index.index_basestringAlwaysThe base the index is 100 (or its base value) at.
to_indexobjectAlways
to_index.periodstringAlways
to_index.valuestringAlways
to_index.index_basestringAlwaysThe base the index is 100 (or its base value) at.
sourceobjectOptional
source.publisherstringAlways
source.distributorstringAlways
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/economics/USA/inflation/calculator?amount=100&from=2020-01"
Example response
{
  "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_list_currencies.

Parameters

This route takes no parameters.

Response fields

FieldTypeSentMeaning
currencieslist of objectAlways
currencies[].codestringAlways
currencies[].numericstringAlways
currencies[].namestringAlwaysName as our symbol list holds it.
currencies[].symbolstringAlwaysTicker on that exchange.
currencies[].decimalsintegerAlways
currencies[].countrieslist of stringAlways
currencies[].sourcestringAlways
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/fx/currencies"
Example response
{
  "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_id. See Errors and credits for the shape and the credit headers. Failed requests are not charged.

CodeStatusMeaning
invalid_query400A parameter is missing, unknown, repeated or outside its range.
not_found404No 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_credits402Your credit balance is less than the request costs.
economics_unavailable503The stored data cannot answer right now. Not charged.

Was this page helpful?