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

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_date = 2000,
  end_date = 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_date

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_date

A numeric value representing the ending year (default: NULL). Must be >= 1970 and cannot be earlier than start_date. 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:

Use ids_list_geographies to find valid debtor geography codes
Use ids_list_series to explore available debt statistics
Use ids_list_counterparts to see available creditor codes

Examples

# \donttest{
# 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_date = 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_date = 2015
)
# }