---
title: "Country data API reference | Narwhal API"
description: "One country's currency and latest headline figures in one call, what an amount is worth in another month by CPI, and the ISO 4217 currency list, by REST and MCP."
url: "https://narwhalapi.com/docs/api/country-data"
---

# 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

| What | Every account |
| --- | --- |
| Country profile | One Economics call |
| Inflation calculator | One Economics call |
| Currency list | One Markets call |

See [pricing](https://narwhalapi.com/pricing.md) 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` is the standard rate of value added tax or goods and services tax in percent, with the date of the record it comes from. The European Union Member States come from the European Commission's Taxes in Europe Database; 13 other countries come from their national tax authority, and `source.publisher` names which. A country with no national VAT or GST, such as the United States, has `vat_rate` null. Each rate is also a series, `vat:standard-rate/<iso3>`.
- `minimum_wage` is the newest statutory minimum wage in the unit its publisher states, so `unit` says the currency and whether it is per hour, day, week, month or year; nothing is converted, and series are never mixed. The profile prefers Eurostat's monthly figure in the national currency, then the OECD's monthly figure, the ILO's monthly figure, and then the OECD's hourly, daily, weekly and annual figures. Every series is also readable on its own: `eurostat:minimum-wage-monthly-nac/<iso3>` and `eurostat:minimum-wage-monthly-eur/<iso3>` (twice a year, the period 2026-01 is the first semester), `oecd:minimum-wage-nominal-hourly`, `-daily`, `-weekly`, `-monthly` and `-annual`, `oecd:minimum-wage-real-hourly-usd-ppp`, `-annual-usd-ppp`, `-hourly-usd-exc` and `-annual-usd-exc`, and `ilo:minimum-wage-monthly-lcu/<iso3>`. A country with no national minimum wage, such as Denmark or Sweden, has `minimum_wage` null.
- `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

| Parameter | Where | Required | Type | Meaning |
| --- | --- | --- | --- | --- |
| `country` | path | Yes | string | ISO 3166 alpha-3 country code, for example DEU. |

#### 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_bound` | string | Optional |  |
| `gdp.upper_bound` | 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_bound` | string | Optional |  |
| `population.upper_bound` | 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_bound` | string | Optional |  |
| `inflation.upper_bound` | 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_rate` | object | Always |  |
| `policy_rate.value` | string | Always |  |
| `policy_rate.lower_bound` | string | Optional |  |
| `policy_rate.upper_bound` | string | Optional |  |
| `policy_rate.unit` | string | Always |  |
| `policy_rate.date` | string | Always |  |
| `policy_rate.source` | object | Always |  |
| `policy_rate.source.publisher` | string | Always |  |
| `policy_rate.source.distributor` | string | Optional |  |
| `policy_rate.note` | string | Optional |  |
| `credit_rating` | object | Always |  |
| `credit_rating.value` | string | Always |  |
| `credit_rating.lower_bound` | string | Optional |  |
| `credit_rating.upper_bound` | string | Optional |  |
| `credit_rating.unit` | string | Always |  |
| `credit_rating.date` | string | Always |  |
| `credit_rating.source` | object | Always |  |
| `credit_rating.source.publisher` | string | Always |  |
| `credit_rating.source.distributor` | string | Optional |  |
| `credit_rating.note` | string | Optional |  |
| `corporate_tax_rate` | object | Always |  |
| `corporate_tax_rate.value` | string | Always |  |
| `corporate_tax_rate.lower_bound` | string | Optional |  |
| `corporate_tax_rate.upper_bound` | string | Optional |  |
| `corporate_tax_rate.unit` | string | Always |  |
| `corporate_tax_rate.date` | string | Always |  |
| `corporate_tax_rate.source` | object | Always |  |
| `corporate_tax_rate.source.publisher` | string | Always |  |
| `corporate_tax_rate.source.distributor` | string | Optional |  |
| `corporate_tax_rate.note` | string | Optional |  |
| `vat_rate` | object | Always |  |
| `vat_rate.value` | string | Always |  |
| `vat_rate.lower_bound` | string | Optional |  |
| `vat_rate.upper_bound` | string | Optional |  |
| `vat_rate.unit` | string | Always |  |
| `vat_rate.date` | string | Always |  |
| `vat_rate.source` | object | Always |  |
| `vat_rate.source.publisher` | string | Always |  |
| `vat_rate.source.distributor` | string | Optional |  |
| `vat_rate.note` | string | Optional |  |
| `minimum_wage` | object | Always |  |
| `minimum_wage.value` | string | Always |  |
| `minimum_wage.lower_bound` | string | Optional |  |
| `minimum_wage.upper_bound` | string | Optional |  |
| `minimum_wage.unit` | string | Always |  |
| `minimum_wage.date` | string | Always |  |
| `minimum_wage.source` | object | Always |  |
| `minimum_wage.source.publisher` | string | Always |  |
| `minimum_wage.source.distributor` | string | Optional |  |
| `minimum_wage.note` | string | Optional |  |

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": {
    "value": "1257",
    "unit": "USD per month",
    "date": "2026-07",
    "source": {
      "publisher": "Eurostat"
    },
    "note": "Series eurostat:minimum-wage-monthly-nac/usa"
  }
}
```

### Get Inflation Calculator

`GET /v1/economics/{country}/inflation/calculator`

MCP: tool `economics_get_inflation_calculator`.

#### Parameters

| Parameter | Where | Required | Type | Meaning |
| --- | --- | --- | --- | --- |
| `country` | path | Yes | string | ISO 3166 alpha-3 country code, for example DEU. |
| `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_inflation_percent` | string | Always |  |
| `from_index` | object | Always |  |
| `from_index.period` | string | Always |  |
| `from_index.value` | string | Always |  |
| `from_index.index_base` | string | Always | The base the index is 100 (or its base value) at. |
| `to_index` | object | Always |  |
| `to_index.period` | string | Always |  |
| `to_index.value` | string | Always |  |
| `to_index.index_base` | string | Always | The base the index is 100 (or its base value) at. |
| `source` | object | Optional |  |
| `source.publisher` | string | Always |  |
| `source.distributor` | string | Always |  |

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

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

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](https://narwhalapi.com/docs/errors.md) for the shape and the credit headers. Failed requests are not charged.

| Code | Status | Meaning |
| --- | --- | --- |
| `invalid_query` | 400 | A parameter is missing, unknown, repeated or outside its range. |
| `not_found` | 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_credits` | 402 | Your credit balance is less than the request costs. |
| `economics_unavailable` | 503 | The stored data cannot answer right now. Not charged. |

Was this page helpful?
