Client Module

The client class defines the wbdata client class and associated support classes.

SearchResult

Bases: List

A list that prints out a user-friendly table when printed or returned on the command line

Items are expected to be dict-like and have an "id" key and a "name" or "value" key

Series

Bases: Series

A pandas.Series with a last_updated attribute.

The last_updated attribute is set when the Series is created but not automatically updated. Its value is either None or a datetime.datetime object.

DataFrame

Bases: DataFrame

__init__(*args, serieses=None, **kwargs)

A pandas.DataFrame with a last_updated attribute

The last_updated attribute is set when the Series is created but not automatically updated. Its value is a dictionary where the keys are the column names and the values are None or a datetime.datetime object.

Client dataclass

The client object for the World Bank API.

Most users will only need to create this if they need more than one cache, want to specify a cache programmatically rather than through environment variables, or want to specify a requests Session.

Parameters:
  • cache_path (Union[str, Path, None], default: None ) –

    path to the cache file

  • cache_ttl_days (Union[int, None], default: None ) –

    number of days to retain cached results

  • cache_max_size (Union[int, None], default: None ) –

    number of items to retain in the cache

  • session (Union[Session, None], default: None ) –

    requests Session object to use to make requests

get_data(indicator, country='all', date=None, freq='Y', source=None, parse_dates=False, skip_cache=False)

Retrieve indicators for given countries and years

Parameters:
  • indicator (str) –

    the desired indicator code

  • country (Union[str, Sequence[str]], default: 'all' ) –

    a country code, sequence of country codes, or "all" (default)

  • date (Union[str, datetime, Tuple[Union[str, datetime], Union[str, datetime]], None], default: None ) –

    the desired date as a string, datetime object or a 2-tuple with start and end dates

  • freq (str, default: 'Y' ) –

    the desired periodicity of the data, one of 'Y' (yearly), 'M' (monthly), or 'Q' (quarterly). The indicator may or may not support the specified frequency.

  • source (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    the specific source to retrieve data from (defaults on API to 2, World Development Indicators)

  • parse_dates (bool, default: False ) –

    if True, convert date field to a datetime.datetime object.

  • skip_cache (bool, default: False ) –

    bypass the cache when downloading
Returns:
  • Result –

    A list of dictionaries of observations

get_sources(source_id=None, skip_cache=False)

Retrieve information on one or more sources

Parameters:
  • source_id (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    a source id or sequence thereof. None returns all sources

  • skip_cache (bool, default: False ) –

    bypass cache when downloading
Returns:
  • SearchResult –

    list of dictionary objects describing selected sources

get_incomelevels(level_id=None, skip_cache=False)

Retrieve information on one or more income level aggregates

Parameters:
  • level_id (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    a level id or sequence thereof. None returns all income level aggregates

  • skip_cache (bool, default: False ) –

    bypass cache when downloading
Returns:
  • SearchResult –

    list of dictionary objects describing selected income level aggregates

get_topics(topic_id=None, skip_cache=False)

Retrieve information on one or more topics

Parameters:
  • topic_id (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    a topic id or sequence thereof. None returns all topics

  • skip_cache (bool, default: False ) –

    bypass cache when downloading
Returns:
  • SearchResult –

    list of dictionary objects describing selected topic aggregates

get_lendingtypes(type_id=None, skip_cache=False)

Retrieve information on one or more lending type aggregates

Parameters:
  • type_id (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    lending type id or sequence thereof. None returns all lending type aggregates

  • skip_cache (bool, default: False ) –

    bypass cache when downloading
Returns:
  • SearchResult –

    list of dictionary objects describing selected lending type aggregates

get_countries(country_id=None, query=None, incomelevel=None, lendingtype=None, skip_cache=False)

Retrieve information on one or more country or regional aggregates.

You can filter your results by specifying query,incomelevel, orlendingtype. Specifyingquery` will only return countries with names that match the query as a regular expression. If a string is supplied, the match is case insensitive.

Specifying query, incomelevel, or lendingtype along with country_id will raise a ValueError.

Parameters:
  • country_id (Union[str, Sequence[str], None], default: None ) –

    a country id or sequence thereof. None returns all countries and aggregates.

  • query (Union[str, Pattern, None], default: None ) –

    a regular expression on which to filter results

  • incomelevel (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    desired incomelevel id or ids on which to filter results

  • lendingtype (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    desired lendingtype id or ids on which to filter results

  • skip_cache (bool, default: False ) –

    bypass cache when downloading
Returns:
  • SearchResult –

    list of dictionaries describing countries

get_indicators(indicator=None, query=None, source=None, topic=None, skip_cache=False)

Retrieve information about an indicator or indicators.

When called with no arguments, returns all indicators. You can specify one or more indicators to retrieve, or you can specify a source or a topic for which to list all indicators. Specifying more than one of indicators, source, and topic will raise a ValueError.

Specifying query will only return indicators with names that match the query as a regular expression. If a string is supplied, the match is case insensitive. Specifying both query and indicators will raise a ValueError.

Parameters:
  • indicator (Union[str, Sequence[str], None], default: None ) –

    an indicator code or sequence thereof

  • query (Union[str, Pattern, None], default: None ) –

    a regular expression on which to filter results

  • source (Union[str, int, Sequence[Union[str, int]], None], default: None ) –

    a source id or sequence thereof

  • topic (Union[str, int, Sequence[Union[str, int]], None], default: None ) –

    a topic id or sequence thereof

  • skip_cache (bool, default: False ) –

    bypass cache when downloading
Returns:
  • SearchResult –

    list of dictionary objects representing indicators

get_series(indicator, country='all', date=None, freq='Y', source=None, parse_dates=False, name='value', keep_levels=False, skip_cache=False)

Retrieve data for a single indicator as a pandas Series.

If pandas is not installed, a RuntimeError will be raised.

Parameters:
  • indicator (str) –

    the desired indicator code

  • country (Union[str, Sequence[str]], default: 'all' ) –

    a country code, sequence of country codes, or "all" (default)

  • date (Union[str, datetime, Tuple[Union[str, datetime], Union[str, datetime]], None], default: None ) –

    the desired date as a string, datetime object or a 2-tuple with start and end dates

  • freq (str, default: 'Y' ) –

    the desired periodicity of the data, one of 'Y' (yearly), 'M' (monthly), or 'Q' (quarterly). The indicator may or may not support the specified frequency.

  • source (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    the specific source to retrieve data from (defaults on API to 2, World Development Indicators)

  • parse_dates (bool, default: False ) –

    if True, convert date field to a datetime.datetime object.

  • skip_cache (bool, default: False ) –

    bypass the cache when downloading

  • name (str, default: 'value' ) –

    the desired name for the pandas Series

  • keep_levels (bool, default: False ) –

    if True don't reduce the number of index levels returned if only getting one date or country

  • skip_cache (bool, default: False ) –

    bypass the cache when downloading
Returns:
  • Series –

    Series with the requested data. The index of the series depends on the data returned and the specified options. If the data spans multiple dates and countries or if keep_levels is True, the index will be a 2-level MultiIndex with levels "country" and "name". If keep_levels is False (the default) and the data only has one country or date, the level with only one value will be dropped. If keep_levels is False and both levels only have one value, the country level is dropped.

get_dataframe(indicators, country='all', date=None, freq='Y', source=None, parse_dates=False, keep_levels=False, skip_cache=False)

Download a set of indicators and merge them into a pandas DataFrame.

If pandas is not installed, a RuntimeError will be raised.

Parameters:
  • indicators (Dict[str, str]) –

    An dictionary where the keys are desired indicators and the values are the desired column names

  • country (Union[str, Sequence[str]], default: 'all' ) –

    a country code, sequence of country codes, or "all" (default)

  • date (Union[str, datetime, Tuple[Union[str, datetime], Union[str, datetime]], None], default: None ) –

    the desired date as a string, datetime object or a 2-tuple with start and end dates

  • freq (str, default: 'Y' ) –

    the desired periodicity of the data, one of 'Y' (yearly), 'M' (monthly), or 'Q' (quarterly). The indicator may or may not support the specified frequency.

  • source (Union[int, str, Sequence[Union[int, str]], None], default: None ) –

    the specific source to retrieve data from (defaults on API to 2, World Development Indicators)

  • parse_dates (bool, default: False ) –

    if True, convert date field to a datetime.datetime object.

  • skip_cache (bool, default: False ) –

    bypass the cache when downloading

  • keep_levels (bool, default: False ) –

    if True don't reduce the number of index levels returned if only getting one date or country

  • skip_cache (bool, default: False ) –

    bypass the cache when downloading
Returns:
  • DataFrame –

    DataFrame with one column per indicator. The index of the DataFrame depends on the data returned and the specified options. If the data spans multiple dates and countries or if keep_levels is True, the index will be a 2-level MultiIndex with levels "country" and "name". If keep_levels is False (the default) and the data only has one country or date, the level with only one value will be dropped. If keep_levels is False and both levels only have one value, the country level is dropped.