Package 'wbids'

Title: Seamless Access to World Bank International Debt Statistics (IDS)
Description: Access and analyze the World Bank's International Debt Statistics (IDS) <https://datacatalog.worldbank.org/search/dataset/0038015>. IDS provides creditor-debtor relationships between countries, regions, and institutions. 'wbids' enables users to download, process and work with IDS series across multiple geographies, counterparts, and time periods.
Authors: Teal Emery [aut, cre], Teal Insights [cph], Christoph Scheuch [aut] , Christopher Smith [ctb]
Maintainer: Teal Emery <[email protected]>
License: MIT + file LICENSE
Version: 1.0.0.9000
Built: 2025-03-07 21:28:54 UTC
Source: https://github.com/teal-insights/r-wbids

Help Index

Download and Process Bulk Data File for International Debt Statistics

Description

This function downloads a data file from the World Bank International Debt Statistics (IDS), reads and processes the data into a tidy format.

Usage

ids_bulk(
  file_url,
  file_path = tempfile(fileext = ".xlsx"),
  quiet = FALSE,
  timeout = getOption("timeout", 60),
  warn_size = TRUE
)

Arguments

file_url

A character string specifying the URL of the Excel file to download. This parameter is required (see ids_bulk_files).
file_path

An optional character string specifying the file path where the downloaded file will be saved. Defaults to a temporary file with .xlsx extension. The file will automatically be deleted after processing.
quiet

A logical parameter indicating whether messages should be printed to the console.
timeout

An integer specifying the timeout in seconds for downloading the file. Defaults to the current R timeout setting.
warn_size

A logical parameter indicating whether to warn about large downloads. Defaults to TRUE.

Value

A tibble containing processed debt statistics data with the following columns:

geography_id

The unique identifier for the geography (e.g., "ZMB").

series_id

The unique identifier for the series (e.g., "DT.DOD.DPPG.CD").

counterpart_id

The unique identifier for the counterpart series.

year

The year corresponding to the data (as an integer).

value

The numeric value representing the statistic for the given geography, series, counterpart, and year.

Examples

## Not run: 
available_files <- ids_bulk_files()
data <- ids_bulk(
  available_files$file_url[1]
)

## End(Not run)

Retrieve Available Bulk Download Files for International Debt Statistics

Description

This function returns a tibble with metadata for files available for bulk download via the World Bank International Debt Statistics (IDS). It includes information such as file names, URLs, and the last update dates for each file in Excel (xlsx) format.

Usage

ids_bulk_files()

Value

A tibble containing the available files and their metadata:

file_name

The name of the file available for download.

file_url

The URL to download the file in Excel format.

last_updated_date

The date when the file was last updated.

Examples

ids_bulk_files()

Retrieve Bulk Series Metadata for International Debt Statistics

Description

This function retrieves a tibble with metadata for series available via bulk download of the World Bank International Debt Statistics (IDS).

Usage

ids_bulk_series()

Value

A tibble containing the available series and their metadata:

series_id

The unique identifier for the series (e.g., "BN.CAB.XOKA.CD").

series_name

The name of the series (e.g., "Current account balance (current US$)").

source_id

The ID of the data source providing the indicator.

source_name

The name or description of the source of the indicator data.

source_note

Additional notes or descriptions about the data source.

source_organization

The organization responsible for the data source.

Examples

ids_bulk_series()

Fetch Data from the World Bank International Debt Statistics (IDS) API

Description

Retrieves standardized debt statistics from the World Bank's International Debt Statistics (IDS) database, which provides comprehensive data on the external debt of low and middle-income countries. The function handles country identification, data validation, and unit standardization, making it easier to conduct cross-country debt analysis and monitoring.

Usage

ids_get(
  geographies,
  series,
  counterparts = "WLD",
  start_year = 2000,
  end_year = NULL,
  progress = FALSE
)

Arguments

geographies

A character vector of geography identifiers representing debtor countries and aggregates. Must use geography_id from ids_list_geographies:

  • For individual countries, use ISO3C codes (e.g., "GHA" for Ghana)

  • For aggregates, use World Bank codes (e.g., "LIC" for low income countries) The IDS database covers low and middle-income countries and related aggregates only. Cannot contain NA values.

series

A character vector of debt statistics series identifiers that must match the series_id column from ids_list_series. Each series represents a specific debt statistic (e.g., "DT.DOD.DECT.CD" for total external debt stocks, "DT.TDS.DECT.CD" for debt service payments). Cannot contain NA values.
counterparts

A character vector of creditor identifiers that must match the counterpart_id column from ids_list_counterparts. The default "WLD" returns aggregated global totals across all creditors. Common options:

  • "WLD" - World total (aggregated across all creditors)

  • "all" - Retrieve data broken down by all creditors

  • All identifiers are strings, but some are string-formatted numbers (e.g., "730" for China, "907" for IMF), while others are alphabetic codes (e.g., "BND" for bondholders) Cannot contain NA values.

start_year

A numeric value representing the starting year (default: 2000). This default is intended to reduce data volume. For historical analysis, explicitly set to 1970 (the earliest year of data available).
end_year

A numeric value representing the ending year (default: NULL). Must be >= 1970 and cannot be earlier than start_year. If NULL, returns data through the most recent available year. Some debt service-related series include projections of debt service. For the 2024 data release, debt service projections are available through 2031.
progress

A logical value indicating whether to display progress messages during data retrieval (default: FALSE).

Value

A tibble containing debt statistics with the following columns:

geography_id

The identifier for the debtor geography (e.g., "GHA" for Ghana, "LIC" for low income countries)

series_id

The identifier for the debt statistic series (e.g., "DT.DOD.DECT.CD" for total external debt stocks)

counterpart_id

The identifier for the creditor (e.g., "WLD" for world total, "730" for China)

year

The year of the observation

value

The numeric value of the debt statistic, standardized to the units specified in the series definition (typically current US dollars)

Data Coverage and Validation

The IDS database provides detailed debt statistics for low and middle-income countries, including:

  • Debt stocks and flows

  • Debt service and interest payments

  • Creditor composition

  • Terms and conditions of new commitments

To ensure valid queries:

See Also

  • ids_list_geographies() for available debtor geography codes

  • ids_list_series() for available debt statistics series codes

  • ids_list_counterparts() for available creditor codes

Examples

# Get total external debt stocks for a single country from 2000 onward
ghana_debt <- ids_get(
  geographies = "GHA",
  series = "DT.DOD.DECT.CD"  # External debt stocks, total
)

# Compare debt service metrics across income groups
income_groups <- ids_get(
  geographies = c("LIC", "LMC", "UMC"),  # Income group aggregates
  series = "DT.TDS.DECT.CD",  # Total debt service
  start_year = 2010
)

# Analyze debt composition by major creditors
creditor_analysis <- ids_get(
  geographies = c("KEN", "ETH"),  # Kenya and Ethiopia
  series = c(
    "DT.DOD.DECT.CD",  # Total external debt
    "DT.TDS.DECT.CD"   # Total debt service
  ),
  counterparts = c(
    "WLD",  # World total
    "730",  # China
    "907",  # IMF
    "BND"   # Bondholders
  ),
  start_year = 2015
)

List Available Counterparts from the World Bank International Debt Statistics API

Description

This function returns a tibble with available counterparts from the World Bank International Debt Statistics (IDS) API. Each row provides details on counterparts, including their unique identifiers, names, and types.

Usage

ids_list_counterparts()

Value

A tibble containing the available counterparts and their attributes:

counterpart_id

The unique identifier for the counterpart (e.g., "730").

counterpart_name

The standardized name of the counterpart (e.g., "China").

counterpart_iso2code

ISO 3166-1 alpha-2 code of the counterpart (e.g., "CN").

counterpart_iso3code

ISO 3166-1 alpha-3 code of the counterpart (e.g., "CHN").

counterpart_type

The type of counterpart (e.g., "Country", "Institution", "Region").

Examples

ids_list_counterparts()

List Available Geographies from the World Bank International Debt Statistics API

Description

This function returns a tibble with available geographies from the World Bank International Debt Statistics (IDS) API. Each row provides details on geographies, including their unique identifiers, names, and types.

Usage

ids_list_geographies()

Value

A tibble containing the available geographies and their attributes:

geography_id

ISO 3166-1 alpha-3 code of the geography (e.g., "ZMB").

geography_name

The standardized name of the geography (e.g., "Zambia").

geography_iso2code

ISO 3166-1 alpha-2 code of the geography (e.g., "ZM").

geography_type

The type of geography (e.g., "Country", "Region").

capital_city

The capital city of the geography (e.g., "Lusaka").

region_id

The unique identifier for the region (e.g., "SSF").

region_iso2code

ISO 3166-1 alpha-2 code of the region (e.g., "ZG").

region_name

The name of the region (e.g., "Sub-Saharan Africa").

admin_region_id

The unique identifier for the administrative region (e.g., "SSA").

admin_region_iso2code

The ISO 3166-1 alpha-2 code for the administrative region (e.g., "ZF").

admin_region_name

The name of the administrative region (e.g., "Sub-Saharan Africa (excluding high income)").

lending_type_id

The unique identifier for the lending type (e.g., "IDX").

lending_type_iso2code

ISO code for the lending type (e.g., "XI").

lending_type_name

The name of the lending type (e.g., "IDA").

Examples

ids_list_geographies()

List Available Series from the World Bank International Debt Statistics API

Description

This function returns a tibble with available series from the World Bank International Debt Statistics (IDS) API. Each series provides data on various debt-related indicators.

Usage

ids_list_series()

Value

A tibble containing the available series and their metadata:

series_id

The unique identifier for the series (e.g., "BN.CAB.XOKA.CD").

series_name

The name of the series (e.g., "Current account balance (current US$)").

source_id

The ID of the data source providing the indicator.

source_name

The name or description of the source of the indicator data.

source_note

Additional notes or descriptions about the data source.

source_organization

The organization responsible for the data source.

Examples

ids_list_series()

List Available Series-Topic combinations from the World Bank International Debt Statistics API

Description

This function returns a tibble with available series-topic combinations from the World BankInternational Debt Statistics (IDS) API. Each row provides a mapping from series to topic, with the possibility of multiple topic per series.

Usage

ids_list_series_topics()

Value

A tibble containing the available series and their topics:

series_id

The unique identifier for the series (e.g., "BM.GSR.TOTL.CD").

topic_id

The unique identifier for the topic (e.g., 3).

topic_name

The name of the topic (e.g., "External Debt").

Examples

ids_list_series_topics()