DOCSEARCHbyAlgolia
Submit Docs

world-bank-data Python Package

repository·main·Indexed 40 days ago

https://github.com/mwouts/world_bank_data

A high-performance Python implementation of the World Bank API v2 for exploring and retrieving World Development Indicators. It provides functions to fetch data series via `get_series()`, search for indicators, countries, and regions, and retrieve metadata such as topics, sources, income levels, and lending types. The library returns data as pandas DataFrames or Series and includes built-in LRU caching for metadata requests.

Tokens
5.9K
Snippets
28
Records
32
Agent score
45%

What's inside world-bank-data

  1. Understand caching behavior

    main
    To improve performance, all requests (except get_series) are cached using a least recently used (LRU) cache from the cachetools package. This means repeated calls for metadata like indicators or topics will be nearly instantaneous after the first request.

  3. Configure global language settings

    main

    The World Bank provides descriptions in multiple languages. You can set the language for all subsequent requests using wb.options.language.

    Supported values include 'en' (English), 'vi' (Vietnamese), etc.

    # Set language globally to Vietnamese
wb.options.language = 'vi'
wb.get_indicators('SP.POP.TOTL')

# Reset to English
wb.options.language = 'en'

  4. Configure global proxy settings

    main

    To use the package behind an HTTP proxy, you can either pass a proxies argument to individual get_* functions or set it globally via wb.options.proxies.

    # Set proxy globally
wb.options.proxies = {'http': 'http://example.com:3128'}

  5. Get lists of sources, topics, countries, and regions

    main

    Use the following functions to retrieve metadata about the World Bank datasets:

    • wb.get_topics(): Returns a list of available topics.
    • wb.get_sources(): Returns a list of available data sources.
    • wb.get_countries(): Returns a list of countries.
    • wb.get_regions(): Returns a list of regions.
    • wb.get_incomelevels(): Returns country income level classifiers.
    • wb.get_lendingtypes(): Returns country lending type classifiers.
    import pandas as pd
import world_bank_data as wb

# Example usage
topics = wb.get_topics()
sources = wb.get_sources()
countries = wb.get_countries()

  6. Get indicator values with get_series()

    main

    The wb.get_series(indicator_code, ...) function returns the values for a single indicator.

    Arguments:

    • indicator_code (str): The unique code for the indicator (e.g., 'SP.POP.TOTL').
    • mrv (int): Request one or more most recent values.
    • date (str): A single year or a range separated by a colon (e.g., '2010:2018').
    • gapfill (str): 'Y' or 'N' (default 'N'). If 'Y', it forward fills missing values.
    • simplify_index (bool): If True, ignores dimensions in the resulting index that contain only a single value (like year or series).
    • id_or_value (str): Set to 'id' if you prefer the data to be indexed by codes rather than labels.
    # Get the most recent estimate for World Population
wb.get_series('SP.POP.TOTL', mrv=1)

# Get data for 2016, indexed by ID, with a simplified index
wb.get_series('SP.POP.TOTL', date='2016', id_or_value='id', simplify_index=True)

  7. Search for countries, sources, or indicators

    main

    Use the following functions to search for specific entities:

    • wb.search_countries(query)
    • wb.search_source(query)
    • wb.search_indicators(query)

    If you are working with an existing DataFrame, you can also use the search method.

    # Search for indicators related to 'mathematics'
wb.search_indicators('mathematics')

  8. Get the list of indicators

    main

    Use wb.get_indicators() to retrieve the list of available indicators. If no arguments are provided, it returns all 16,000+ indicators (this result is cached for subsequent calls).

    You can filter the list by providing a specific topic or source ID obtained from get_topics() or get_sources().

    # Query indicators for a specific topic and source
wb.get_indicators(topic=3, source=2)

  9. Collapse multiple values into a semicolon-separated string

    main

    The collapse(values) utility converts various input types into a single string suitable for World Bank API queries.

    • Strings: Returned as-is.
    • None: Returns the string 'all'.
    • Lists: Recursively collapses each element and joins them with a semicolon (;).
    • Other types: Converted to their string representation.

  10. Retrieve indicator metadata with get_indicators()

    main

    Use get_indicators() to return a pandas DataFrame describing one, multiple, or all indicators. The resulting DataFrame is indexed by the indicator ID.

    Parameters:

    • indicator: None (to get all indicators), a single indicator ID (string), or a list of multiple IDs.
    • language: The desired language for the indicator descriptions.
    • id_or_value: Determines whether the 'source' and 'topics' columns contain IDs or human-readable values. If set to 'iso2code', it is treated as 'id'.
    • **params: Additional arguments passed to the underlying World Bank API request.
    import world_bank_data

# Get all indicators
all_indicators = world_bank_data.get_indicators()

# Get a specific indicator by ID
indicator_info = world_bank_data.get_indicators(indicator='SP.POP.TOTL')

# Get multiple indicators
multiple_indicators = world_bank_data.get_indicators(indicator=['SP.POP.TOTL', 'NY.GDP.MKTP.CD'])

  11. Retrieve regions with get_regions()

    main

    Use get_regions() to return a pandas DataFrame describing one, multiple, or all regions, indexed by the region ID.

    Parameters:

    • region: None (to get all regions), a single region ID string, or a list of multiple region ID strings.
    • language: The desired language for the descriptions.
    • **params: Additional keyword arguments passed to the underlying request handler.
    from world_bank_data import get_regions

# Get all regions
all_regions = get_regions()

# Get a specific region by ID
specific_region = get_regions(region='EMU')

# Get multiple specific regions
multiple_regions = get_regions(region=['EMU', 'NAC'])

  12. Retrieve income levels with get_incomelevels()

    main

    Use get_incomelevels() to return a pandas DataFrame describing one, multiple, or all income levels, indexed by the income level (IL) ID.

    Parameters:

    • incomelevel: None (to get all income levels), a single income level ID, or a list of multiple income level IDs.
    • language: The desired language for the descriptions.
    • **params: Additional keyword arguments passed to the underlying request handler.
    from world_bank_data import get_incomelevels

# Get all income levels
all_income_levels = get_incomelevels()