finagg.fred.api package

Module contents

An implementation of the Federal Reserve Economic Data (FRED) API.

The FRED API provides methods for retrieving, searching, and describing economic data from a variety of sources. The FRED API is one of the most popular APIs in the financial industry.

A FRED API key is required to use this API. You can request a FRED API key at the FRED API webpage. You can pass your FRED API key directly to the implemented API getters, or you can set the FRED_API_KEY environment variable to have the FRED API key be passed to the implemented API getters for you.

Alternatively, running finagg fred install (or the broader finagg install) will prompt you where to acquire a FRED KEY and will automatically store it in an .env file in your current working directory. The environment variables set in that .env file will be loaded into your shell upon using finagg (whether that be through the Python interface or through the CLI tools).

See the official FRED API docs for more info on the FRED API.

finagg.fred.api.category

The most popular way for accessing the finagg.fred.api.Category.

finagg.fred.api.related_tags

The most popular way for accessing finagg.fred.api.RelatedTags.

finagg.fred.api.release

The most popular way for accessing finagg.fred.api.Release.

finagg.fred.api.releases

The most popular way for accessing finagg.fred.api.Releases.

finagg.fred.api.series

The most popular way for accessing finagg.fred.api.Series.

finagg.fred.api.source

The most popular way for accessing finagg.fred.api.Source.

finagg.fred.api.sources

The most popular way for accessing finagg.fred.api.Sources.

finagg.fred.api.tags

The most popular way for accessing finagg.fred.api.Tags.

class finagg.fred.api.API[source]

Bases: ABC

Abstract FRED API.

url: ClassVar[str]

Request API URL.

abstract classmethod get(*args: Any, **kwargs: Any) → DataFrame[source]

Main dataset API method.

class finagg.fred.api.Category[source]

Bases: API

Collection of “fred/category” APIs.

The class variable finagg.fred.api.category is an instance of this API implementation and is the most popular interface for calling this API.

children

“category/children” FRED API. Get the children of a category. The most popular way for accessing the finagg.fred.api.CategoryChildren API.

related

“category/related” FRED API. Get categories related to a category. The most popular way for accessing the finagg.fred.api.CategoryRelated API.

related_tags

“category/related_tags” FRED API. Get tags related to a category. The most popular way for accessing the finagg.fred.api.CategoryRelatedTags API.

series

“category/series” FRED API. Get a category’s series. The most popular way for accessing the finagg.fred.api.CategorySeries API.

tags

“category/tags” FRED API. Get a category’s tags. The most popular way for accessing the finagg.fred.api.CategoryTags API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/category'

Request API URL.

classmethod get(category_id: int = 0, *, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get a category’s details.

Parameters:

  • category_id – The category’s ID. Use the “category/children” API to explore categories.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

Dataframe of category details.

Examples

>>> finagg.fred.api.category.get()  
   id        name  parent_id
0   0  Categories          0
class finagg.fred.api.CategoryChildren[source]

Bases: API

Get FRED child categories.

The class variable finagg.fred.api.Category.children is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/category/children'

Request API URL.

classmethod get(category_id: int = 0, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get all child categories for a specific parent category.

See the related FRED API documentation at:

Parameters:

  • category_id – The category’s ID. Use the “category/children” API to explore categories.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for a category’s children.

Examples

>>> finagg.fred.api.category.children.get()  
      id                                     name  parent_id
0  32991                Money, Banking, & Finance          0
1     10  Population, Employment, & Labor Markets          0
2  32992                        National Accounts          0
3      1           Production & Business Activity          0
4  32455                                   Prices          0
5  32263                       International Data          0
6   3008                       U.S. Regional Data          0
7  33060                            Academic Data          0
class finagg.fred.api.CategoryRelated[source]

Bases: API

Get FRED related categories.

The class variable finagg.fred.api.Category.related is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/category/related'

Request API URL.

classmethod get(category_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get categories related to a category.

See the related FRED API documentation at:

Parameters:

  • category_id – The category’s ID. Use the “category/children” API to explore categories.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for categories related to the given category.

class finagg.fred.api.CategoryRelatedTags[source]

Bases: API

Get FRED category’s related tags.

The class variable finagg.fred.api.Category.related_tags is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/category/related_tags'

Request API URL.

classmethod get(category_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, tag_names: None | str | list[str] = None, exclude_tag_names: None | str | list[str] = None, tag_group_id: None | str = None, search_text: None | str | list[str] = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get data for tags related to a category.

See the related FRED API documentation at:

Parameters:

  • category_id – The category’s ID. Use the “category/children” API to explore categories.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • tag_names – Find tags related to these tags.

  • exclude_tag_names – Exclude tags related to these tags.

  • tag_group_id –

    A tag group ID to filter tags by. Options include:

    • ”freq” = frequency

    • ”gen” = general or concept

    • ”geo” = geography

    • ”geot” = geography type

    • ”rls” = release

    • ”seas” = seasonal adjustment

    • ”src” = source

  • search_text – The words to find matching tags with.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for tags related to a category according to the given parameters.

Examples

>>> finagg.fred.api.category.related_tags.get(33951, tag_names="funds")  
                                 name group_id                     notes ...
0                        anbil, sriya      src                           ...
1                       carlson, mark      src                           ...
2                               daily     freq                           ...
3                             federal      gen                           ...
4                  hanes, christopher      src                           ...
5                            interest      gen                           ...
6                       interest rate      gen                           ...
7                              nation     geot                           ...
8                                 nsa     seas   Not Seasonally Adjusted ...
9   public domain: citation requested       cc                      None ...
10                               rate      gen                           ...
11                                usa      geo  United States of America ...
12                  wheelock, david c      src                           ...
13                                wsj      rls       Wall Street Journal ...
class finagg.fred.api.CategorySeries[source]

Bases: API

Get FRED series within a category.

The class variable finagg.fred.api.Category.series is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/category/series'

Request API URL.

classmethod get(category_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, filter_variable: None | str = None, filter_value: None | str = None, tag_names: None | str | list[str] = None, exclude_tag_names: None | str | list[str] = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get series within a category.

See the related FRED API documentation at:

Parameters:

  • category_id – The category’s ID. Use the “category/children” API to explore categories.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • filter_variable –

    The attribute (or column) to filter results by. Options include:

    • ”frequency”

    • ”units”

    • ”seasonal_adjustment”

  • filter_value – The value of filter_variable to filter results by.

  • tag_names – Find tags related to these tags.

  • exclude_tag_names – Exclude tags related to these tags.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for a category’s series according to the given parameters.

Examples

>>> finagg.fred.api.category.series.get(33951)  
          id realtime_start realtime_end                                              title ...
0   FFHTHIGH     2023-03-15   2023-03-15  High Value of the Federal Funds Rate for the I... ...
1    FFHTLOW     2023-03-15   2023-03-15  Low Value of the Federal Funds Rate for the In... ...
2  FFWSJHIGH     2023-03-15   2023-03-15  High Value of the Federal Funds Rate for the I... ...
3   FFWSJLOW     2023-03-15   2023-03-15  Low Value of the Federal Funds Rate for the In... ...
class finagg.fred.api.CategoryTags[source]

Bases: API

Get FRED category’s tags.

The class variable finagg.fred.api.Category.tags is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/category/tags'

Request API URL.

classmethod get(category_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, tag_names: None | str | list[str] = None, tag_group_id: None | str = None, search_text: None | str | list[str] = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get a FRED category’s tags.

See the related FRED API documentation at:

Parameters:

  • category_id – The category’s ID. Use the “category/children” API to explore categories.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • tag_names – Filtering of tag names to include in the results.

  • tag_group_id –

    A tag group ID to filter tags by. Options include:

    • ”freq” = frequency

    • ”gen” = general or concept

    • ”geo” = geography

    • ”geot” = geography type

    • ”rls” = release

    • ”seas” = seasonal adjustment

    • ”src” = source

  • search_text – The words to find matching tags with.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for a category’s tags according to the given parameters.

Examples

>>> finagg.fred.api.category.tags.get(33951, limit=5)  
            name group_id notes                 created  popularity  series_count
0   anbil, sriya      src        2020-07-03 11:52:33-05          16             8
1  carlson, mark      src        2020-07-03 11:53:20-05          16             8
2          daily     freq        2012-02-27 10:18:19-06          71             8
3        federal      gen        2012-02-27 10:18:19-06          60             8
4          funds      gen  None  2020-05-11 13:13:02-05          28             8
class finagg.fred.api.RelatedTags[source]

Bases: API

Get FRED tags related to other FRED tags.

The module variable related_tags is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/related_tags'

Request API URL.

classmethod get(*, realtime_start: None | int | str = None, realtime_end: None | int | str = None, tag_names: None | str | list[str] = None, exclude_tag_names: None | str | list[str] = None, tag_group_id: None | str = None, search_text: None | str | list[str] = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get data for tags related to an economic release.

See the related FRED API documentation at:

Parameters:

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • tag_names – Find tags related to these tags.

  • exclude_tag_names – Exclude tags related to these tags.

  • tag_group_id –

    A tag group ID to filter tags by. Options include:

    • ”freq” = frequency

    • ”gen” = general or concept

    • ”geo” = geography

    • ”geot” = geography type

    • ”rls” = release

    • ”seas” = seasonal adjustment

    • ”src” = source

  • search_text – The words to find matching tags with.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for related FRED tags.

Examples

>>> finagg.fred.api.related_tags.get(tag_names="bea", limit=5)  
                                name group_id                     notes                 created  popularity  series_count
0  public domain: citation requested       cc                      None  2018-12-17 23:33:13-06          99         78680
1                                usa      geo  United States of America  2012-02-27 10:18:19-06         100         78434
2                                nsa     seas   Not Seasonally Adjusted  2012-02-27 10:18:19-06          99         67720
3                             annual     freq                            2012-02-27 10:18:19-06          88         66478
4                                gdp      gen    Gross Domestic Product  2012-02-27 10:18:19-06          81         60040
class finagg.fred.api.Release[source]

Bases: API

Get data on an economic release.

The class variable finagg.fred.api.release is an instance of this API implementation and is the most popular interface for calling this API.

dates

“release/dates” FRED API. Get economic release dates. The most popular way for accessing the finagg.fred.api.ReleaseDates API.

related_tags

“release/related_tags” FRED API. Get tags related to an economic release. The most popular way for accessing the finagg.fred.api.ReleaseRelatedTags API.

series

“release/series” FRED API. Get the series of an economic release. The most popular way for accessing the finagg.fred.api.ReleaseSeries API.

sources

“release/sources” FRED API. Get the sources for an economic release. The most popular way for accessing the finagg.fred.api.ReleaseSources API.

tables

“release/tables” FRED API. Get the tables of an economic release. The most popular way for accessing the finagg.fred.api.ReleaseTables API.

tags

“release/tags” FRED API. Get tags of an economic release. The most popular way for accessing the finagg.fred.api.ReleaseTags API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/release'

Request API URL.

classmethod get(release_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get overview data of an economic release.

See the related FRED API documentation at:

Parameters:

  • release_id – The ID for a release.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing high-level info on an economic release.

class finagg.fred.api.ReleaseDates[source]

Bases: API

Get dates associated with an economic release.

The class variable finagg.fred.api.Release.dates is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/release/dates'

Request API URL.

classmethod get(release_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 10000, offset: None | int = 0, sort_order: None | str = None, include_release_dates_with_no_data: None | bool = False, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get data on release dates for a particular release of economic data.

See the related FRED API documentation at:

Parameters:

  • release_id – The ID for a release.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • include_release_dates_with_no_data – Whether to return release dates that don’t contain any data.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for an economic data release’s release dates.

class finagg.fred.api.ReleaseRelatedTags[source]

Bases: API

Get tags related to an economic release.

The class variable finagg.fred.api.Release.related_tags is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/release/related_tags'

Request API URL.

classmethod get(release_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, tag_names: None | str | list[str] = None, exclude_tag_names: None | str | list[str] = None, tag_group_id: None | str = None, search_text: None | str | list[str] = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get data for tags related to an economic release.

See the related FRED API documentation at:

Parameters:

  • release_id – The ID for a release.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • tag_names – Find tags related to these tags.

  • exclude_tag_names – Exclude tags related to these tags.

  • tag_group_id –

    A tag group ID to filter tags by. Options include:

    • ”freq” = frequency

    • ”gen” = general or concept

    • ”geo” = geography

    • ”geot” = geography type

    • ”rls” = release

    • ”seas” = seasonal adjustment

    • ”src” = source

  • search_text – The words to find matching tags with.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for tags related to an economic release according to the given parameters.

class finagg.fred.api.Releases[source]

Bases: API

Get all releases of economic data.

dates

“releases/dates” FRED API. Get dates for releases of economic data. The most popular way for accessing the finagg.fred.api.ReleasesDates API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/releases'

Request API URL.

classmethod get(*, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get all releases of economic data.

See the related FRED API documentation at:

Parameters:

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”release_id”

    • ”name”

    • ”press_release”

    • ”realtime_start”

    • ”realtime_end”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data on all releases of economic data.

class finagg.fred.api.ReleasesDates[source]

Bases: API

Get all release dates of FRED economic data.

The class variable finagg.fred.api.Releases.dates is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/releases/dates'

Request API URL.

classmethod get(*, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = 'release_date', sort_order: None | str = 'desc', include_release_dates_with_no_data: None | bool = False, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get all release dates of economic data.

See the related FRED API documentation at:

Parameters:

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”release_date”

    • ”release_id”

    • ”release_name”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • include_release_dates_with_no_data – Whether to return release dates that don’t contain any data.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data on release dates for all releases of economic data.

class finagg.fred.api.ReleaseSeries[source]

Bases: API

Get series associated with an economic release.

The class variable finagg.fred.api.Release.series is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/release/series'

Request API URL.

classmethod get(release_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, filter_variable: None | str = None, filter_value: None | str = None, tag_names: None | str | list[str] = None, exclude_tag_names: None | str | list[str] = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get data on the series related to a release of economic data.

See the related FRED API documentation at:

Parameters:

  • release_id – The ID for a release.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”series_id”

    • ”title”

    • ”units”

    • ”frequency”

    • ”seasonal_adjustment”

    • ”realtime_start”

    • ”realtime_end”

    • ”last_updated”

    • ”observation_start”

    • ”observation_end”

    • ”popularity”

    • ”group_popularity”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • filter_variable –

    The attribute (or column) to filter results by. Options include:

    • ”frequency”

    • ”units”

    • ”seasonal_adjustment”

  • filter_value – The value of filter_variable to filter results by.

  • tag_names – Find tags related to these tags.

  • exclude_tag_names – Exclude tags related to these tags.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing series data for a release.

class finagg.fred.api.ReleaseSources[source]

Bases: API

Get sources associated with an economic release.

The class variable finagg.fred.api.Release.sources is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/release/sources'

Request API URL.

classmethod get(release_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get sources related to an economic release.

See the related FRED API documentation at:

Parameters:

  • release_id – The ID for a release.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing sources related to an economic release.

class finagg.fred.api.ReleaseTables[source]

Bases: API

Get tables associated with an economic release.

The class variable finagg.fred.api.Release.tables is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/release/tables'

Request API URL.

classmethod get(release_id: int, /, *, element_id: None | int = 0, include_observation_values: None | bool = False, observation_date: None | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get release tables for a given economic release.

See the related FRED API documentation at:

Parameters:

  • release_id – The ID for a release.

  • element_id – The release table element you’d like to retrieve.

  • include_observation_values – A flag indicating whether observations need to be returned.

  • observation_date – The observation date to be included with the returned release table.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe of release tables for a given economic release.

class finagg.fred.api.ReleaseTags[source]

Bases: API

Get tags for an economic release.

The class variable finagg.fred.api.Release.tags is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/release/tags'

Request API URL.

classmethod get(release_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, tag_names: None | str | list[str] = None, tag_group_id: None | str = None, search_text: None | str | list[str] = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get tags for an economic release.

See the related FRED API documentation at:

Parameters:

  • release_id – The ID for a release.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • tag_names – Filtering of tag names to include in the results.

  • tag_group_id –

    A tag group ID to filter tags by. Options include:

    • ”freq” = frequency

    • ”gen” = general or concept

    • ”geo” = geography

    • ”geot” = geography type

    • ”rls” = release

    • ”seas” = seasonal adjustment

    • ”src” = source

  • search_text – The words to find matching tags with.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for an economic release’s tags according to the given parameters.

class finagg.fred.api.Series[source]

Bases: API

Get an economic data series.

The class variable finagg.fred.api.series is an instance of this API implementation and is the most popular interface for calling this API.

categories

“series/categories” FRED API. Get the categories for an economic data series. The most popular way for accessing the finagg.fred.api.SeriesCategories API.

observations

“series/observations” FRED API. Get the observations or data values for an economic data series. The most popular way for accessing the finagg.fred.api.SeriesObservations API.

release

“series/release” FRED API. Get the release for an economic data series. The most popular way for accessing the finagg.fred.api.SeriesRelease API.

search

“series/search” FRED API. Get economic data series that match search text. The most popular way for accessing the finagg.fred.api.SeriesSearch API.

tags

“series/tags” FRED API. Get FRED tags for a series. The most popular way for accessing the finagg.fred.api.SeriesTags API.

updates

“series/updates” FRED API. Get economic data series sorted by when observations were updated on the FRED server. The most popular way for accessing the finagg.fred.api.SeriesUpdates API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series'

Request API URL.

vintage_dates

“series/vintage_dates” FRED API. Get the dates in history when a a series’ data values were revised or new data values were released. The most popular way for accessing the finagg.fred.api.SeriesVintageDates API.

classmethod get(series_id: str, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get an economic data series.

See the related FRED API documentation at:

Parameters:

  • series_id – The ID for a series.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing info on an economic data series.

Examples

>>> finagg.fred.api.series.get("CPIAUCNS", realtime_start=0, realtime_end=-1).head(5)  
         id realtime_start realtime_end                                              title ...
0  CPIAUCNS     1949-03-24   1953-02-26  Consumer Price Index for Urban Wage Earners an... ...
1  CPIAUCNS     1953-02-27   1962-02-27  Consumer Price Index for Urban Wage Earners an... ...
2  CPIAUCNS     1962-02-28   1971-02-18  Consumer Price Index for Urban Wage Earners an... ...
3  CPIAUCNS     1971-02-19   1978-02-26  Consumer Price Index for Urban Wage Earners an... ...
4  CPIAUCNS     1978-02-27   1988-02-25  Consumer Price Index for All Urban Consumers: ... ...
class finagg.fred.api.SeriesCategories[source]

Bases: API

Get the categories for an economic data series.

The class variable finagg.fred.api.Series.categories is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/categories'

Request API URL.

classmethod get(series_id: str, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get the categories for an economic data series.

See the related FRED API documentation at:

Parameters:

  • series_id – The ID for a series.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data on categories for the economic data series.

Examples

>>> finagg.fred.api.series.categories.get("CPIAUCNS")  
   id                                  name  parent_id
0   9  Consumer Price Indexes (CPI and PCE)      32455
class finagg.fred.api.SeriesObservations[source]

Bases: API

Get the observations or data values for an economic data series.

This is by far the most popular FRED API method. The class variable finagg.fred.api.Series.observations is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/observations'

Request API URL.

classmethod get(series_id: str, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 100000, offset: None | int = 0, sort_order: None | str = None, observation_start: None | int | str = None, observation_end: None | int | str = None, units: None | str = 'lin', frequency: None | str = None, aggregation_method: None | str = 'avg', output_type: None | int = 1, vintage_dates: None | str | list[str] = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get the observations or data values for an economic data series.

See the related FRED API documentation at:

Parameters:

  • series_id – The ID for a series.

  • realtime_start – Start date for fetching results according to their publication date. 0 indicates since the beginning of time.

  • realtime_end – End date for fetching results according to their publication date. -1 indicates to present day.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • observation_start – The start date of the observation period.

  • observation_end – The end date of the observation period.

  • units –

    Units to return the series values in. Options include:

    • ”lin” = levels (no unit transformation)

    • ”chg” = change

    • ”ch1” = change from a year ago

    • ”pch” = percent change

    • ”pc1” = percent change from a year ago

    • ”pca” = compounded annual rate of change

    • ”cch” = continuously compounded rate of change

    • ”cca” = continuously compounded annual rate of change

    • ”log” = natural log

  • frequency –

    An optional parameter that indicates a lower frequency to aggregate values to. Frequency options without period descriptions include:

    • ”d” = daily

    • ”w” = weekly

    • ”bw” = biweekly

    • ”m” = monthly

    • ”q” = quarterly

    • ”sa” = semiannual

    • ”a” = annual

    Frequency options with period descriptions include:

    • ”wef” = weekly, ending Friday

    • ”weth” = weekly, ending Thursday

    • ”wetu” = weekly, ending Wednesday

    • ”wem” = weekly, ending Monday

    • ”wesu” = weekly, ending Sunday

    • ”wesa” = weekly, ending Saturday

    • ”bwew” = weekly, ending Wednesday

    • ”bwem” = weekly, Monday

  • aggregation_method –

    A key that indicates the aggregation method used for frequency aggregation. Options include:

    • ”avg” = average

    • ”sum” = sum

    • ”eop” = end of period

  • output_type –

    An integer indicating the type of observations to include. Options include:

    • 1 = observations by realtime period

    • 2 = all observations by vintage dates

    • 3 = new and revised observations only

    • 4 = initial release observations only

  • vintage_dates – Vintage dates used to download data as it existed on these specified dates in history. Vintage dates can be specified instead of realtime periods.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing economic data series observations/values according to the given parameters.

Examples

>>> finagg.fred.api.series.observations.get(
...     "CPIAUCNS",
...     realtime_start=0,
...     realtime_end=-1,
...     output_type=4
... ).head(5)  
  realtime_start realtime_end        date  value series_id
0     1949-04-22   1953-02-26  1949-03-01  169.5  CPIAUCNS
1     1949-05-23   1953-02-26  1949-04-01  169.7  CPIAUCNS
2     1949-06-24   1953-02-26  1949-05-01  169.2  CPIAUCNS
3     1949-07-22   1953-02-26  1949-06-01  169.6  CPIAUCNS
4     1949-08-26   1953-02-26  1949-07-01  168.5  CPIAUCNS
classmethod get_original_observations(series_id: str, /, *, limit: None | int = 100000, offset: None | int = 0, sort_order: None | str = None, observation_start: None | int | str = None, observation_end: None | int | str = None, units: None | str = 'lin', frequency: None | str = None, aggregation_method: None | str = 'avg', paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get only the initial releases/observations for an economic data series.

Similar to SeriesObservations.get(), but tries to get initial releases/observations only.

Parameters:

  • series_id – The ID for a series.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • observation_start – The start date of the observation period.

  • observation_end – The end date of the observation period.

  • units –

    Units to return the series values in. Options include:

    • ”lin” = levels (no unit transformation)

    • ”chg” = change

    • ”ch1” = change from a year ago

    • ”pch” = percent change

    • ”pc1” = percent change from a year ago

    • ”pca” = compounded annual rate of change

    • ”cch” = continuously compounded rate of change

    • ”cca” = continuously compounded annual rate of change

    • ”log” = natural log

  • frequency –

    An optional parameter that indicates a lower frequency to aggregate values to. Frequency options without period descriptions include:

    • ”d” = daily

    • ”w” = weekly

    • ”bw” = biweekly

    • ”m” = monthly

    • ”q” = quarterly

    • ”sa” = semiannual

    • ”a” = annual

    Frequency options with period descriptions include:

    • ”wef” = weekly, ending Friday

    • ”weth” = weekly, ending Thursday

    • ”wetu” = weekly, ending Wednesday

    • ”wem” = weekly, ending Monday

    • ”wesu” = weekly, ending Sunday

    • ”wesa” = weekly, ending Saturday

    • ”bwew” = weekly, ending Wednesday

    • ”bwem” = weekly, Monday

  • aggregation_method –

    A key that indicates the aggregation method used for frequency aggregation. Options include:

    • ”avg” = average

    • ”sum” = sum

    • ”eop” = end of period

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing economic data series observations/values according to the given parameters.

Examples

>>> finagg.fred.api.series.observations.get_original_observations(
...     "CPIAUCNS",
... ).head(5)  
  realtime_start realtime_end        date  value series_id
0     1949-04-22   1953-02-26  1949-03-01  169.5  CPIAUCNS
1     1949-05-23   1953-02-26  1949-04-01  169.7  CPIAUCNS
2     1949-06-24   1953-02-26  1949-05-01  169.2  CPIAUCNS
3     1949-07-22   1953-02-26  1949-06-01  169.6  CPIAUCNS
4     1949-08-26   1953-02-26  1949-07-01  168.5  CPIAUCNS
class finagg.fred.api.SeriesRelease[source]

Bases: API

Get the latest release for an economic data seris.

The class variable finagg.fred.api.Series.release is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/release'

Request API URL.

classmethod get(series_id: str, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get the release for an economic data series.

See the related FRED API documentation at:

Parameters:

  • series_id – The ID for a series.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data on a release for an economic data series.

class finagg.fred.api.SeriesSearch[source]

Bases: API

Get economic data series that match search text.

The class variable finagg.fred.api.Series.search is an instance of this API implementation and is the most popular interface for calling this API.

related_tags

“series/search/related_tags” FRED API. Get the related tags for a series search. The most popular way for accessing the finagg.fred.api.SeriesSearchRelatedTags API.

tags

“series/search/tags” FRED API. Get the tags for a series search. The most popular way for accessing the finagg.fred.api.SeriesSearchTags API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/search'

Request API URL.

classmethod get(search_text: str | list[str], /, *, search_type: None | str = 'full_text', realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, filter_variable: None | str = None, filter_value: None | str = None, tag_names: None | str | list[str] = None, exclude_tag_names: None | str | list[str] = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get economic data series that match search text.

See the related FRED API documentation at:

Parameters:

  • search_text – The words to match against economic data series.

  • search_type –

    Determines the type of search to perform. Options include:

    • ”full_text” = search series attributes, units, frequency, and tags by parsing words into stems.

    • ”series_id” = performs a substring search on series IDs.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Order results by values of the specified attribute. Options include:

    • ”search_rank”

    • ”series_id”

    • ”title”

    • ”units”

    • ”frequency”

    • ”seasonal_adjustment”

    • ”realtime_start”

    • ”realtime_end”

    • ”last_updated”

    • ”observation_start”

    • ”observation_end”

    • ”popularity”

    • ”group_popularity”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order for the attribute values specified by order_by.

  • filter_variable –

    The attribute to filter results by. Options include:

    • ”frequency”

    • ”units”

    • ”seasonal_adjustment”

  • filter_value – The value of the filter_variable attribute to filter results by.

  • tag_names – List of tag names that series match all of.

  • exclude_tag_names – List of tag names that series match none of.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data on series matching the search.

Examples

>>> finagg.fred.api.series.search.get("price index", limit=5)  
            id realtime_start realtime_end                                              title ...
0     CPIAUCSL     2023-03-16   2023-03-16  Consumer Price Index for All Urban Consumers: ... ...
1     CPIAUCNS     2023-03-16   2023-03-16  Consumer Price Index for All Urban Consumers: ... ...
2  CUUS0000SA0     2023-03-16   2023-03-16  Consumer Price Index for All Urban Consumers: ... ...
3   CSUSHPINSA     2023-03-16   2023-03-16    S&P/Case-Shiller U.S. National Home Price Index ...
4    CSUSHPISA     2023-03-16   2023-03-16    S&P/Case-Shiller U.S. National Home Price Index ...
class finagg.fred.api.SeriesSearchRelatedTags[source]

Bases: API

Search for series tags related to a series’s tags.

The class variable finagg.fred.api.SeriesSearch.related_tags is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/search/related_tags'

Request API URL.

classmethod get(series_search_text: None | str | list[str], /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, tag_names: None | str | list[str] = None, exclude_tag_names: None | str | list[str] = None, tag_group_id: None | str = None, tag_search_text: None | str | list[str] = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get the related tags for a series search.

See the related FRED API documentation at:

Parameters:

  • series_search_text – The words to match against economic data series.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • tag_names – Tag names to only include in the response.

  • exclude_tag_names – Tag names that series match none of.

  • tag_group_id –

    A tag group ID to filter tags by type. Options include:

    • ”freq” = frequency

    • ”gen” = general or concept

    • ”geo” = geography

    • ”geot” = geography type

    • ”rls” = release

    • ”seas” = seasonal adjustment

    • ”src” = source

  • tag_search_text – The words to find matching tags with.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Order results by values of the specified attribute. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order for the attribute values specified by order_by.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing related FRED tags for a series search. The dataframe can have results optionally filtered by the FRED servers according to the method’s args.

Examples

>>> finagg.fred.api.series.search.related_tags.get("price index", tag_names="price", limit=5)  
                                name group_id                    notes                 created ...
0                                nsa     seas  Not Seasonally Adjusted  2012-02-27 10:18:19-06 ...
1                            indexes      gen                           2012-02-27 10:18:19-06 ...
2                        price index      gen                           2012-02-27 10:18:19-06 ...
3                            monthly     freq                           2012-02-27 10:18:19-06 ...
4  public domain: citation requested       cc                     None  2018-12-17 23:33:13-06 ...
class finagg.fred.api.SeriesSearchTags[source]

Bases: API

Get FRED series tags.

The class variable finagg.fred.api.SeriesSearch.tags is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/search/tags'

Request API URL.

classmethod get(series_search_text: None | str | list[str], /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, tag_names: None | str | list[str] = None, tag_group_id: None | str = None, tag_search_text: None | str | list[str] = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get the tags for a series search.

See the related FRED API documentation at:

Parameters:

  • series_search_text – The words to match against economic data series.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • tag_names – Tag names to only include in the response.

  • tag_group_id –

    A tag group ID to filter tags by type. Options include:

    • ”freq” = frequency

    • ”gen” = general or concept

    • ”geo” = geography

    • ”geot” = geography type

    • ”rls” = release

    • ”seas” = seasonal adjustment

    • ”src” = source

  • tag_search_text – The words to find matching tags with.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Order results by values of the specified attribute. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order for the attribute values specified by order_by.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing FRED tags for a series search. The dataframe can have results optionally filtered by the FRED servers according to the method’s args.

Examples

>>> finagg.fred.api.series.search.tags.get("price index", limit=5)  
                                name group_id                    notes ...
0                                nsa     seas  Not Seasonally Adjusted ...
1                              price      gen                          ...
2                            indexes      gen                          ...
3                        price index      gen                          ...
4  public domain: citation requested       cc                     None ...
class finagg.fred.api.SeriesTags[source]

Bases: API

Get FRED tags for an economic data series.

The class variable finagg.fred.api.Series.tags is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/tags'

Request API URL.

classmethod get(series_id: str, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, order_by: None | str = None, sort_order: None | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get the FRED tags for a series.

See the related FRED API documentation at:

Parameters:

  • series_id – The ID for a series.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • order_by –

    Order results by values of the specified attribute. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order for the attribute values specified by order_by.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data on FRED tags for series.

Examples

>>> finagg.fred.api.series.tags.get("CPIAUCNS").head(5)  
                                name group_id                     notes ...
0                                nsa     seas   Not Seasonally Adjusted ...
1                                usa      geo  United States of America ...
2  public domain: citation requested       cc                      None ...
3                             nation     geot                           ...
4                            monthly     freq                           ...
class finagg.fred.api.SeriesUpdates[source]

Bases: API

Get data on when economic data series where updated on the FRED server.

The class variable finagg.fred.api.Series.updates is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/updates'

Request API URL.

classmethod get(*, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 1000, offset: None | int = 0, filter_value: None | str = None, start_time: None | str = None, end_time: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get economic data series sorted by when observations were updated on the FRED server.

Results are limited to series updated within the last two weeks.

See the related FRED API documentation at:

Parameters:

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • filter_value –

    Limit results by geographic type of economic data series. Options include:

    • ”macro” = limit results to macroeconomic data series

    • ”regional” = limit results to series for parts of the US

    • ”all” = does not filter results

  • start_time – Start time for limiting results for a time range. Can filter down to minutes. Expects format “YYYMMDDHhmm”.

  • end_time – Start time for limiting results for a time range. Can filter down to minutes. Expects format “YYYMMDDHhmm”.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing info on recently updated economic data series.

class finagg.fred.api.SeriesVintageDates[source]

Bases: API

Get FRED series revision dates.

The class variable finagg.fred.api.Series.vintage_dates is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/series/vintage_dates'

Request API URL.

classmethod get(series_id: str, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 10000, offset: None | int = 0, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

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 for the series did not change.

See the related FRED API documentation at:

Parameters:

  • series_id – The ID for a series.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) vintage date order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing dates on vintage release dates for a series.

class finagg.fred.api.Source[source]

Bases: API

Get a source of economic data.

The module variable finagg.fred.api.source is an instance of this API implementation and is the most popular interface for calling this API.

releases

“source/releases” FRED API. Get the releases for a source of economic data. The most popular way for accessing the finagg.fred.api.SourceReleases API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/source'

Request API URL.

classmethod get(source_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get overview data of an economic series.

See the related FRED API documentation at:

Parameters:

  • source_id – The ID for a source.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing high-level info on an economic source.

Examples

>>> finagg.fred.api.source.get(1)  
   id realtime_start realtime_end                                               name                            link
0   1     2023-03-15   2023-03-15  Board of Governors of the Federal Reserve Syst...  http://www.federalreserve.gov/
class finagg.fred.api.SourceReleases[source]

Bases: API

Get all of a source’s releases of economic data.

The class variable finagg.fred.api.Source.releases is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/source/releases'

Request API URL.

classmethod get(source_id: int, /, *, realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get all releases for a source of economic data.

See the related FRED API documentation at:

Parameters:

  • source_id – The ID for a source.

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”release_id”

    • ”name”

    • ”press_release”

    • ”realtime_start”

    • ”realtime_end”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data on all releases for a source of economic data.

Examples

>>> finagg.fred.api.source.releases.get(1, limit=5)  
   id realtime_start realtime_end                                               name  press_release                                         link
0  13     2023-03-15   2023-03-15  G.17 Industrial Production and Capacity Utiliz...           True  http://www.federalreserve.gov/releases/g17/
1  14     2023-03-15   2023-03-15                               G.19 Consumer Credit           True  http://www.federalreserve.gov/releases/g19/
2  15     2023-03-15   2023-03-15                         G.5 Foreign Exchange Rates           True   http://www.federalreserve.gov/releases/g5/
3  17     2023-03-15   2023-03-15                        H.10 Foreign Exchange Rates           True  http://www.federalreserve.gov/releases/h10/
4  18     2023-03-15   2023-03-15                       H.15 Selected Interest Rates           True  http://www.federalreserve.gov/releases/h15/
class finagg.fred.api.Sources[source]

Bases: API

Get all FRED sources of economic data.

The module variable finagg.fred.api.sources is an instance of this API implementation and is the most popular interface for calling this API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/sources'

Request API URL.

classmethod get(realtime_start: None | int | str = None, realtime_end: None | int | str = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get all sources of economic data.

See the related FRED API documentation at:

Parameters:

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”source_id”

    • ”name”

    • ”press_release”

    • ”realtime_start”

    • ”realtime_end”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data on all sources of economic data.

Examples

>>> finagg.fred.api.sources.get(limit=5)  
   id realtime_start realtime_end                                               name                              link
0   1     2023-03-15   2023-03-15  Board of Governors of the Federal Reserve Syst...    http://www.federalreserve.gov/
1   3     2023-03-15   2023-03-15               Federal Reserve Bank of Philadelphia  https://www.philadelphiafed.org/
2   4     2023-03-15   2023-03-15                  Federal Reserve Bank of St. Louis        http://www.stlouisfed.org/
3   6     2023-03-15   2023-03-15  Federal Financial Institutions Examination Cou...             http://www.ffiec.gov/
4  11     2023-03-15   2023-03-15                                Dow Jones & Company           http://www.dowjones.com
class finagg.fred.api.Tags[source]

Bases: API

Get FRED tags.

The module variable tags is an instance of this API implementation and is the most popular interface for calling this API.

series

“tags/series” FRED API. Get the series for a FRED tag. The most popular way for accessing the Series API.

url: ClassVar[str] = 'https://api.stlouisfed.org/fred/tags'

Request API URL.

classmethod get(*, realtime_start: None | int | str = None, realtime_end: None | int | str = None, tag_names: None | str | list[str] = None, tag_group_id: None | str = None, search_text: None | str | list[str] = None, limit: None | int = 1000, offset: None | int = 0, order_by: None | str = None, sort_order: None | str = None, paginate: bool = False, cache: bool = True, api_key: None | str = None) → DataFrame[source]

Get the FRED tags for a series.

See the related FRED API documentation at:

Parameters:

  • realtime_start – Start date for fetching results according to their publication date.

  • realtime_end – End date for fetching results according to their publication date.

  • tag_names – Filtering of tag names to include in the results.

  • tag_group_id –

    A tag group ID to filter tags by. Options include:

    • ”freq” = frequency

    • ”gen” = general or concept

    • ”geo” = geography

    • ”geot” = geography type

    • ”rls” = release

    • ”seas” = seasonal adjustment

    • ”src” = source

    • ”cc” = citation and copyright

  • search_text – The words to find matching tags with.

  • limit – Maximum number of results to return.

  • offset – Result start offset.

  • order_by –

    Variable to order results by. Options include:

    • ”series_count”

    • ”popularity”

    • ”created”

    • ”name”

    • ”group_id”

  • sort_order – Sort results in ascending (“asc”) or descending (“desc”) order.

  • paginate – Whether to manage offset automatically, making multiple API calls until all results are returned.

  • cache – Whether to cache the response from the API.

  • api_key – Your FRED API key. Defaults to the FRED_API_KEY environment variable.

Returns:

A dataframe containing data for all FRED economic data tags.

Examples

>>> finagg.fred.api.tags.get(tag_group_id="src", limit=5)  
          name group_id                        notes                 created  popularity  series_count
0       census      src                       Census  2012-02-27 10:18:19-06          79        237692
1          bls      src   Bureau of Labor Statistics  2012-02-27 10:18:19-06          89        175376
2  realtor.com      src                               2020-03-24 11:15:04-05          66         90632
3          bea      src  Bureau of Economic Analysis  2012-02-27 10:18:19-06          78         78842
4      frb stl      src                St. Louis Fed  2012-02-27 10:18:19-06          68         78442