repository·main·Indexed 25 days ago
https://github.com/pydata/pandas-datareaderA library for accessing macroeconomic and factor-oriented remote data sources directly into pandas DataFrames. It provides readers for providers including FRED, World Bank, OECD, Eurostat, Fama/French, and the Bank of Canada. The library includes a macro module for unified data access and a modern API for OECD and Eurostat data that returns structured MacroResult objects.
If you need the latest features from the development branch, you can install directly from GitHub using one of the following methods:
Option 1: Direct pip install from git
pip install git+https://github.com/pydata/pandas-datareader.gitOption 2: Clone and editable install
git clone https://github.com/pydata/pandas-datareader.git
cd pandas-datareader
python -m pip install -e .To avoid repeated bandwidth usage, slow execution, or IP bans, you can cache queries in pandas-datareader by passing a requests_cache.Session object to the session parameter of the DataReader function. This is supported for maintained public data readers (e.g., fred).
When using a CachedSession with a sqlite backend, a file named cache.sqlite will be created in your working directory to store requests until they expire.
import pandas_datareader.data as web
import datetime
import requests_cache
# Define cache expiration (e.g., 3 days)
expire_after = datetime.timedelta(days=3)
# Initialize a CachedSession
session = requests_cache.CachedSession(cache_name='cache', backend='sqlite', expire_after=expire_after)
start = datetime.datetime(2010, 1, 1)
end = datetime.datetime(2013, 1, 27)
# Pass the session to DataReader
f = web.DataReader("VIXCLS", 'fred', start, end, session=session)
print(f.head())To install the stable version of pandas-datareader, use pip.
pip install pandas-datareaderAfter installing, you can import pandas_datareader and use specific data readers to fetch remote data. For example, you can use get_data_fred to read 5-years of 10-year constant maturity yields on U.S. government bonds from FRED.
import pandas_datareader as pdr
pdr.get_data_fred('GS10')The pandas_datareader.macro submodule provides a modern API for accessing OECD and Eurostat data directly via their current interfaces. This API returns a structured MacroResult object instead of a raw DataFrame, ensuring metadata and data are kept together.
Top-level functions:
read_macro(provider, dataset, *, start=None, end=None, filters=None, session=None, **kwargs) -> MacroResult:
Reads macro data for a specific provider and dataset.search_macro_datasets(provider, query=None, *, session=None, **kwargs) -> pd.DataFrame:
Searches for available datasets within a provider.describe_macro_dataset(provider, dataset, *, session=None, **kwargs) -> dict:
Returns metadata describing a specific dataset.Supported Providers:
OECDClient (via OECD SDMX endpoints)EurostatClient (via Eurostat SDMX 2.1 endpoints)The macro API uses specific exception types to categorize failures:
MacroNotFoundError: Raised when a provider returns a 404 or the dataset is unknown.MacroSchemaError: Raised when an unexpected live schema change is detected.MacroProviderError: Raised during request timeouts, operational failures, or general provider issues.MacroDataError: General error related to macro data processing.access_key keyword argument in DataReader has been deprecated. Use api_key instead.The public API provides access to macroeconomic, policy, and factor-style data sources including FRED, Fama/French, Bank of Canada, World Bank, OECD, Eurostat, and the pandas_datareader.macro interface. You can use functions like get_data_fred to retrieve specific series.
import pandas_datareader as pdr
pdr.get_data_fred('GS10')pandas_datareader.fred module to retrieve economic data from the Federal Reserve Economic Data (FRED) database. The primary interface is the FredReader class, which provides a read method to fetch time series data.pandas_datareader.econdb module provides an EcondbReader class to retrieve economic data from the Economic Data (Econdb) service. You can use this reader to fetch datasets directly into pandas DataFrames.api_key argument in get_data_econdb, by setting the ECONDB_API_KEY environment variable, or via an explicit token=... query parameter.The pandas_datareader.macro module provides a unified routing layer and provider-specific clients for maintained macro sources like eurostat and oecd. It includes functions for searching datasets, reading data, and describing dataset metadata.
from pandas_datareader.macro import (
describe_macro_dataset,
read_macro,
search_macro_datasets,
)
# Read specific dataset
euro = read_macro("eurostat", "ert_h_eur_a", start="2009-01-01", end="2010-01-01")
# Search for datasets
flows = search_macro_datasets("oecd", query="trade union")
# Get metadata for a dataset
meta = describe_macro_dataset("eurostat", "ert_h_eur_a")