worldbankpy

• Interacts with the World Bank API to retrieve macroeconomic data.

Requirements & Installation :

• Requirements: datetime, requests, pandas.

Example:

import worldbankpy

# Instantiate the World Bank API client:
instance = worldbankpy.Instance()

You can filter countries using the filtered_countries method. Available filters include region, income level, admin region, lending type. Values for these filters can be obtained using the following attributes:

regions = instance.list_regions  # Display all regions

>>> [
    'Latin America & Caribbean',
    'Aggregates',
    'South Asia',
    'Sub-Saharan Africa',
    'Europe & Central Asia',
    'Middle East & North Africa',
    'East Asia & Pacific',
    'North America'
    ]

countries = instance.list_available_countries  # Display all countries

>>> [
    'Aruba',
    'Africa Eastern and Southern',
    'Afghanistan',
    ...
    'South Africa',
    'Zambia',
    'Zimbabwe'
    ]

income_levels = instance.list_income_levels  # Display all income levels

>>> [
    'High income',
    'Aggregates',
    'Low income',
    'Lower middle income',
    'Upper middle income',
    'Not classified'
    ]

admin_regions = instance.list_admin_regions  # Display all admin regions

>>> [
    'South Asia',
    'Sub-Saharan Africa (excluding high income)',
    'Europe & Central Asia (excluding high income)',
    'Latin America & Caribbean (excluding high income)',
    'East Asia & Pacific (excluding high income)',
    'Middle East & North Africa (excluding high income)'
    ]

lending_types = instance.list_lending_types  # Display all lending types

>>> ['Not classified', 'Aggregates', 'IDA', 'IBRD', 'Blend']

For example, you can filter the countries in Europe & Central Asia with high income:

eu_central_asia_high_inc = instance.filtered_countries(region="Europe & Central Asia", income_level="High income")

>>>{
    'Andorra': 'AND',
    'Austria': 'AUT',
    'Belgium': 'BEL',
    ...
    'Slovak Republic': 'SVK',
    'Slovenia': 'SVN',
    'Sweden': 'SWE'
    }

You can then filter indicators using the filtered_indicators method. Available filters include topics & sources. Values for these filters can be obtained using the following attributes:

topics = instance.list_topics  # Display all topics

>>> [
    'Poverty','Education','Social Protection & Labor','Economy & Growth','Agriculture & Rural Development',
    'Climate Change','Urban Development','External Debt','Public Sector','Financial Sector','Aid Effectiveness',
    'Millenium development goals','Environment','Energy & Mining','Infrastructure','Science & Technology',
    'Private Sector','Trade','Gender','Health'
    ]

sources = instance.list_sources  # Display all sources

>>> [
    'LAC Equity Lab', 'Sustainable Energy for All','Global Partnership for Education',
    'International Comparison Program (ICP) 2005','ICP 2017',
    'Exporter Dynamics Database – Indicators at Country-Year Level','Global Financial Inclusion',
    'G20 Financial Inclusion Indicators','Disability Data Hub (DDH)','Education Statistics',
    ...
    'Indicators of Resilience and Equity','PEFA 2016','PEFA 2011','Joint External Debt Hub',
    'Health Nutrition and Population Statistics','Education Policy',
    'Health Nutrition and Population Statistics by Wealth Quintile','Universal Health Coverage',
    'Jobs','Subnational Malnutrition Database','Subnational Population','Statistical Performance Indicators (SPI)'
    ]


categories = instance.list_available_categories  # Display all categories (similar to topics)

You can acces a list of popular indicators using the list_popular_indicators attribute:

popular_indicators = instance.list_popular_indicators

>>> [
    {'Population, total': 'SP.POP.TOTL'},
    {'Population growth (annual %)': 'SP.POP.GROW'},
    {'Surface area (sq. km)': 'AG.SRF.TOTL.K2'},
    ...
    {'GDP per capita (current US$)': 'NY.GDP.PCAP.CD'},
    {'Foreign direct investment, net (BoP, current US$)': 'BN.KLT.DINV.CD'},
    {'Inflation, consumer prices (annual %)': 'FP.CPI.TOTL.ZG'}
    ]

For example, let's filter the indicators related to Economy & Growth:

gdp_indicators = instance.filtered_indicators(topic="Economy & Growth")
gdp_indicators_v2 = instance.category_indicators('Economy & Growth')

Otherwise, you can search for indicators by keywords:

indicators = instance.search_indicator_by_keywords(["GDP", "growth", "annual"])

An example use:

countries = instance.filtered_countries(region="Europe & Central Asia", income_level="High income")

>>>{
    'Andorra': 'AND',
    'Austria': 'AUT',
    'Belgium': 'BEL',
    ...
    'Slovak Republic': 'SVK',
    'Slovenia': 'SVN',
    'Sweden': 'SWE'
    }

countries_codes = [v for k, v in countries.items()]

>>> [
    'AND','AUT','BEL','BGR','CHE','CHI','CYP','CZE','DEU','DNK',
    'ESP','EST','FIN','FRA','FRO','GBR','GIB','GRC','GRL','HRV',
    'HUN','IMN','IRL','ISL','ITA','LIE','LTU','LUX','LVA','MCO',
    'NLD','NOR','POL','PRT','ROU','RUS','SMR','SVK','SVN','SWE'
    ]

indicators = instance.search_indicator_by_keywords(["GDP", "growth", "annual"])

>>> [
    {'name': 'GDP growth (annual %)', 'code': 'NY.GDP.MKTP.KN.87.ZG'},
    {'name': 'GDP per capita, PPP annual growth (%)','code': 'NY.GDP.PCAP.PP.KD.ZG'},
    {'name': 'GDP per person employed (annual % growth)','code': 'SL.GDP.PCAP.EM.KD.ZG'},
    {'name': 'GDP growth (annual %)', 'code': 'NY.GDP.MKTP.KD.ZG'},
    {'name': 'GDP per capita growth (annual %)', 'code': 'NY.GDP.PCAP.KD.ZG'}
    ]

indicator_id = indicators[-2]['code']
indicator_name = indicators[-2]['name']


>>> 'NY.GDP.MKTP.KD.ZG'

data = instance.indicator(countries_codes, indicator_id)

The returned pandas.DataFrame has attributes providing relevant informations about the data:

data.attrs

>>>{
'Country Codes':['AND','AUT','BEL', ..., 'SVK','SVN','SWE'],
'Countries': ['Andorra', 'Austria', 'Belgium', ...,  'Slovak Republic', 'Slovenia', 'Sweden'],
'Indicator': 'GDP growth (annual %)',
'Indicator Code': 'NY.GDP.MKTP.KD.ZG',
'Unit': '',
'Last Updated': '2025-04-15',
'Source': 'World Bank',
'Source URLs': [
  'https://api.worldbank.org/v2/country/AND/indicator/NY.GDP.MKTP.KD.ZG?date=1930:2025&per_page=10000&format=json',
  'https://api.worldbank.org/v2/country/AUT/indicator/NY.GDP.MKTP.KD.ZG?date=1930:2025&per_page=10000&format=json',
  'https://api.worldbank.org/v2/country/BEL/indicator/NY.GDP.MKTP.KD.ZG?date=1930:2025&per_page=10000&format=json',
  ...
  'https://api.worldbank.org/v2/country/SVK/indicator/NY.GDP.MKTP.KD.ZG?date=1930:2025&per_page=10000&format=json',
  'https://api.worldbank.org/v2/country/SVN/indicator/NY.GDP.MKTP.KD.ZG?date=1930:2025&per_page=10000&format=json',
  'https://api.worldbank.org/v2/country/SWE/indicator/NY.GDP.MKTP.KD.ZG?date=1930:2025&per_page=10000&format=json'
  ]
}

You can then analyze/ visualize the data:

plt.figure(figsize=(11, 10))
for country in data:
    plt.plot(data.index, data[country], label=country)

plt.title(f"{indicator_name} in Europe & Central Asia (High Income)")
plt.xlabel("Year")
plt.ylabel(indicator_name)
plt.show()