Basic functionality

The basic functionality for wbdata users is provided by a set of functions in the topic level package namespace.

Data Retrieval

These are the functions for actually getting data values from the World Bank API.

Raw Data Retrieval

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

Pandas Data Retrieval

These functions require Pandas to be installed to work.

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.

Metadata Retrieval

These functions, for the most part, are for finding the parameters you want to put into the data retrieval functions. These all return SearchResult, which are lists that pretty-print the table in an interactive environment, and which contain dictionary representations of the requested resource.

Searchable Metadata

There are enough indicators and countries that it's annoying to look through them, so the functions for retrieving information about them can be narrowed with additional facets and filtered with a search term or regular expression supplied to the query parameter.

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

Indicator Facets

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_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

Country Facets

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_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