
<!-- README.md is generated from README.Rmd. Please edit that file -->

# worldbank

<!-- badges: start -->

[![R-CMD-check](https://github.com/m-muecke/worldbank/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/m-muecke/worldbank/actions/workflows/R-CMD-check.yaml)
[![CRAN
status](https://www.r-pkg.org/badges/version/worldbank)](https://CRAN.R-project.org/package=worldbank)
[![R-universe
version](https://m-muecke.r-universe.dev/worldbank/badges/version)](https://m-muecke.r-universe.dev/worldbank)
<!-- badges: end -->

## Overview

worldbank provides a simple interface to the following [World
Bank](https://datahelpdesk.worldbank.org/knowledgebase/articles/889386-developer-information-overview)
APIs:

- [Indicators API
  v2](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation)
- [Poverty and Inequality Platform (PIP)
  API](https://pip.worldbank.org/api)
- [Finances One API](https://financesone.worldbank.org)
- [Projects API v2](https://search.worldbank.org/api/v2/projects)

The main difference to other packages is that it’s a modern
implementation using the [httr2](https://httr2.r-lib.org) package and
supports all available endpoints and parameters.

## Installation

You can install the released version of **worldbank** from
[CRAN](https://CRAN.R-project.org) with:

``` r
install.packages("worldbank")
```

And the development version from [GitHub](https://github.com/) with:

``` r
# install.packages("pak")
pak::pak("m-muecke/worldbank")
```

## Usage

worldbank functions are prefixed with `wb_` and follow the naming
convention of the [World Bank API
v2](https://datahelpdesk.worldbank.org/knowledgebase/articles/889392-about-the-indicators-api-documentation).

``` r
library(worldbank)

# filter by specific country
wb_country(c("US", "DE"))
#>   country_id country_code  country_name region_id region_code
#> 1        DEU           DE       Germany       ECS          Z7
#> 2        USA           US United States       NAC          XU
#>            region_value admin_region_id admin_region_code admin_region_value
#> 1 Europe & Central Asia            <NA>              <NA>               <NA>
#> 2         North America            <NA>              <NA>               <NA>
#>   income_level_id income_level_code income_level_value lending_type_id
#> 1             HIC                XD        High income             LNX
#> 2             HIC                XD        High income             LNX
#>   lending_type_code lending_type_value    capital_city longitude latitude
#> 1                XX     Not classified          Berlin   13.4115  52.5235
#> 2                XX     Not classified Washington D.C.  -77.0320  38.8895

# or fetch all (default)
country <- wb_country()
str(country)
#> 'data.frame':    295 obs. of  18 variables:
#>  $ country_id        : chr  "ABW" "AFE" "AFG" "AFR" ...
#>  $ country_code      : chr  "AW" "ZH" "AF" "A9" ...
#>  $ country_name      : chr  "Aruba" "Africa Eastern and Southern" "Afghanista"..
#>  $ region_id         : chr  "LCN" "NA" "MEA" "NA" ...
#>  $ region_code       : chr  "ZJ" "NA" "ZQ" "NA" ...
#>  $ region_value      : chr  "Latin America & Caribbean" "Aggregates" "Middle "..
#>  $ admin_region_id   : chr  NA NA "MNA" NA ...
#>  $ admin_region_code : chr  NA NA "XQ" NA ...
#>  $ admin_region_value: chr  NA NA "Middle East, North Africa, Afghanistan & P"..
#>  $ income_level_id   : chr  "HIC" "NA" "LIC" "NA" ...
#>  $ income_level_code : chr  "XD" "NA" "XM" "NA" ...
#>  $ income_level_value: chr  "High income" "Aggregates" "Low income" "Aggregat"..
#>  $ lending_type_id   : chr  "LNX" NA "IDX" NA ...
#>  $ lending_type_code : chr  "XX" NA "XI" NA ...
#>  $ lending_type_value: chr  "Not classified" "Aggregates" "IDA" "Aggregates" ...
#>  $ capital_city      : chr  "Oranjestad" NA "Kabul" NA ...
#>  $ longitude         : num  -70 NA 69.2 NA NA ...
#>  $ latitude          : num  12.5 NA 34.5 NA NA ...

# search for indicators by keyword across id, name, and description
ind <- wb_search("GDP")
ind <- subset(ind, source_value == "World Development Indicators")
str(ind)
#> 'data.frame':    103 obs. of  9 variables:
#>  $ id                 : chr  "BG.GSR.NFSV.GD.ZS" "BM.KLT.DINV.WD.GD.ZS" "BN.C"..
#>  $ name               : chr  "Trade in services (% of GDP)" "Foreign direct i"..
#>  $ unit               : chr  NA NA NA NA ...
#>  $ source_id          : int  2 2 2 2 2 2 2 2 2 2 ...
#>  $ source_value       : chr  "World Development Indicators" "World Developmen"..
#>  $ source_note        : chr  "Total trade in services includes services provi"..
#>  $ source_organization: chr  "Balance of Payments Statistics Yearbook and dat"..
#>  $ topic_id           : int  3 3 3 3 3 7 7 5 5 5 ...
#>  $ topic_value        : chr  "Economy & Growth" "Economy & Growth" "Economy &"..

# fetch indicator data for specific or all countries (default)
gdp <- wb_data("NY.GDP.MKTP.CD", c("US", "DE", "FR", "CH", "JP"))
str(gdp)
#> 'data.frame':    330 obs. of  10 variables:
#>  $ date          : int  2025 2024 2023 2022 2021 2020 2019 2018 2017 2016 ...
#>  $ indicator_id  : chr  "NY.GDP.MKTP.CD" "NY.GDP.MKTP.CD" "NY.GDP.MKTP.CD" "N"..
#>  $ indicator_name: chr  "GDP (current US$)" "GDP (current US$)" "GDP (current"..
#>  $ country_id    : chr  "CH" "CH" "CH" "CH" ...
#>  $ country_name  : chr  "Switzerland" "Switzerland" "Switzerland" "Switzerlan"..
#>  $ country_code  : chr  "CHE" "CHE" "CHE" "CHE" ...
#>  $ value         : num  1.04e+12 9.70e+11 9.28e+11 8.58e+11 8.41e+11 ...
#>  $ unit          : chr  NA NA NA NA ...
#>  $ obs_status    : chr  NA NA NA NA ...
#>  $ decimal       : int  0 0 0 0 0 0 0 0 0 0 ...

# plot the indicator data
library(ggplot2)

subset(gdp, date >= 1980) |>
  ggplot(aes(x = date, y = value, color = country_name)) +
  geom_line() +
  theme_minimal() +
  theme(
    legend.title = element_blank(),
    legend.position = "bottom",
    plot.title = element_text(face = "bold"),
    panel.grid.major.y = element_line(color = "black", linewidth = 0.2),
    panel.grid.major.x = element_blank(),
    panel.grid.minor = element_blank(),
    axis.text = element_text(color = "black"),
    axis.title = element_blank()
  ) +
  scale_y_continuous(
    labels = scales::label_currency(scale_cut = scales::cut_short_scale())
  ) +
  labs(title = "GDP in Current U.S. Dollars", color = "Country")
```

<img src="man/figures/README-demo-1.png" alt="" width="100%" />

## Related work

- [WDI](https://github.com/vincentarelbundock/WDI): R package to
  download World Bank data
- [pipr](https://github.com/worldbank/pipr): R client for the PIP
  Worldbank API
- [wbstats](https://github.com/gshs-ornl/wbstats): R package for
  searching and downloading data from the World Bank API
- [wbwdi](https://github.com/tidy-intelligence/r-wbwdi): R package to
  download World Bank indicator data
