DOCSEARCHbyAlgolia
Submit Docs

WBGAPI Python Library

repository·master·Indexed 41 days ago

https://github.com/tgherzog/wbgapi

A Python library providing pythonic access to the World Bank's data API. It allows users to retrieve data as pandas DataFrames or Python dictionaries, explore indicators, countries, and regions, and handle multiple World Bank databases. Key features include the `wb.data.DataFrame()` method for data retrieval, `wb.economy.coder()` for resolving country names to ISO codes, and specialized submodules for series, economy, time, and regions.

Tokens
5.7K
Snippets
28
Records
29
Agent score
51%

What's inside WBGAPI

  1. How WBGAPI sub-packages and functions work

    master

    WBGAPI is organized into sub-packages representing major World Bank API features (e.g., series, economy, time, source, region, income, lending, topic).

    Each sub-package implements a consistent set of four functions for accessing and displaying elements:

    • list: Returns a Python generator of elements.
    • get: Returns a single specific element (e.g., wb.series.get('SP.POP.TOTL')).
    • info: Returns a human-readable table (ideal for interactive use).
    • Series: Returns a pandas Series object.
    import wbgapi as wb

# Example of using different access methods for series
series_list = wb.series.list()
series_info = wb.series.info()
series_pd = wb.series.Series()

  2. Querying multi-dimensional databases (e.g., WDI Archives)

    master

    While most databases use 3 dimensions (series, economy, time), some contain a 4th dimension like version. Use wb.source.concepts(db=ID) to identify the dimensions available in a specific database, then pass the extra dimension as a parameter to wb.data.DataFrame.

    import wbgapi as wb

# Check dimensions for database 57
print(wb.source.concepts(db=57))

# Querying with a 'version' dimension (YYYYMM format)
# This example queries Brazil's population for years 2000-2004 across specific April versions
df = wb.data.DataFrame('SP.POP.TOTL', 'BRA', range(2000, 2005), version=range(201004, 202004, 100), db=57)

  3. Quick Start with WBGAPI

    master

    Import the module using the wb namespace to begin interacting with the World Bank API. The library includes extensive docstrings for exploring its capabilities.

    import wbgapi as wb

# Explore the module
help(wb)
help(wb.series)

  6. Explore API content using `info()` and `search()`

    master

    Use the info() method on sub-packages to inspect available data. You can filter results by passing identifiers or using keyword searches.

    Keyword Search Rules:

    • Use q='keyword' for standard searches. This ignores the parenthetical part of indicator names (e.g., q='GDP' will not match "Gross domestic savings (% of GDP)").
    • Use q='!keyword' to include the parenthetical part in the search (e.g., q='!GDP').

    If info() is insufficient, use wb.search('query') for a deeper search across all metadata in the current database.

    import wbgapi as wb

# List available databases
wb.source.info()

# Inspect series in the default database (WDI)
wb.series.info()

# Inspect economies in a specific database (e.g., Debt Statistics, db=6)
wb.economy.info(db=6)

# Filter info by specific identifiers
wb.series.info('NY.GDP.PCAP.CD')
wb.economy.info(['CAN', 'USA', 'MEX'])

# Keyword search
wb.series.info(q='women')
wb.series.info(q='!GDP')

# Deep search
wb.search('fossil fuels')

  7. How wbgapi submodules and common functions work

    master

    wbgapi is organized into 9 submodules that correspond to major components of the World Bank API. Each submodule provides common functions to explore the data structure.

    Submodules:

    • source: Databases
    • series: Indicators
    • economy: Countries/economies/aggregates
    • data: Data
    • topic: Indicator topics
    • time: Time
    • region: Regions
    • income: Income Groups
    • lending: Lending types

    Common Functions:

    • info(): Returns a human-readable table of elements.
    • list(): Returns elements one at a time.
    • get(): Returns a single element.
    • Series(): Returns a pandas Series.
    import wbgapi as wb

# Examples of common functions
wb.time.info()
wb.economy.list()
wb.series.get('SP.POP.TOTL')
wb.income.Series()

  8. Configure proxy servers and HTTP options

    master

    WBGAPI uses the requests library for all HTTP/HTTPS calls. To pass additional parameters to requests.get (such as proxy settings or disabling SSL verification), use the wb.get_options module variable.

    Note: Using wb.proxies is deprecated and will raise a DeprecationWarning.

    wb.get_options['proxies'] = {
   'http': 'http://10.10.1.10:3128',
   'https': 'http://10.10.1.10:1080',
}

  9. Access non-standard dimensions like WDI versions

    master

    While most databases use series, country, and time, some (like the WDI Archives, db=57) include extra dimensions such as version.

    1. Discover concepts for a specific database: wb.source.concepts(db=57).
    2. Fetch features for a dimension: wb.source.features('version', db=57).
    3. Pass the extra dimension as a parameter to wb.data.DataFrame (e.g., version=...).
    # Querying population across different WDI versions (April releases)
df = wb.data.DataFrame('SP.POP.TOTL', 'BRA', db=57, time=range(2000, 2020),
                       version=range(201004, 202004, 100), index='time')

  10. Calculate weighted averages using WBGAPI data

    master

    To calculate a weighted average (e.g., weighting an indicator by population), you must fetch both the indicator and the weight variable in a single DataFrame using a multi-index.

    Steps:

    1. Fetch both indicators with index=['series', 'economy'].
    2. Use .xs() to extract the specific indicator and the weight variable.
    3. Crucial: Mask out rows where the weight variable is NaN for the observations present in the indicator variable to ensure the denominator is correct.
    4. Calculate: (indicator * weight).sum() / weight.sum().
    # 1. Fetch combined data
combined = wb.data.DataFrame(['EG.ELC.ACCS.ZS', 'SP.POP.TOTL'], ['BRA', 'COL', 'PER'],
                             time=range(1990, 1996), index=['series', 'economy'])

# 2. Extract components
elec_access = combined.xs('EG.ELC.ACCS.ZS')
pop = combined.xs('SP.POP.TOTL')

# 3. Mask NaN values in the weight variable to match the indicator's availability
combined_masked = combined[elec_access.isna() == False]

# 4. Calculate weighted average
# Note: Re-extracting from masked data or using the original pop with masking
weighted_avg = (elec_access * pop).sum() / pop.sum()

  12. Fetch data as dictionaries or pandas DataFrames

    master

    The wb.data sub-package is used to request actual data values. You can retrieve data as rows of dictionaries or as a pandas DataFrame.

    Parameters:

    • series: A single identifier, a list of identifiers, or 'all'.
    • economy: A single identifier, a list of identifiers, or 'all'.
    • time: A single year, a range, or 'all'.

    Key Methods:

    • wb.data.fetch(series, economy, time): Returns rows as dictionary objects.
    • wb.data.DataFrame(series, economy, time, ...): Returns a pandas DataFrame. Supports parameters like mrv (most recent values), skipBlanks, and columns to control the shape of the resulting DataFrame.
    import wbgapi as wb

# Fetch all years for a specific series and economy as dictionaries
for row in wb.data.fetch('SP.POP.TOTL', 'USA'):
    print(row)

# Fetch most recent 5 years for multiple series as a DataFrame
df = wb.data.DataFrame(['NY.GDP.PCAP.CD', 'SP.POP.TOTL'], 'CAN', mrv=5)

# Fetch population for African countries for a specific range of years
df_africa = wb.data.DataFrame('SP.POP.TOTL', wb.region.members('AFR'), range(2010, 2020, 2))

# Customizing DataFrame columns and skipping blanks
df_custom = wb.data.DataFrame(['SP.POP.TOTL', 'EN.ATM.CO2E.KT'], time=range(2000, 2020), skipBlanks=True, columns='series')