Country Macroeconomic Indicators API

Available via: REST API · MCP

This endpoint provides country-level macroeconomic data from 1970 to the current year. Each record covers one country for one calendar year and contains 38 indicators grouped by category.

Coverage

Countries	50+, including all OECD and G20 countries, plus Bulgaria, Croatia, Peru, Romania, and Thailand
Indicators	38
Historical Depth	1970 to the current year (current-year values are forecasts). The start year varies by country (download the list of countries with start years).
Frequency	Annual

Data Freshness

Macroeconomic indicators are updated quarterly.

Data Availability & Limitations

Data is annual. Quarterly and monthly values are not provided.
Some fields may be null if a specific indicator is not available for a given country and year. It does not indicate an error.
The earliest available year varies by country. See the country list for each country’s start year.
Values for the current year are forecasts based on available data and may be revised.
Historical values may be revised as data is updated.
Values, units, and methodologies are provided as received from the original data sources. Methodologies may vary across indicators and countries. FinImpulse does not independently recalculate or verify these figures.

When to Use This Endpoint

Display macroeconomic indicators and historical charts on country profiles and dashboards.
Add country-level economic context to stock, ETF, and mutual fund data.
Build country screeners and rankings based on macroeconomic indicators.
Supply macroeconomic inputs to financial models and portfolio allocation tools.
Analyze country risk factors using government finance, trade, and currency data.

Request Parameters

POST

v1/macro-economics

filters arrayoptional

Optional filter expressions. Supported on all fields.

Each filter condition is defined as: [field, operator, value]. Conditions can be combined using logical operators and/or.

Supported operators:

Numeric fields:

> - greater than
>= - greater than or equal
< - less than
<= - less than or equal
= - equals
<> - not equal

String fields:

like – pattern match (requires % as a wildcard)
not_like - pattern does not match (requires % as a wildcard)
contains - value exists in string
not_contains - value does not exist in string
startswith - string starts with value
endswith - string ends with value

String operators apply to country_iso3, the only string field in the response.

% usage examples:

%abc% - matches any string containing "abc"
abc% - matches any string starting with "abc"
%abc - matches any string ending with "abc"

sort_by arrayoptional

Optional sorting configuration for result items. Each sorting setup is defined as an object {selector, desc}:

selector - Field used for sorting (e.g., year).
desc - Sorting direction (true for descending, false for ascending).

Multiple sorting setups can be combined in the array.

limit integeroptional

Maximum number of matched items returned (user-defined).

Default: 100
Maximum: 1000

offset integeroptional

Pagination offset (0-based)

tag stringoptional

User-defined identifier for the task (max 255 characters).

It is returned in the response data object, allowing you to match results with the corresponding request. It does not affect API processing or filtering logic.

Example Request

curl --location "https://api.finimpulse.com/v1/macro-economics" \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <API_TOKEN>" \
  -d '{
      "filters": [
          [
              "year",
              "=",
              2026
          ],
          "and",
          [
              "country_iso3",
              "=",
              "CHE"
          ]
      ],
      "sort_by": [
          {
              "selector": "year",
              "desc": true
          }
      ],
      "limit": 1,
      "offset": 0
  }'

using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;

var client = new HttpClient();
var url = "https://api.finimpulse.com/v1/macro-economics";

client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", "<API_TOKEN>");
client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/json"));

var json = @"{
    ""filters"": [
        [
            ""year"",
            ""="",
            2026
        ],
        ""and"",
        [
            ""country_iso3"",
            ""="",
            ""CHE""
        ]
    ],
    ""sort_by"": [
        {
            ""selector"": ""year"",
            ""desc"": true
        }
    ],
    ""limit"": 1,
    ""offset"": 0
}";
var content = new StringContent(json, Encoding.UTF8, "application/json");

var response = await client.PostAsync(url, content);
var result = await response.Content.ReadAsStringAsync();
Console.WriteLine(result);

<?php
$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.finimpulse.com/v1/macro-economics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Bearer <API_TOKEN>"
  ],
  CURLOPT_POSTFIELDS => json_encode(
[
      "filters" => [
        [
          "year",
          "=",
          2026
        ],
        "and",
        [
          "country_iso3",
          "=",
          "CHE"
        ]
      ],
      "sort_by" => [
        [
          "selector" => "year",
          "desc" => true
        ]
      ],
      "limit" => 1,
      "offset" => 0
    ]
  )
]);

$response = curl_exec($curl);
curl_close($curl);

echo $response;

import urllib.request
import json

url = "https://api.finimpulse.com/v1/macro-economics"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <API_TOKEN>"
}
data = {
    "filters": [
        [
            "year",
            "=",
            2026
        ],
        "and",
        [
            "country_iso3",
            "=",
            "CHE"
        ]
    ],
    "sort_by": [
        {
            "selector": "year",
            "desc": True
        }
    ],
    "limit": 1,
    "offset": 0
}

req = urllib.request.Request(url,
    data=json.dumps(data).encode("utf-8"),
    headers=headers,
    method="POST")

with urllib.request.urlopen(req) as response:
    result = json.loads(response.read().decode("utf-8"))
    print(result)

const https = require('https');

const data = JSON.stringify({
    "filters": [
        [
            "year",
            "=",
            2026
        ],
        "and",
        [
            "country_iso3",
            "=",
            "CHE"
        ]
    ],
    "sort_by": [
        {
            "selector": "year",
            "desc": true
        }
    ],
    "limit": 1,
    "offset": 0
});

const options = {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer <API_TOKEN>',
    'Content-Length': Buffer.byteLength(data)
  }
};

const req = https.request('https://api.finimpulse.com/v1/macro-economics', options, (res) => {
  let body = '';
  res.on('data', chunk => body += chunk);
  res.on('end', () => console.log(JSON.stringify(JSON.parse(body), null, 2)));
});

req.on('error', (e) => console.error(e));
req.write(data);
req.end();

Response

The response contains pagination fields and a list of macroeconomic records. Each item represents one country for one calendar year.

Pagination Fields

total_count integer

Total number of matching records.

items_count integer

Number of records returned.

items array

Array of macroeconomic records.

Identifiers

country_iso3 string

Country identifier (ISO 3166-1 alpha-3 code, e.g., "CHE" for Switzerland).

year integer

Calendar year of the record.

GDP & Wealth

population number

Total population.

gdp_usd number

Nominal gross domestic product (GDP), normalized to USD.

gdp_per_capita_usd number

Real GDP per capita (constant prices), normalized to USD.

gdp_usd / population is not expected to equal gdp_per_capita_usd. gdp_usd represents nominal GDP, while gdp_per_capita_usd is based on real GDP.

gdp_growth number

Year-over-year growth rate of nominal GDP.

gdp_per_capita_growth number

Year-over-year growth rate of real GDP per capita.

Trade & Balance

exports_usd number

Exports of goods and services, normalized to USD.

imports_usd number

Imports of goods and services, normalized to USD.

account_balance_usd number

Current account balance, normalized to USD.

account_balance_percent number

Current account balance as a percentage of GDP.

export_import_ratio number

Ratio of exports to imports.

account_balance_change number

Year-over-year relative change in the current account balance.

Inflation & Employment

unemployment_rate number

Unemployment rate as a percentage of the labor force.

inflation number

Annual inflation rate.

consumer_price_index number

Consumer Price Index (CPI).

deflator number

GDP deflator.

inflation_growth number

Year-over-year relative change in the inflation rate.

Rates & Currency

central_bank_interest_rate number

Central bank policy interest rate, annual average.

short_term_interest_rate number

Short-term market interest rate, annual average.

long_term_interest_rate number

Long-term market interest rate (e.g., 10-year government bond yield), annual average.

interest_rate_spread number

Difference between long-term and short-term interest rates, in percentage points.

exchange_rate_usd number

Official exchange rate (local currency per USD), annual average.

real_effective_exchange_rate number

Real effective exchange rate (REER) index.

exchange_rate_change number

Year-over-year relative change in the exchange rate.

Government Finances

general_government_debt number

Gross general government debt, in local currency.

general_government_debt_to_gdp number

General government debt as a percentage of GDP.

general_government_debt_to_gdp_growth number

Year-over-year relative change in the debt-to-GDP ratio.

general_government_deficit number

General government budget balance (revenue minus expenditure), in local currency.

Negative values indicate a deficit
Positive values indicate a surplus

general_government_deficit_to_gdp number

General government budget balance as a percentage of GDP.

Negative values indicate a deficit
Positive values indicate a surplus

fiscal_balance_trend number

Year-over-year relative change in general_government_deficit_to_gdp.

general_government_revenue number

General government revenue, in local currency.

general_government_revenue_to_gdp number

General government revenue as a percentage of GDP.

general_government_tax_revenue_to_gdp number

Tax revenue as a percentage of GDP.

general_government_expenditure number

General government expenditure, in local currency.

general_government_expenditure_to_gdp number

General government expenditure as a percentage of GDP.

Consumption & Investment

household_consumption number

Household final consumption expenditure, in local currency.

government_consumption number

General government final consumption expenditure, in local currency.

gross_capital_formation number

Gross capital formation (total investment), in local currency.

gross_fixed_capital_formation number

Gross fixed capital formation (investment in fixed assets), in local currency.

Example Response

{
    "task_id": "08041213-0022-0060-0000-5207dc4fcb68",
    "status_code": 20000,
    "status_message": "OK",
    "live": true,
    "cost": 0.00035,
    "data": {
        "limit": 1,
        "offset": 0,
        "filters": [
            [
                "year",
                "=",
                2026
            ],
            "and",
            [
                "country_iso3",
                "=",
                "CHE"
            ]
        ],
        "sort_by": [
            {
                "selector": "year",
                "desc": true
            }
        ]
    },
    "result": {
        "total_count": 1,
        "items_count": 1,
        "items": [
            {
                "country_iso3": "CHE",
                "year": 2026,
                "gdp_usd": 966355320340.284,
                "gdp_per_capita_usd": 86080.154106,
                "exports_usd": 904664631552.63,
                "imports_usd": 826937660755.981,
                "account_balance_usd": 47908911173.2118,
                "account_balance_percent": 4.232002,
                "deflator": 108.065291,
                "population": 9156561.053364,
                "unemployment_rate": 4.893447,
                "central_bank_interest_rate": 0.0625,
                "inflation": 0.660846,
                "consumer_price_index": 107.635787,
                "short_term_interest_rate": 0.021704,
                "long_term_interest_rate": 0.381666,
                "real_effective_exchange_rate": 103.878237,
                "exchange_rate_usd": 0.780372,
                "general_government_debt": 360642557949.615,
                "general_government_debt_to_gdp": 40.832447,
                "general_government_deficit": 3279238390.40076,
                "general_government_deficit_to_gdp": 0.371279,
                "general_government_revenue": 300533577290.674,
                "general_government_revenue_to_gdp": 34.026825,
                "general_government_expenditure": 297254338900.273,
                "general_government_expenditure_to_gdp": 33.655545,
                "general_government_tax_revenue_to_gdp": 27.703844,
                "household_consumption": 438413492133.993,
                "government_consumption": 105958051973.503,
                "gross_capital_formation": 278207337470.785,
                "gross_fixed_capital_formation": 230816714309.017,
                "gdp_growth": 0.01806,
                "gdp_per_capita_growth": 0.004418,
                "inflation_growth": 3.280118,
                "interest_rate_spread": 0.359962,
                "general_government_debt_to_gdp_growth": -0.014291,
                "fiscal_balance_trend": -0.31016,
                "export_import_ratio": 1.093993,
                "exchange_rate_change": -0.06109,
                "account_balance_change": -0.343597
            }
        ]
    }
}

Units & Formats

Monetary fields with the _usd suffix are normalized to USD. Other monetary fields, such as general_government_debt and household_consumption, are expressed in the country’s local currency.
Fields ending in _interest_rate or _to_gdp, as well as inflation, unemployment_rate, and account_balance_percent, are expressed as percentages (e.g., 4.35 represents 4.35%).
Fields ending in _growth or _change, as well as fiscal_balance_trend, are expressed as decimal values (e.g., 0.0614 represents 6.14%).
Index fields (consumer_price_index, deflator, real_effective_exchange_rate) use base years that may vary by country and source. The base year is not provided in the API response. These fields are best used to track changes within the same country over time rather than for direct cross-country comparison.

Pagination & Limits

You can control how many records a response returns and page through large result sets using the limit and offset parameters.

Use limit to set the number of records per request, from 1 to 1000. If limit is not specified, up to 100 records are returned.
Use offset to skip records (0-based). For example, limit: 100 and offset: 100 return records 101–200.
To retrieve all matching records, increase offset by the limit value until offset + items_count reaches total_count.
To keep the order consistent across pages, pass sort_by, for example, by country_iso3 and year.

Each returned record is billed as a Row, so the cost of a request depends on the number of records returned.

API Pricing

Call: $0.00030
Row: $0.00005