Accessing International Debt Statistics (IDS) through World Bank Data API¶

Part 2 - Get and explore data¶

Python 3¶

Date: 04/15/2020
Updated: 9/26/2024
Data source
Developer Information
GitHub

This is second part of a two-part series on accessing the International Debt Statistics (IDS) database through the World Bank Data API. In Part 1, we queried the World Bank Data API to retrieve indicator names and location codes. In this guide, we will use that information to explore the regional trends of total external debt stocks from the IDS database.

The following code in this guide will show step-by-step how to:

  1. Setup up your environment with the needed packages
  2. Input your data specifications (as selected in Part 1)
  3. Use the World Bank Data API call to return the specified data
  4. Explore the data through basic descriptive analysis and create a pretty chart.

1. Setup¶

To start, make sure you have the following packages installed on your machine. If you aren't familiar with how to install a Python package, visit each of the linked packages below for instructions.

  • pandas: Data analysis
  • numpy: Data analysis
  • datetime: Parsing dates
  • wbgapi: World Bank Data API wrapper
  • plotly: Data visualization

Then, open up your preferred mode of writing Python. This could be in a Jupyter Notebook using Jupyter Lab, using a code editor (like Cursor or Visual Studio) + command line, or just from the command line. Now follow the rest of the steps below to retreive and analyze the World Bank data.

In [ ]:
# Importing packages
import pandas as pd
import numpy as np
import datetime
import wbgapi as wb
import plotly.express as px
import plotly.io as pio
pio.renderers.default = "notebook" # use "pio.renderers" to see the default renderer

2. Data Specifications¶

You will specify the data you want to explore using the following parameters:

  • Indicator(s): The indicator code(s) for the data
  • Location(s): The location code(s) for the countries, regions, or income level categories
  • Time: Years
  • Source: The World Bank API source

Indicator(s)¶

In this guide, we will be looking at "total external debt stock" from the IDS database. To find the indicator for the data in which you're interested, you can either explore the World Bank data catalog or use an API query as outlined in Part 1 of this series. You can also view the IDS indicators and codes in their hierarchical order on our data tables. The Analytical view shows the select indicators from the IDS publication and the Standard view shows all available indicators.

In [ ]:
# Selecting the indicator
indicatorSelection = {"DT.DOD.DECT.CD":"TotalExternalDebt"}

The text that follows the indicator code (in this case, "TotalExternalDebt") should be a description that helps that you correctly identify the indicator. To call more than one indicator, add more indicator names and descriptions to the dictionary.

Location(s)¶

Debtor Country

To select a debtor location by country, region, or income level category you will need to know its 2 or 3 letter code. To figure out what this code is, you can either use an API query as outlined in Part 1 of this series or use the convenient location-codes csv* in this repo.

We will select regional aggregates (these exclude high-income countries):

  • ECA: Europe & Central Asia
  • SSA: Sub-Saharan Africa
  • SAS: South Asia
  • LAC: Latin America & the Caribbean
  • MNA: Middle East & North Africa
  • EAP: East Asia & Pacific

Creditor Country / Multilateral Agency (Counterpart-Area)

Similarly, we can select a creditor country or multilateral agency, which is named "counterpart-area" in IDS. This is also outlined in Part 1 of this series or use the location-codes csv* in this repo.

We will select World - or the total:

  • WLD: World
*The location-codes csv was created using the API queries: https://api.worldbank.org/v2/sources/6/country/all?per_page=500&format=json&source=6 and https://api.worldbank.org/v2/sources/6/counterpart-area/all?per_page=500&format=json&source=6¶
In [ ]:
# Select the debtor countries or regions
debtorSelection = ["ECA","SSA","SAS","LAC","MNA","EAP"]
In [ ]:
# Select the creditor
creditorSelection = ["WLD"]

Time¶

Here you will select the time frame for your data series. The format for the date is year, month, day. We are selecting data from 2009 to 2022.

In [ ]:
# Selecting the time frame
timeSelection = range(2009, 2023)

Source¶

The World Bank Data API has numerous sources, including one specific to International Debt Statistics. As identified in Part 1, IDS has a source ID of 6.

In [ ]:
IDS = wb.source.info(6)

3. API Call¶

In this step, we will retrieve the data using the World Bank Data API call. The package "wbgapi," created by Tim Herzog. In this example, we will request the data, with the parameters outlined above.

In [ ]:
# Making the API call and assigning the resulting DataFrame to "EXD"
EXD = wb.data.DataFrame(
    indicatorSelection, 
    economy=debtorSelection, 
    counterpart_area=creditorSelection,
    time=timeSelection, 
    db=6,
    labels=True).reset_index()

If you want a quick preview of your freshly retrieved DataFrame, you can print the first 5 lines

In [ ]:
# Print the first 5 lines of the DataFrame
print(EXD.head())

  economy                                            Country        YR2009  \
0     EAP        East Asia & Pacific (excluding high income)  8.292777e+11   
1     MNA  Middle East & North Africa (excluding high inc...  2.003394e+11   
2     LAC  Latin America & Caribbean (excluding high income)  8.560357e+11   
3     SAS                                         South Asia  3.666214e+11   
4     SSA         Sub-Saharan Africa (excluding high income)  2.944954e+11   

         YR2010        YR2011        YR2012        YR2013        YR2014  \
0  1.193014e+12  1.559066e+12  1.741615e+12  2.099323e+12  2.441880e+12   
1  2.104988e+11  2.109497e+11  2.205187e+11  2.425359e+11  2.430697e+11   
2  1.007253e+12  1.143749e+12  1.291144e+12  1.444065e+12  1.590396e+12   
3  4.102381e+11  4.605918e+11  5.302013e+11  5.684656e+11  6.088550e+11   
4  3.395090e+11  3.772914e+11  4.258964e+11  4.664434e+11  5.050872e+11   

         YR2015        YR2016        YR2017        YR2018        YR2019  \
0  2.008181e+12  2.117865e+12  2.495789e+12  2.805109e+12  2.999349e+12   
1  2.587749e+11  2.902550e+11  3.280893e+11  3.497578e+11  3.688230e+11   
2  1.614442e+12  1.657341e+12  1.752501e+12  1.865566e+12  1.901738e+12   
3  6.399661e+11  6.292997e+11  7.183565e+11  7.444834e+11  8.043390e+11   
4  5.103656e+11  5.563663e+11  6.505142e+11  6.890714e+11  7.379729e+11   

         YR2020        YR2021        YR2022  
0  3.273846e+12  3.676728e+12  3.345565e+12  
1  3.980972e+11  4.205611e+11  4.308192e+11  
2  1.895118e+12  1.947803e+12  1.989298e+12  
3  8.310993e+11  9.126150e+11  9.190163e+11  
4  7.763197e+11  8.157537e+11  8.327880e+11

4. Explore the data!¶

Congratulations! At this point you should have the total external debt stock for regions (excluding high-income economies) from 2009 - 2022 all in a DataFrame called "EXD."

Now we can do the following:

  • Data Cleaning: Clean up the format to use in a table or populate a visualization
  • Visualization: Create a simple chart

Data Cleaning¶

As you saw in the preview of the data in section 3, the DataFrame's format needs to be cleaned up. We want to reshape and clean the data. This will get it ready to present in a table or in a visualization.

In [ ]:
# Reshape from wide to long format
EXDlong = pd.melt(EXD, id_vars=['economy', 'Country'], var_name='Year', value_name='TotalExternalDebt')

# Rename columns
EXDlong.rename(columns={
    'economy': 'RegionCode',
    'Country': 'RegionName',
}, inplace=True)

# Remove "(excluding high income)" from the 'RegionName' column
EXDlong['RegionName'] = EXDlong['RegionName'].str.replace(r"\(excluding high income\)", "", regex=True).str.strip()

# Convert 'DebtValue' to billions, round to 0 decimal places, and convert to integers
EXDlong['TotalExternalDebt'] = (EXDlong['TotalExternalDebt'] / 1e9).round(0).astype(int)

# Display the reshaped DataFrame
print(EXDlong.head())

  RegionCode                  RegionName    Year  TotalExternalDebt
0        EAP         East Asia & Pacific  YR2009                829
1        MNA  Middle East & North Africa  YR2009                200
2        LAC   Latin America & Caribbean  YR2009                856
3        SAS                  South Asia  YR2009                367
4        SSA          Sub-Saharan Africa  YR2009                294

Now our data should be ready to present in a table or visualize in a chart. Let's take a look at the first five lines again so we can compare the cleaned up data to the raw output in section 3.

Data Visualization¶

Now use the package "plotly" to create a basic line graph of the regional trends in total external debt stock.

In [ ]:
# Defining the data source
source = EXDlong

# Creating the chart
chart = px.line(EXDlong, 
                x="Year",
                y="TotalExternalDebt",
                color="RegionName",
                title="Regional Total External Debt Stock (excluding High-Income countries)(USD billion)")
chart.update_layout(
                plot_bgcolor="white")

# Displaying the chart
chart