Exploring Debt Data by Creditor Composition

R

Date: 11/16/2020
Data source
Developer Information
GitHub

For the first time in its almost half a century of existence, this year’s publication of the World Bank’s International Debt Statistics (IDS) added an additional dimension to the data - the creditor country. You can now see the public and publicly guaranteed sector debt of low- and middle-income countries owed to each creditor country, either official (multilateral or bilateral) or non-official (private creditor and bondholders), providing more detailed information on the borrower-lender relationship. This brief guides serves to introduce you to this new data breakdown and get you started in your own analysis.

IDS Dimensions:

Country (debtor country)
Series (Indicator, such as Total Debt Stock)
Time
Counterpart area (creditor country) <- the new addition (default or total is “World”)

To understand how to view a full list of dimensions (and series definitions), please read Part 1 of our IDS API guides.

The following code and text will show step-by-step how to:

Setup - getting your environment ready with the needed R packages
API Request - understanding the path and variables of the IDS API request
Query data

1. Setup

To start, make sure you have the following packages installed on your machine. To install an R package, type install.packages(“httr”) with the correct package name into R. You can also visit each of the linked packages for reference.

httr: Submitting HTTP requests
jsonlite: Parsing json response
tidyverse: Data work
plotly: Graphing library

Then, open up your preferred mode of writing R, like R Studio. Now follow the rest of the steps below to query the World Bank Data API to find your indicator and location codes.

library(httr)
library(jsonlite)
library(tidyverse)
library(plotly)

2. API Request

In the previous guides, we used an R package to wrap the API and present us with data. This time, in order to better understand API requests we will take a closer look at how each variable is presented in the URL.

Below is an example of the 4 dimensional API request: http://api.worldbank.org/v2/sources/6/country/AGO/series/DT.DOD.BLAT.CD/counterpart-area/701/time/all

Let’s dissect the URL to understand each component:

http://api.worldbank.org/v2: This beginning portion of the above URL is called the endpoint - the starting point of the API from where you’re requesting data.

To get specific data, we use a “path variable.” The path is the word before the forward slash and the variable is the word after it.

sources/6: “sources” is the path and we select the variable “6,” corresponding to the IDS database.

After selecting the API source for the IDS database, we specify each of the 4 IDS dimensions:

country/AGO: “country” is the debtor country and AGO (the ISO code for Angola) is our variable.
counterpart-area/701: “counterpart-area” is the new dimension! This is the creditor country, showing public and publically guaranteed debt. By choosing “701” (the code for Japan) we are selecting the variable Japan as the official or bilateral lender.
series/DT.DOD.BLAT.CD: “series” is the path for our indicator code. In this case, the indicator is “DT.DOD.BLAT.CD,” the code for the bilateral public and publically guaranteed debt outstanding and disbursed in US dollars current (PPG, bilateral (DOD, current US$)).
time/all: the “time” path will show us the yearly data. By selecting the variable “all” we can get all years, including the NaN values.

3. Query

Below is a function that will take the parameters you set in the “Creditor,” “Debtor,” and “Series” variables to create an API request and create a neat table.

ENTER YOUR PARAMETERS HERE:

debtorCountry <- "AGO"
creditorCountry <- "701"
series <- "DT.DOD.BLAT.CD"
time <- "All"

The following code will use the entered parameters above to get the selected data from the World Bank API:

# Setting up the API URL
url <- "http://api.worldbank.org/v2/sources/6/country/"
end <- "?format=json&per_page=500"
path <- paste(url,debtorCountry,"/series/",series,"/counterpart-area/",creditorCountry,"/time/",time,end,sep="")

# Getting the data from the API
customRequest <- GET(url = path)
customResponse <- content(customRequest, as = "text", encoding = "UTF-8")
customJSON <- fromJSON(customResponse, flatten = TRUE)

# Creating a funtion that will parse through the JSON response
getData <- function(JSON) {
  df <- data.frame(
    year=rep(0, listLen),
    creditorCountry=rep(0, listLen),
    debtorCountry=rep(0, listLen),
    series=rep(0, listLen),
    data=rep(0, listLen)
    )
  
  for(i in 1:listLen){
    year <- JSON[["source"]][["data"]][["variable"]][[i]][[3]][[2]]
    data <- JSON[["source"]][["data"]][["value"]][[i]]
    df[i,] <- c(year,creditorCountry, debtorCountry, series, data)
    df$data = as.integer(df$data)
  }
  return(df)
}

# get length of data response
listLen <- length(customJSON[["source"]][["data"]][["value"]])

# Plugging the data into the parsing function and printing the data (excluding NA values)
IDSdata <- getData(customJSON)
IDSdata <- na.omit(IDSdata)
print(IDSdata)

##    year creditorCountry debtorCountry         series      data
## 42 2011             701           AGO DT.DOD.BLAT.CD  39462168
## 43 2012             701           AGO DT.DOD.BLAT.CD 163188978
## 44 2013             701           AGO DT.DOD.BLAT.CD 155071287
## 45 2014             701           AGO DT.DOD.BLAT.CD 631822127
## 46 2015             701           AGO DT.DOD.BLAT.CD 743593983
## 47 2016             701           AGO DT.DOD.BLAT.CD 698012068
## 48 2017             701           AGO DT.DOD.BLAT.CD 639803915
## 49 2018             701           AGO DT.DOD.BLAT.CD 553718698
## 50 2019             701           AGO DT.DOD.BLAT.CD 468514639

Now that you have selected data, you can create a bar chart showing the increase in official bilateral PPG lending from Japan to Angola.

# Making a simple bar chart
p<-plot_ly(
  IDSdata, x = ~year, y=~data, 
  type = "bar")%>%
  layout(
    title= "Official bilateral PPG Lending from Japan to Angola (US$)"
  )
p