series module

The series module provides functions to request data from the FRED API Sources endpoints.

SeriesApiParameters

Bases: BaseModel

Represents the parameters accepted by the FRED Series endpoints.

SeriesInfo

Bases: BaseModel

Represents metadata about an economics data series. Endpoint documentation.

open_url

open_url()

Open the FRED webpage for the given series.

SeriesSearchParameters

Bases: BaseModel

Represents the parameters accepted by the FRED Series Search endpoints.

get_series

get_series(series_id: str, api_key: ApiKeyType = None, return_format: ReturnFormats = 'pandas', **kwargs: KwargsType) -> ReturnTypes

Get the observations or data values for an economic data series by ID. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
return_format	Literal[json, pandas] | ReturnFormat	Define how to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.	'pandas'
**kwargs	dict	Additional parameters to FRED API series/observations endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict | DataFrame | DataFrame

get_series_all_releases

get_series_all_releases(series_id: str, api_key: ApiKeyType = None, return_format: ReturnFormats = 'pandas', **kwargs: KwargsType) -> ReturnTypes

Get the observations or data values for all releases an economic data series by ID.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
return_format	Literal['json', 'pandas', 'polars'] | ReturnFormat	In what format to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.	'pandas'
**kwargs	dict	Additional parameters to FRED API series/observation endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict | DataFrame | DataFrame

get_series_asof_date

get_series_asof_date(series_id: str, date: str, api_key: ApiKeyType = None, return_format: ReturnFormats = 'pandas', **kwargs: KwargsType) -> ReturnTypes

Get the observations or data values for an economic data series made on or before a specific date.

Retrieves the latest data known for the series as of the date provided. This includes any revisions to the data series made before or on the date, but excludes any revisions made after the date.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
date	str	Include only data revisions made on or before this date.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
return_format	Literal['json', 'pandas'] | ReturnFormat	In what format to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.	'pandas'
**kwargs	dict	Additional parameters to FRED API series/observation endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict | DataFrame | DataFrame

get_series_categories

get_series_categories(series_id: str, api_key: ApiKeyType = None, **kwargs: KwargsType) -> JsonType

Get the categories for an economic data series by ID. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
**kwargs	dict	Additional parameters to FRED API series/categories endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict	Dictionary representing the json response.

get_series_info

get_series_info(series_id: str, api_key: ApiKeyType = None, **kwargs: KwargsType) -> SeriesInfo

Get an economic data series information by ID. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
**kwargs	dict	Additional parameters to FRED API series/ endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
SeriesInfo	An instance of SeriesInfo.

get_series_initial_release

get_series_initial_release(series_id: str, api_key: ApiKeyType = None, return_format: ReturnFormats = 'pandas', **kwargs: KwargsType) -> ReturnTypes

Get the observations or data values for the initial release of an economic data series.

Includes only the the initial release of the series and excludes all revisions.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
return_format	Literal['json', 'pandas', 'polars'] | ReturnFormat	In what format to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.	'pandas'
**kwargs	dict	Additional parameters to FRED API series/observation endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict | DataFrame | DataFrame

get_series_releases

get_series_releases(series_id: str, api_key: ApiKeyType = None, **kwargs: KwargsType) -> JsonType

Get the FRED release for an economic data series by ID. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
**kwargs	dict	Additional parameters to FRED API series/releases endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict	Dictionary representing the json response.

get_series_tags

get_series_tags(series_id: str, api_key: ApiKeyType = None, **kwargs: KwargsType) -> JsonType

Get the FRED tags for an economic data series by ID. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
**kwargs	dict	Additional parameters to FRED API series/tags endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict	Dictionary representing the json response.

get_series_updates

get_series_updates(series_id: str, api_key: ApiKeyType = None, **kwargs: KwargsType) -> JsonType

Get the FRED updates for an economic data series by ID. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
**kwargs	dict	Additional parameters to FRED API series/updates endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict	Dictionary representing the json response.

get_series_vintagedates

get_series_vintagedates(series_id: str, api_key: ApiKeyType = None, **kwargs: KwargsType) -> List[str]

Get the dates in history when a series' data values were revised or new data values were released.

Vintage dates are the release dates for a series excluding release dates when the data did not change. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
**kwargs	dict	Additional parameters to FRED API series/vintagedates endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
List[str]	List of strings representing the the available vintage dates

search_series

search_series(search_text: str, api_key: ApiKeyType = None, search_type: Literal['full_text', 'series_id'] = 'full_text', return_format: ReturnFormats = 'pandas', **kwargs: KwargsType) -> ReturnTypes

Get economic data series that match search text. Endpoint documentation.

Parameters:

Name	Type	Description	Default
search_text	str	The text to match against.	required
api_key	(str | None, optional)	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
search_type	Literal['full_text', 'series_id']	Defines which type of search to preform. One of the following strings: 'full_text', 'series_id'. Parameter docs.	'full_text'
return_format	: Literal["json", "pandas", "polars"] | ReturnFormat	In what format to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.	'pandas'
**kwargs	dict	Additional parameters to FRED API series/observation endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict | DataFrame | DataFrame

search_series_related_tags

search_series_related_tags(search_text: str, tag_names: str, api_key: ApiKeyType = None, return_format: ReturnFormats = 'pandas', **kwargs) -> ReturnTypes

Get the related FRED tags for one or more FRED tags matching a series search. Endpoint documentation.

Parameters:

Name	Type	Description	Default
search_text	str	The text to match against.	required
tag_names	str	A semicolon delimited list of tag names that series match all of.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
return_format	: Literal["json", "pandas", "polars"] | ReturnFormat	In what format to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.	'pandas'
**kwargs	dict	Additional parameters to FRED API series/observation endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict | DataFrame | DataFrame

search_series_tags

search_series_tags(search_text: str, api_key: ApiKeyType = None, return_format: ReturnFormats = 'pandas', **kwargs: KwargsType) -> ReturnTypes

Get the FRED tags for a series search. Endpoint documentation.

Parameters:

Name	Type	Description	Default
search_text	str	The text to match against.	required
api_key	(str | None, optional)	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
return_format	: Literal["json", "pandas", "polars"] | ReturnFormat	In what format to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.	'pandas'
**kwargs	dict	Additional parameters to FRED API series/observation endpoint. Refer to the FRED documentation for a list of all possible parameters.	{}

Returns:

Type	Description
dict | DataFrame | DataFrame