Type:	Package
Title:	Seamless Access to World Bank World Development Indicators (WDI)
Version:	1.0.1
Description:	Access and analyze the World Bank’s World Development Indicators (WDI) using the corresponding API https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation. WDI provides more than 24,000 country or region-level indicators for various contexts. 'wbwdi' enables users to download, process and work with WDI series across multiple countries, aggregates, and time periods.
License:	MIT + file LICENSE
Encoding:	UTF-8
RoxygenNote:	7.3.2
Depends:	R (≥ 4.1)
Imports:	cli, dplyr (≥ 1.0.0), httr2 (≥ 1.0.0), jsonlite (≥ 1.0.0), purrr (≥ 1.0.0), tibble, tidyr (≥ 1.0.0), rlang (≥ 1.0.0)
Suggests:	curl, knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
Config/Needs/website:	forcats, ggplot2, wbids
URL:	https://github.com/tidy-intelligence/r-wbwdi, https://tidy-intelligence.github.io/r-wbwdi/
BugReports:	https://github.com/tidy-intelligence/r-wbwdi/issues
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-03-25 20:45:10 UTC; krise
Author:	Christoph Scheuch [aut, cre, cph]
Maintainer:	Christoph Scheuch <christoph@tidy-intelligence.com>
Repository:	CRAN
Date/Publication:	2025-03-25 21:00:01 UTC

wbwdi: Seamless Access to World Bank World Development Indicators (WDI)

Description

Access and analyze the World Bank’s World Development Indicators (WDI) using the corresponding API https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation. WDI provides more than 24,000 country or region-level indicators for various contexts. 'wbwdi' enables users to download, process and work with WDI series across multiple countries, aggregates, and time periods.

Author(s)

Maintainer: Christoph Scheuch christoph@tidy-intelligence.com (ORCID) [copyright holder]

See Also

Useful links:

• https://github.com/tidy-intelligence/r-wbwdi

• https://tidy-intelligence.github.io/r-wbwdi/

• Report bugs at https://github.com/tidy-intelligence/r-wbwdi/issues

Internal function to perform API requests to the World Bank API

Description

This function constructs and sends a request to the specified World Bank API resource, with options to specify the language, the number of results per page, a date range, and the data source. It also supports paginated requests and progress tracking.

Usage

perform_request(
  resource,
  language = NULL,
  per_page = 10000L,
  date = NULL,
  most_recent_only = NULL,
  source = NULL,
  progress = FALSE,
  base_url = "https://api.worldbank.org/v2/",
  max_tries = 10L
)

Arguments

Details

This internal helper function constructs the request URL using the base URL, language, resource, and other optional parameters (such as date and source), and performs the API request. For paginated results, it iterates through all pages and consolidates the data into a single output. The function handles API errors, providing detailed error messages when available.

Value

A list containing the parsed JSON response from the API. If the response contains multiple pages, the results are combined into a single list. If the API returns an error, it provides the relevant error message and documentation.

Download World Bank indicator data for specific entities and time periods

Description

This function retrieves indicator data from the World Bank API for a specified set of entities and indicators. The user can specify one or more indicators, a date range, and other options to tailor the request. The data is processed and returned in a tidy format, including country, indicator, date, and value fields.

Usage

wdi_get(
  entities,
  indicators,
  start_year = NULL,
  end_year = NULL,
  most_recent_only = FALSE,
  frequency = "annual",
  language = "en",
  per_page = 10000L,
  progress = TRUE,
  source = NULL,
  format = "long"
)

Arguments

Details

This function constructs a request URL for the World Bank API, retrieves the relevant data for the given entities and indicators, and processes the response into a tidy format. The user can optionally specify a date range, and the function will handle requests for multiple pages if necessary. If the progress parameter is TRUE, messages will be displayed during the request and parsing process.

The function supports downloading multiple indicators by sending individual API requests for each indicator and then combining the results into a single tidy data frame.

Value

A tibble with the following columns:

entity_id

The ISO 3-country code of the country or aggregate for which the data was retrieved.

indicator_id

The ID of the indicator (e.g., "NY.GDP.PCAP.KD").

year

The year of the indicator data as an integer.

quarter

Optional. The quarter of the indicator data as integer.

month

Optional. The month of the indicator data as integer.

value

The value of the indicator for the given country and date.

Examples

# Download single indicator for multiple entities
wdi_get(c("USA", "CAN", "GBR"), "NY.GDP.PCAP.KD")

# Download single indicator for a specific time frame
wdi_get(c("USA", "CAN", "GBR"), "DPANUSSPB",
        start_year = 2012, end_year = 2013)

# Download single indicator for monthly frequency
wdi_get("AUT", "DPANUSSPB",
        start_year = 2012, end_year = 2015, frequency = "month")

# Download single indicator for quarterly frequency
wdi_get("NGA", "DT.DOD.DECT.CD.TL.US",
        start_year = 2012, end_year = 2015, frequency = "quarter")

# Download single indicator for all entities and disable progress bar
wdi_get("all", "NY.GDP.PCAP.KD", progress = FALSE)

# Download multiple indicators for multiple entities
wdi_get(c("USA", "CAN", "GBR"), c("NY.GDP.PCAP.KD", "SP.POP.TOTL"))

# Download indicators for different sources
wdi_get("DEU", "SG.LAW.INDX", source = 2)
wdi_get("DEU", "SG.LAW.INDX", source = 14)

# Download indicators in wide format
wdi_get(c("USA", "CAN", "GBR"), c("NY.GDP.PCAP.KD"),
        format = "wide")
wdi_get(c("USA", "CAN", "GBR"), c("NY.GDP.PCAP.KD", "SP.POP.TOTL"),
        format = "wide")

# Download most recent value only
wdi_get("USA", "SP.POP.TOTL", most_recent_only = TRUE)

Download all countries and regions from the World Bank API

Description

This function retrieves information about entities (countries and regions) from the World Bank API. It returns a tibble containing various details such as the entity's ID, ISO2 code, name, region information, lending type, capital city, and coordinates.

Usage

wdi_get_entities(language = "en", per_page = 1000)

Arguments

Details

This function sends a request to the World Bank API to retrieve data for all supported entities in the specified language. The data is then processed into a tidy format and includes information about the country, such as its ISO code, capital city, geographical coordinates, and additional metadata about regions, income levels, and lending types.

Value

A tibble with the following columns:

entity_id

A character string representing the entity's unique identifier.

entity_name

A character string for the name of the entity.

entity_iso2code

A character string for the ISO2 country code.

entity_type

A character string for the type of the entity ("country" or "region").

region_id

A character string representing the region's unique identifier.

region_name

A character string for the name of the region.

region_iso2code

A character string for the ISO2 region code.

admin_region_id

A character string representing the administrative region's unique identifier.

admin_region_name

A character string for the name of the administrative region.

admin_region_iso2code

A character string for the ISO2 code of the administrative region.

income_level_id

A character string representing the entity's income level.

income_level_name

A character string for the name of the income level.

income_level_iso2code

A character string for the ISO2 code of the income level.

lending_type_id

A character string representing the lending type's unique identifier.

lending_type_name

A character string for the name of the lending type.

lending_type_iso2code

A character string for the ISO2 code of the lending type.

capital_city

A character string for the name of the capital city.

longitude

A numeric value for the longitude of the entity.

latitude

A numeric value for the latitude of the entity.

Examples

# Download all entities in English
wdi_get_entities()

# Download all entities in Spanish
wdi_get_entities(language = "zh")

Download income levels from the World Bank API

Description

This function returns a tibble of supported income levels for querying the World Bank API. The income levels categorize countries based on their gross national income per capita.

Usage

wdi_get_income_levels(language = "en")

Arguments

Details

This function provides a reference for the supported income levels, which categorize countries according to their income group as defined by the World Bank. The language parameter allows the results to be returned in different languages as supported by the API.

Value

A tibble with columns that typically include:

income_level_id

An integer identifier for the income level.

income_level_iso2code

A character string representing the ISO2 code for the income level.

income_level_name

The description of the income level (e.g., "Low income", "High income").

Source

https://api.worldbank.org/v2/incomeLevels

Examples

# Download all income levels in English
wdi_get_income_levels()

Download all available World Bank indicators

Description

This function retrieves a comprehensive list of all indicators supported by the World Bank API. The indicators include metadata such as the indicator ID, name, unit, source, and associated topics. The user can specify the language of the API response and whether to include additional details.

Usage

wdi_get_indicators(language = "en", per_page = 32500L)

Arguments

Details

This function makes a request to the World Bank API to retrieve metadata for all available indicators. It processes the response into a tidy tibble format.

Value

A tibble containing the available indicators and their metadata:

indicator_id

A character string for the ID of the indicator (e.g., "NY.GDP.PCAP.KD").

indicator_name

A character string for the name of the indicator (e.g., "GDP per capita, constant prices").

source_id

An integer identifying the data source providing the indicator.

source_name

A character string describing the source of the indicator data.

source_note

A character string providing additional notes about the data source.

source_organization

A character string denoting the organization responsible for the data source.

topics

A nested tibble containing (possibly multiple) topics associated with the indicator, with two columns: an integer topic_id and a character topic_name.

Examples

# Download all supported indicators in English
wdi_get_indicators()

# Download all supported indicators in Spanish
wdi_get_indicators(language = "es")

Download languages from the World Bank API

Description

This function returns a tibble of supported languages for querying the World Bank API. The supported languages include English, Spanish, French, Arabic, and Chinese, etc.

Usage

wdi_get_languages()

Details

This function provides a simple reference for the supported languages when querying the World Bank API.

Value

A tibble with three columns:

language_code

A character string representing the language code (e.g., "en" for English).

language_name

A character string representing the description of the language (e.g., "English").

native_form

A character string representing the native form of the language (e.g., "English").

Source

https://api.worldbank.org/v2/languages

Examples

# Download all languages
wdi_get_languages()

Download lending types from the World Bank API

Description

This function returns a tibble of supported lending types for querying the World Bank API. The lending types classify countries based on the financial terms available to them from the World Bank.

Usage

wdi_get_lending_types(language = "en")

Arguments

Details

This function provides a reference for the supported lending types, which classify countries according to the financial terms they are eligible for under World Bank programs. The language parameter allows the results to be returned in different languages as supported by the API.

Value

A tibble with columns that typically include:

lending_type_id

An integer for the lending type.

lending_type_iso2code

A character string for the ISO2 code of the lending type.

lending_type_name

A description of the lending type (e.g., "IBRD", "IDA").

Source

https://api.worldbank.org/v2/lendingTypes

Examples

# Download all lending types in English
wdi_get_lending_types()

Download regions from the World Bank API

Description

This function returns a tibble of supported regions for querying the World Bank API.The regions include various geographic areas covered by the World Bank's datasets.

Usage

wdi_get_regions(language = "en")

Arguments

Details

This function provides a reference for the supported regions, which are important for refining queries related to geographic data in the World Bank's datasets. The region_id column is unique for seven key regions.

Value

A tibble with the following columns:

region_id

An integer identifier for each region.

region_code

A character string representing the region code.

region_iso2code

A character string representing the ISO2 code for the region.

region_name

A character string representing the name of the region, in the specified language.

Source

https://api.worldbank.org/v2/region

Examples

# Download all regions
wdi_get_regions()

Download data sources from the World Bank API

Description

This function returns a tibble of supported data sources for querying the World Bank API. The data sources include various databases and datasets provided by the World Bank.

Usage

wdi_get_sources(language = "en")

Arguments

Details

This function provides a reference for the supported data sources and their metadata when querying the World Bank API. The columns is_data_available and is_metadata_available are logical values derived from the API response, where "Y" indicates availability.

Value

A tibble with six columns:

source_id

An integer identifier for the data source.

source_code

A character string for the source code.

source_name

The name of the data source (e.g., "World Development Indicators").

update_date

The last update date of the data source.

is_data_available

A boolean indicating whether data is available.

is_metadata_available

A boolean indicating whether metadata is available.

concepts

The number of concepts defined for the data source.

Source

https://api.worldbank.org/v2/sources

Examples

# Download all available data sources in English
wdi_get_sources()

Download topics from the World Bank API

Description

This function returns a tibble of supported topics for querying the World Bank API. Topics represent the broad subject areas covered by the World Bank's datasets.

Usage

wdi_get_topics(language = "en")

Arguments

Details

This function provides a reference for the supported topics that can be used to refine your queries when accessing the World Bank API. Topics represent different areas of focus for data analysis.

Value

A tibble with three columns:

id

The unique identifier for the topic.

value

The name of the topic (e.g., "Education", "Health").

source_note

A brief description or note about the topic.

Source

https://api.worldbank.org/v2/topics

Examples

# Download all available topics in English
wdi_get_topics()

Search for Keywords in Data Frame Columns

Description

This function searches for specified keywords across columns in a data frame and returns only the rows where at least one keyword appears in any of the specified columns. It supports nested columns (lists within columns) and provides the option to limit the search to specific columns.

Usage

wdi_search(data, keywords, columns = NULL)

Arguments

Value

A data frame containing only the rows where at least one keyword is found in the specified columns. The returned data frame has the same structure as data.

Examples

# Download indicators
indicators <- wdi_get_indicators()

# Search for keywords "inequality" or "gender" across all columns
wdi_search(
  indicators,
  keywords = c("inequality", "gender")
)

# Search for keywords only within the "indicator_name" column
wdi_search(
  indicators,
  keywords = c("inequality", "gender"),
  columns = c("indicator_name")
)