Clients
- class pystlouisfed.FRED(api_key: str, ratelimiter_enabled: bool = True, ratelimiter_max_calls: int = 120, ratelimiter_period: timedelta | None = None, request_params: dict | None = None)[source]
- The FRED API is a web service that allows developers to write programs and build applications that retrieve economic data from the FRED and ALFRED websites hosted by the Economic Research Division of the Federal Reserve Bank of St. Louis.Requests can be customized according to data source, release, category, series, and other preferences.
https://fred.stlouisfed.org https://fred.stlouisfed.org/docs/api/fred/
- Parameters:
api_key (str) – 32 character alpha-numeric lowercase string
request_params (dict) – HTTP GET method parameters, see https://docs.python-requests.org/en/latest/api/#requests.request
- category(category_id: int = 0) Category[source]
- Parameters:
category_id (int) – The id for a category.
- Return type:
Description
Get a category.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.category(category_id=125) # Category(id=125, name='Trade Balance', parent_id=13)
- category_children(category_id: int = 0, realtime_start: date | None = None, realtime_end: date | None = None) DataFrame[source]
- Parameters:
category_id (int) – The id for a category.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
- Return type:
Description
Get the child categories for a specified parent category.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.category_children(category_id=13).head() # name parent_id # id # 16 Exports 13 # 17 Imports 13 # 3000 Income Payments & Receipts 13 # 33705 International Investment Position 13 # 125 Trade Balance 13
- Parameters:
category_id (int) – The id for a category.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
- Return type:
Description
Get the related categories for a category.A related category is a one-way relation between 2 categories that is not part of a parent-child category hierarchy.Most categories do not have related categories.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.category_related(category_id=32073).head() # name parent_id # id # 149 Arkansas 27281 # 150 Illinois 27281 # 151 Indiana 27281 # 152 Kentucky 27281 # 153 Mississippi 27281
- Parameters:
category_id (int) – The id for a category.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
exclude_tag_names (Optional[list[str]]) – Tuple of tag names that series match none of.
tag_group_id (enums.TagGroupID) – A tag group id to filter tags by type.
search_text (str) – The words to find matching tags with.
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the related FRED tags for one or more FRED tags within a category.Optionally, filter results by tag group or search.FRED tags are attributes assigned to series.For this request, related FRED tags are the tags assigned to series that match all tags in the tag_names parameter, no tags in the exclude_tag_names parameter, and the category set by the category_id parameter.See the related request fred/category/tags.Series are assigned tags and categories. Indirectly through series, it is possible to get the tags for a category.No tags exist for a category that does not have series.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.category_related_tags(category_id=125, tag_names=['services', 'quarterly']).head() # group_id notes created popularity series_count # name # discontinued gen 2012-02-27 16:18:19+00:00 67 4 # nsa seas Not Seasonally Adjusted 2012-02-27 16:18:19+00:00 100 6 # sa seas Seasonally Adjusted 2012-02-27 16:18:19+00:00 88 6 # goods gen 2012-02-27 16:18:19+00:00 68 8 # balance gen 2012-02-27 16:18:19+00:00 47 12
- category_series(category_id: int = 0, realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy = OrderBy.series_id, sort_order: SortOrder = SortOrder.asc, filter_variable: FilterVariable | None = None, filter_value: FilterValue | None = None, tag_names: list[str] | None = None, exclude_tag_names: list[str] | None = None) DataFrame[source]
- Parameters:
category_id (int) – The id for a category.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
filter_variable (enums.FilterVariable) – The attribute to filter results by.
filter_value (enums.FilterValue) – The value of the filter_variable attribute to filter results by.
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
exclude_tag_names (Optional[list[str]]) – Tuple of tag names that series match none of.
- Return type:
Description
Get the series in a category.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.category_series(category_id=125).head() # realtime_start realtime_end title observation_start observation_end frequency frequency_short units units_short seasonal_adjustment seasonal_adjustment_short last_updated popularity group_popularity notes # id # AITGCBN 2022-02-05 2022-02-05 Advance U.S. International Trade in Goods: Bal... 2021-12-01 2021-12-01 Monthly M Millions of Dollars Mil. of $ Not Seasonally Adjusted NSA 2022-01-26 13:31:05+00:00 3 26 This advance estimate represents the current m... # AITGCBS 2022-02-05 2022-02-05 Advance U.S. International Trade in Goods: Bal... 2021-12-01 2021-12-01 Monthly M Millions of Dollars Mil. of $ Seasonally Adjusted SA 2022-01-26 13:31:02+00:00 26 26 This advance estimate represents the current m... # BOPBCA 2022-02-05 2022-02-05 Balance on Current Account (DISCONTINUED) 1960-01-01 2014-01-01 Quarterly Q Billions of Dollars Bil. of $ Seasonally Adjusted SA 2014-06-18 13:41:28+00:00 10 11 This series has been discontinued as a result ... # BOPBCAA 2022-02-05 2022-02-05 Balance on Current Account (DISCONTINUED) 1960-01-01 2013-01-01 Annual A Billions of Dollars Bil. of $ Not Seasonally Adjusted NSA 2014-06-18 13:41:28+00:00 2 11 This series has been discontinued as a result ... # BOPBCAN 2022-02-05 2022-02-05 Balance on Current Account (DISCONTINUED) 1960-01-01 2014-01-01 Quarterly Q Billions of Dollars Bil. of $ Not Seasonally Adjusted NSA 2014-06-18 13:41:28+00:00 1 11 This series has been discontinued as a result ...
- category_tags(category_id: int = 0, realtime_start: date | None = None, realtime_end: date | None = None, tag_names: list[str] | None = None, tag_group_id: TagGroupID | None = None, search_text: str | None = None, order_by: OrderBy = OrderBy.series_count, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
category_id (int) – The id for a category.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
tag_group_id (enums.TagGroupID) – A tag group id to filter tags by type.
search_text (str) – The words to find matching tags with.
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the FRED tags for a category.Optionally, filter results by tag name, tag group, or search. Series are assigned tags and categories.Indirectly through series, it is possible to get the tags for a category. No tags exist for a category that does not have series.See the related request fred/category/related_tags.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.category_tags(category_id=125).head() # group_id notes created popularity series_count # name # headline figure gen 2013-11-19 19:55:53+00:00 53 2 # primary gen 2012-02-27 16:18:19+00:00 42 2 # transfers gen 2012-02-27 16:18:19+00:00 31 2 # census src Census 2012-02-27 16:18:19+00:00 80 4 # investment gen 2012-02-27 16:18:19+00:00 56 4
- Parameters:
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
exclude_tag_names (Optional[list[str]]) – Tuple of tag names that series match none of.
tag_group_id (enums.TagGroupID) – A tag group id to filter tags by type.
search_text (str) – The words to find matching tags with.
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the related FRED tags for one or more FRED tags.Optionally, filter results by tag group or search.FRED tags are attributes assigned to series.Related FRED tags are the tags assigned to series that match all tags in the tag_names parameter and no tags in the exclude_tag_names parameter.See the related request fred/tags.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.related_tags(tag_names=['monetary aggregates', 'weekly']).head() group_id notes created popularity series_count # name # copyrighted: citation required cc <NA> 2018-12-18 05:33:13+00:00 88 2 # currency gen 2012-02-27 16:18:19+00:00 62 2 # frb stl src St. Louis Fed 2012-02-27 16:18:19+00:00 68 2 # m1 gen M1 Money Stock 2012-02-27 16:18:19+00:00 47 2 # m3 gen M3 Money Stock 2012-02-27 16:18:19+00:00 39 2
- release(release_id: int, realtime_start: date | None = None, realtime_end: date | None = None) Release[source]
- Parameters:
release_id (int) – The id for a release.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
- Return type:
Description
Get a release of economic data.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.release(release_id=53) # Release(id=53, realtime_start=datetime.date(2022, 1, 14), realtime_end=datetime.date(2022, 1, 14), name='Gross Domestic Product', press_release=True, link='https://www.bea.gov/data/gdp/gross-domestic-product')
- release_dates(release_id: int, realtime_start: date | None = None, realtime_end: date | None = None, sort_order: SortOrder = SortOrder.asc, include_release_dates_with_no_data: bool = False) DataFrame[source]
- Parameters:
release_id (int) – The id for a release.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
sort_order (enums.SortOrder) – Sort results is ascending or descending release date order. One of the following strings: ‘asc’, ‘desc’.
include_release_dates_with_no_data (bool) – Determines whether release dates with no data available are returned. The defalut value ‘false’ excludes release dates that do not have data. In particular, this excludes future release dates which may be available in the FRED release calendar or the ALFRED release calendar.
- Return type:
Description
Get release dates for a release of economic data.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.release_dates(release_id=82).head() # release_id date # 0 82 1997-02-10 # 1 82 1998-02-10 # 2 82 1999-02-04 # 3 82 2000-02-10 # 4 82 2001-01-16
- Parameters:
release_id (int) – The id for a release.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
exclude_tag_names (Optional[list[str]]) – Tuple of tag names that series match none of.
tag_group_id (enums.TagGroupID) – A tag group id to filter tags by type.
search_text (str) – The words to find matching tags with.
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the related FRED tags for one or more FRED tags within a release. Optionally, filter results by tag group or search.FRED tags are attributes assigned to series.For this request, related FRED tags are the tags assigned to series that match all tags in the tag_names parameter, no tags in the exclude_tag_names parameter, and the release set by the release_id parameter.See the related request fred/release/tags.Series are assigned tags and releases. Indirectly through series, it is possible to get the tags for a release.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.release_related_tags(release_id=86, tag_names=['sa', 'foreign']).head() # group_id notes created popularity series_count # name # financial gen 2012-02-27 16:18:19+00:00 55 2 # monthly freq 2012-02-27 16:18:19+00:00 93 2 # nonfinancial gen 2012-02-27 16:18:19+00:00 55 2 # weekly freq 2012-02-27 16:18:19+00:00 68 2 # commercial gen 2012-02-27 16:18:19+00:00 61 4
- release_series(release_id: int, realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy = OrderBy.series_id, sort_order: SortOrder = SortOrder.asc, filter_variable: FilterVariable | None = None, filter_value: FilterValue | None = None, tag_names: list[str] | None = None, exclude_tag_names: list[str] | None = None) DataFrame[source]
- Parameters:
release_id (int) – The id for a release.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
filter_variable (enums.FilterVariable) – The attribute to filter results by.
filter_value (enums.FilterValue) – The value of the filter_variable attribute to filter results by.
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
exclude_tag_names (Optional[list[str]]) – Tuple of tag names that series match none of.
- Return type:
Description
Get the series on a release of economic data.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.release_series(release_id=51).head() # realtime_start realtime_end title observation_start observation_end frequency frequency_short units units_short seasonal_adjustment seasonal_adjustment_short last_updated popularity group_popularity notes # id # BOMTVLM133S 2022-02-05 2022-02-05 U.S. Imports of Services - Travel 1992-01-01 2017-09-01 Monthly M Million of Dollars Mil. of $ Seasonally Adjusted SA 2017-11-03 13:12:15+00:00 1 1 Further information related to the internation... # BOMVGMM133S 2022-02-05 2022-02-05 U.S. Imports of Services: U.S. Government Misc... 1992-01-01 2013-12-01 Monthly M Millions of Dollars Mil. of $ Seasonally Adjusted SA 2014-10-20 14:27:37+00:00 1 1 BEA has introduced new table presentations, in... # BOMVJMM133S 2022-02-05 2022-02-05 U.S. Imports of Services - Direct Defense Expe... 1992-01-01 2013-12-01 Monthly M Millions of Dollars Mil. of $ Seasonally Adjusted SA 2014-10-20 14:26:44+00:00 1 1 BEA has introduced new table presentations, in... # BOMVMPM133S 2022-02-05 2022-02-05 U.S. Imports of Services - Passenger Fares 1992-01-01 2017-09-01 Monthly M Million of Dollars Mil. of $ Seasonally Adjusted SA 2017-11-03 13:12:15+00:00 1 1 Further information related to the internation... # BOMVOMM133S 2022-02-05 2022-02-05 U.S. Imports of Services - Other Private Servi... 1992-01-01 2013-12-01 Monthly M Million of Dollars Mil. of $ Seasonally Adjusted SA 2014-10-20 14:25:54+00:00 1 1 BEA has introduced new table presentations, in...
- release_sources(release_id: int, realtime_start: date | None = None, realtime_end: date | None = None) DataFrame[source]
- Parameters:
release_id (int) – The id for a release.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
- Return type:
Description
Get the sources for a release of economic data.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.release_sources(release_id=51).head() # realtime_start realtime_end name link # id # 19 2022-02-05 2022-02-05 U.S. Census Bureau http://www.census.gov/ # 18 2022-02-05 2022-02-05 U.S. Bureau of Economic Analysis http://www.bea.gov/
- release_tables(release_id: int, element_id: int | None = None, include_observation_values: bool = False, observation_date: date | None = None) DataFrame[source]
- Parameters:
release_id (int) – The id for a release.
element_id (int) – The release table element id you would like to retrieve. When the parameter is not passed, the root(top most) element for the release is given.
include_observation_values (bool) – A flag to indicate that observations need to be returned. Observation value and date will only be returned for a series type element.
observation_date (datetime.date) – The observation date to be included with the returned release table.
- Return type:
Description
Get release table trees for a given release.You can go directly to the tree structure by passing the appropriate element_id.You may also use a drill-down approach to start at the root (top most) element by leaving the element_id off.Note that release dates are published by data sources and do not necessarily represent when data will be available on the FRED or ALFRED websites.
- release_tags(release_id: int, realtime_start: date | None = None, realtime_end: date | None = None, tag_names: list[str] | None = None, tag_group_id: TagGroupID | None = None, search_text: str | None = None, order_by: OrderBy = OrderBy.series_count, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
release_id (int) – The id for a release.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
tag_group_id (enums.TagGroupID) – A tag group id to filter tags by type.
search_text (str) – The words to find matching tags with.
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the FRED tags for a release.Optionally, filter results by tag name, tag group, or search.Series are assigned tags and releases.Indirectly through series, it is possible to get the tags for a release.See the related request fred/release/related_tags.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.release_tags(release_id=86).head() # group_id notes created popularity series_count # name # 1-month gen 2012-02-27 16:18:19+00:00 39 2 # 2-month gen 2012-05-25 16:29:21+00:00 17 2 # owned gen 2012-06-25 20:04:36+00:00 33 2 # tier-2 gen 2014-02-12 17:18:16+00:00 -13 2 # 10-20 days gen 2014-02-12 17:08:07+00:00 -16 4
- releases(realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy = OrderBy.release_id, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get all releases of economic data.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.releases().head() # realtime_start realtime_end name press_release link notes # id # 9 2022-02-05 2022-02-05 Advance Monthly Sales for Retail and Food Serv... True http://www.census.gov/retail/ The U.S. Census Bureau conducts the Advance Mo... # 10 2022-02-05 2022-02-05 Consumer Price Index True http://www.bls.gov/cpi/ <NA> # 11 2022-02-05 2022-02-05 Employment Cost Index True http://www.bls.gov/ncs/ect/ <NA> # 13 2022-02-05 2022-02-05 G.17 Industrial Production and Capacity Utiliz... True http://www.federalreserve.gov/releases/g17/ <NA> # 14 2022-02-05 2022-02-05 G.19 Consumer Credit True http://www.federalreserve.gov/releases/g19/ <NA>
- releases_dates(realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy = OrderBy.release_id, sort_order: SortOrder = SortOrder.desc, include_release_dates_with_no_data: bool = False) DataFrame[source]
- Parameters:
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
include_release_dates_with_no_data – bool, Determines whether release dates with no data available are returned. The defalut value ‘false’ excludes release dates that do not have data. In particular, this excludes future release dates which may be available in the FRED release calendar or the ALFRED release calendar. If include_release_dates_with_no_data is set to true, the XML tag release_date has an extra attribute release_last_updated that can be compared to the release date to determine if data has been updated.
- Return type:
Description
Get release dates for all releases of economic data.Note that release dates are published by data sources and do not necessarily represent when data will be available on the FRED or ALFRED websites.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.releases_dates(realtime_start=dt_date.today() - timedelta(days=1)).head() # release_name date # release_id # 502 Euro Short Term Rate 2022-02-04 # 492 SONIA Interest Rate Benchmark 2022-02-04 # 484 Key ECB Interest Rates 2022-02-04 # 483 SOFR Averages and Index Data 2022-02-04 # 469 State Unemployment Insurance Weekly Claims Report 2022-02-04
- series(series_id: str, realtime_start: date | None = None, realtime_end: date | None = None) Series[source]
- Parameters:
series_id (str) – The id for a series.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
- Return type:
Description
Get an economic data series.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series(series_id='GNPCA') # Series(id='GNPCA', realtime_start=datetime.date(2022, 1, 14), realtime_end=datetime.date(2022, 1, 14), title='Real Gross National Product', observation_start=datetime.date(1929, 1, 1), observation_end=datetime.date(2020, 1, 1), frequency='Annual', frequency_short='A', units='Billions of Chained 2012 Dollars', units_short='Bil. of Chn. 2012 $', seasonal_adjustment='Not Seasonally Adjusted', seasonal_adjustment_short='NSA', last_updated=datetime.datetime(2021, 7, 29, 7, 45, 58, tzinfo=datetime.timezone(datetime.timedelta(days=-1, seconds=68400))), popularity=12, notes='BEA Account Code: A001RX\n\n')
- series_categories(series_id: str, realtime_start: date | None = None, realtime_end: date | None = None) DataFrame[source]
- Parameters:
series_id (str) – The id for a series.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
- Return type:
Description
Get the categories for an economic data series.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_categories(series_id='EXJPUS') # name parent_id # id # 95 Monthly Rates 15 # 275 Japan 158
- series_observations(series_id: str, realtime_start: date | None = None, realtime_end: date | None = None, sort_order: SortOrder = SortOrder.asc, observation_start: date | None = None, observation_end: date | None = None, units: Unit = Unit.lin, frequency: Frequency | None = None, aggregation_method: AggregationMethod = AggregationMethod.avg, output_type: OutputType = OutputType.realtime_period, vintage_dates: list[str] | None = None) DataFrame[source]
- Parameters:
series_id (str) – The id for a series.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
sort_order (enums.SortOrder) – Sort results is ascending or descending observation_date order.
observation_start (datetime.date) – The start of the observation period.
observation_end (datetime.date) – The end of the observation period.
units (enums.Unit) – A key that indicates a data value transformation.
frequency (enums.Frequency) – An optional parameter that indicates a lower frequency to aggregate values to.
aggregation_method (enums.AggregationMethod) – A key that indicates the aggregation method used for frequency aggregation. This parameter has no affect if the frequency parameter is not set.
output_type (enums.OutputType) – An integer that indicates an output type. See https://alfred.stlouisfed.org/help/downloaddata#outputformats
vintage_dates (Optional[list[str]]) – A comma separated string of YYYY-MM-DD formatted dates in history (e.g. 2000-01-01,2005-02-24). Vintage dates are used to download data as it existed on these specified dates in history. Vintage dates can be specified instead of a real-time period using realtime_start and realtime_end. Sometimes it may be useful to enter a vintage date that is not a date when the data values were revised. For instance you may want to know the latest available revisions on 2001-09-11 (World Trade Center and Pentagon attacks) or as of a Federal Open Market Committee (FOMC) meeting dt_date. Entering a vintage date is also useful to compare series on different releases with different release dates.
- Return type:
Description
Get the observations or data values for an economic data series.Warning
The FRED API seems to have implemented a hard cap of 2000 vintages to be retrieved at once (see strange things or issues/2 and fredapi/pull/52).
Examples
Plot value with default matplotlib:
from matplotlib import pyplot as plt from pystlouisfed import FRED fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") df = fred.series_observations(series_id="T10Y2Y") df.plot(y="value", grid=True) plt.show()
Of course, we can use any library, for example Plotly:
import plotly.express as px from pystlouisfed import FRED fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') df = fred.series_observations(series_id='SP500') fig = px.scatter( x=df.index, y=df.value, trendline="ols", trendline_color_override="red", title=f"S&P 500", labels={"x": "Date", "y": "Index"}, ) fig.show()
Output types
These output formats are a cross tabulation between the series’ observation dates and the specified vintage dates.The first column contains the observation dates for which the data values are measured.The first row contains the vintage dates that specify dates in history and what data actually existed on past dates.The interior cells contain data values for specific combinations of observation dates and vintage dates.For details see https://alfred.stlouisfed.org/help/downloaddata#outputformats .Observations by Real-Time Period (default)
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_observations( series_id="GNPCA", output_type=OutputType.realtime_period, realtime_start=date(2020, 7, 4), realtime_end=date(2023, 7, 20), observation_start=date(1990, 7, 1), observation_end=date(2023, 7, 1) ).head() # # realtime_start realtime_end value # date # 1929-01-01 2023-07-27 2023-07-27 1120.718 # 1930-01-01 2023-07-27 2023-07-27 1025.678 # 1931-01-01 2023-07-27 2023-07-27 958.927 # 1932-01-01 2023-07-27 2023-07-27 834.769 # 1933-01-01 2023-07-27 2023-07-27 823.628
All Observations
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_observations( series_id="GNPCA", output_type=OutputType.all, realtime_start=date(2020, 7, 4), realtime_end=date(2023, 7, 20), observation_start=date(1990, 7, 1), observation_end=date(2023, 7, 1) ).head() # GNPCA_20200704 GNPCA_20200730 GNPCA_20210325 GNPCA_20210729 GNPCA_20220330 GNPCA_20220929 GNPCA_20230330 GNPCA_20230720 # date # 1991-01-01 9406.669 9406.669 9406.669 9411.632 9411.632 9411.632 9411.632 9411.632 # 1992-01-01 9734.705 9734.705 9734.705 9739.841 9739.841 9739.841 9739.841 9739.841 # 1993-01-01 10000.831 10000.831 10000.831 10006.004 10006.004 10006.004 10006.004 10006.004 # 1994-01-01 10389.663 10389.663 10389.663 10395.034 10395.034 10395.034 10395.034 10395.034 # 1995-01-01 10672.832 10672.832 10672.832 10678.341 10678.341 10678.341 10678.341 10678.341
New and Revised Observations Only
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_observations( series_id='GNPCA', output_type=OutputType.new_and_revised, realtime_start=date(2020, 7, 4), realtime_end=date(2023, 7, 20), observation_start=date(1990, 7, 1), observation_end=date(2023, 7, 1) ).head() # GNPCA_20210729 GNPCA_20200730 GNPCA_20220929 GNPCA_20210325 GNPCA_20220330 GNPCA_20230330 # date # 1991-01-01 9411.632 NaN NaN NaN NaN NaN # 1992-01-01 9739.841 NaN NaN NaN NaN NaN # 1993-01-01 10006.004 NaN NaN NaN NaN NaN # 1994-01-01 10395.034 NaN NaN NaN NaN NaN # 1995-01-01 10678.341 NaN NaN NaN NaN NaN
Initial Release Only
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_observations( series_id='GNPCA', output_type=OutputType.initial_release_only, realtime_start=date(2020, 7, 4), realtime_end=date(2023, 7, 20), observation_start=date(1990, 7, 1), observation_end=date(2023, 7, 1) ).head() # realtime_start realtime_end value # date # 2020-01-01 2021-03-25 2021-07-28 18612.022 # 2021-01-01 2022-03-30 2022-09-28 19644.028 # 2022-01-01 2023-03-30 2023-07-20 20158.225
- series_release(series_id: str, realtime_start: date | None = None, realtime_end: date | None = None) DataFrame[source]
- Parameters:
series_id (str) – The id for a series.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end – datetime.date, he end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
- Return type:
Description
Get the release for an economic data series.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_release(series_id='IRA').head() # realtime_start realtime_end name press_release link # id # 21 2022-02-05 2022-02-05 H.6 Money Stock Measures True http://www.federalreserve.gov/releases/h6/
- series_search(search_text: str, search_type: SearchType = SearchType.full_text, realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy | None = None, sort_order: SortOrder | None = None, filter_variable: FilterVariable | None = None, filter_value: FilterValue | None = None, tag_names: list[str] | None = None, exclude_tag_names: list[str] | None = None) DataFrame[source]
- Parameters:
search_text (str) – The words to match against economic data series.
search_type (enums.SearchType) – Determines the type of search to perform.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
filter_variable (enums.FilterVariable) – The attribute to filter results by.
filter_value (enums.FilterValue) – The value of the filter_variable attribute to filter results by.
tag_names (Optional[list[str]]) – A semicolon delimited list of tag names that series match all of.
exclude_tag_names (Optional[list[str]]) – A semicolon delimited list of tag names that series match none of.
- Return type:
Description
Get economic data series that match search text.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_search(search_text='monetary service index').head() # realtime_start realtime_end title observation_start observation_end frequency frequency_short units units_short seasonal_adjustment seasonal_adjustment_short last_updated popularity group_popularity notes # id # MSIMZMP 2022-02-05 2022-02-05 Monetary Services Index: MZM (preferred) 1967-01-01 2013-12-01 Monthly M Billions of Dollars Bil. of $ Seasonally Adjusted SA 2014-01-17 13:16:42+00:00 20 20 The MSI measure the flow of monetary services ... # MSIM2 2022-02-05 2022-02-05 Monetary Services Index: M2 (preferred) 1967-01-01 2013-12-01 Monthly M Billions of Dollars Bil. of $ Seasonally Adjusted SA 2014-01-17 13:16:44+00:00 16 16 The MSI measure the flow of monetary services ... # MSIALLP 2022-02-05 2022-02-05 Monetary Services Index: ALL Assets (preferred) 1967-01-01 2013-12-01 Monthly M Billions of Dollars Bil. of $ Seasonally Adjusted SA 2014-01-17 13:16:45+00:00 14 14 The MSI measure the flow of monetary services ... # MSIM1P 2022-02-05 2022-02-05 Monetary Services Index: M1 (preferred) 1967-01-01 2013-12-01 Monthly M Billions of Dollars Bil. of $ Seasonally Adjusted SA 2014-01-17 13:16:45+00:00 9 9 The MSI measure the flow of monetary services ... # MSIM2A 2022-02-05 2022-02-05 Monetary Services Index: M2 (alternative) 1967-01-01 2013-12-01 Monthly M Billions of Dollars Bil. of $ Seasonally Adjusted SA 2014-01-17 13:16:44+00:00 8 8 The MSI measure the flow of monetary services ...
- Parameters:
series_search_text (str) – The words to match against economic data series.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
tag_names (Optional[list[str]]) – A semicolon delimited list of tag names to only include in the response. See the related request fred/series/search/related_tags.
exclude_tag_names (Optional[list[str]]) – A semicolon delimited list of tag names that series match none of..
tag_group_id (enums.TagGroupID) – A tag group id to filter tags by type.
tag_search_text (str) – The words to find matching tags with.
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the related FRED tags for one or more FRED tags matching a series search. Optionally, filter results by tag group or tag search.FRED tags are attributes assigned to series.For this request, related FRED tags are the tags assigned to series that match all tags in the tag_names parameter, no tags in the exclude_tag_names parameter,and the search words set by the series_search_text parameter.See the related request fred/series/search/tags.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_search_related_tags(series_search_text='mortgage rate', tag_names=['30-year', 'frb'], realtime_start=date(2022, 1, 5), realtime_end=date(2022, 1, 5)).head() # group_id notes created popularity series_count # name # conventional gen 2012-02-27 16:18:19+00:00 21 2 # discontinued gen 2012-02-27 16:18:19+00:00 67 2 # h15 rls H.15 Selected Interest Rates 2012-08-16 20:21:17+00:00 57 2 # interest gen 2012-02-27 16:18:19+00:00 74 2 # interest rate gen 2012-05-29 15:14:19+00:00 74 2
- series_search_tags(series_search_text: str, realtime_start: date | None = None, realtime_end: date | None = None, tag_names: list[str] | None = None, tag_group_id: TagGroupID | None = None, tag_search_text: str | None = None, order_by: OrderBy = OrderBy.series_count, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
series_search_text (str) – The words to match against economic data series.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
tag_names (Optional[list[str]]) – A semicolon delimited list of tag names to only include in the response. See the related request fred/series/search/related_tags.
tag_group_id (enums.TagGroupID) – A tag group id to filter tags by type.
tag_search_text (str) – The words to find matching tags with.
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the FRED tags for a series search. Optionally, filter results by tag name, tag group, or tag search. See the related request fred/series/search/related_tags.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_search_tags(series_search_text='monetary service index').head() # group_id notes created popularity series_count # name # accounting gen 2012-02-27 16:18:19+00:00 43 2 # advertisement gen 2012-08-06 19:50:07+00:00 17 2 # assets gen 2012-02-27 16:18:19+00:00 64 2 # boe src Bank of England 2013-02-25 22:21:19+00:00 42 2 # communication gen 2012-02-27 16:18:19+00:00 22 2
- series_tags(series_id: str, realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy = OrderBy.series_count, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
series_id (str) – The id for a series.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the FRED tags for a series.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_tags(series_id='STLFSI').head() # group_id notes created popularity series_count # name # stlfsi rls St. Louis Financial Stress Index 2012-08-16 20:21:17+00:00 19 4 # fsi gen Financial Stress Index 2014-08-08 19:01:37+00:00 26 26 # weekly freq 2012-02-27 16:18:19+00:00 68 3548 # financial gen 2012-02-27 16:18:19+00:00 55 21652 # discontinued gen 2012-02-27 16:18:19+00:00 67 40386
- series_updates(realtime_start: date | None = None, realtime_end: date | None = None, filter_value: FilterValue = FilterValue.all, start_time: datetime | None = None, end_time: datetime | None = None) DataFrame[source]
- Parameters:
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
filter_value (enums.FilterValue) – Limit results by geographic type of economic data series; namely ‘macro’, ‘regional’, and ‘all’.
start_time (Optional[datetime]) – Start time for limiting results for a time range, can filter down to minutes
end_time (Optional[datetime]) – End time for limiting results for a time range, can filter down to minutes
- Return type:
Description
Get economic data series sorted by when observations were updated on the FRED server (attribute last_updated).Results are limited to series updated within the last two weeks.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_updates(start_time=datetime(2022, 1, 15), end_time=datetime(2022, 1, 16)).head() # realtime_start realtime_end title observation_start observation_end frequency frequency_short units units_short seasonal_adjustment seasonal_adjustment_short last_updated popularity notes # id # SP500 2022-02-05 2022-02-05 S&P 500 2012-02-06 2022-02-04 Daily, Close D Index Index Not Seasonally Adjusted NSA 2022-02-05 01:11:04+00:00 85 The observations for the S&P 500 represent the... # CBBCHUSD 2022-02-05 2022-02-05 Coinbase Bitcoin Cash 2017-12-20 2022-02-04 Daily, 7-Day D U.S. Dollars U.S. $ Not Seasonally Adjusted NSA 2022-02-05 01:04:07+00:00 22 All data is as of 5 PM PST. # CBBTCUSD 2022-02-05 2022-02-05 Coinbase Bitcoin 2014-12-01 2022-02-04 Daily, 7-Day D U.S. Dollars U.S. $ Not Seasonally Adjusted NSA 2022-02-05 01:04:06+00:00 65 All data is as of 5 PM PST. # CBETHUSD 2022-02-05 2022-02-05 Coinbase Ethereum 2016-05-18 2022-02-04 Daily, 7-Day D U.S. Dollars U.S. $ Not Seasonally Adjusted NSA 2022-02-05 01:04:05+00:00 44 All data is as of 5 PM PST. # CBLTCUSD 2022-02-05 2022-02-05 Coinbase Litecoin 2016-08-17 2022-02-04 Daily, 7-Day D U.S. Dollars U.S. $ Not Seasonally Adjusted NSA 2022-02-05 01:04:03+00:00 20 All data is as of 5 PM PST.
- series_vintagedates(series_id: str, realtime_start: date | None = None, realtime_end: date | None = None, sort_order: SortOrder = SortOrder.asc) Series[source]
- Parameters:
series_id (str) – The id for a series.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
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.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.series_vintagedates(series_id='GNPCA').head() # 0 1958-12-21 # 1 1959-02-19 # 2 1959-07-19 # 3 1960-02-16 # 4 1960-07-22
- source(source_id: int, realtime_start: date | None = None, realtime_end: date | None = None) Source[source]
- Parameters:
source_id (int) – The id for a source.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
- Return type:
Description
Get a source of economic data.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.source(source_id=1) # Source(id=1, realtime_start='2022-01-14', realtime_end='2022-01-14', name='Board of Governors of the Federal Reserve System (US)', link='http://www.federalreserve.gov/')
- source_releases(source_id: int, realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy = OrderBy.release_id, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
source_id (int) – The id for a source.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the releases for a source.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.source_releases(source_id=1).head() # realtime_start realtime_end name press_release link notes # id # 13 2022-02-05 2022-02-05 G.17 Industrial Production and Capacity Utiliz... True http://www.federalreserve.gov/releases/g17/ <NA> # 14 2022-02-05 2022-02-05 G.19 Consumer Credit True http://www.federalreserve.gov/releases/g19/ <NA> # 15 2022-02-05 2022-02-05 G.5 Foreign Exchange Rates True http://www.federalreserve.gov/releases/g5/ <NA> # 17 2022-02-05 2022-02-05 H.10 Foreign Exchange Rates True http://www.federalreserve.gov/releases/h10/ <NA> # 18 2022-02-05 2022-02-05 H.15 Selected Interest Rates True http://www.federalreserve.gov/releases/h15/ <NA>
- sources(realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy = OrderBy.source_id, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get all sources of economic data.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.sources() # realtime_start realtime_end name link notes # id # 1 2022-02-05 2022-02-05 Board of Governors of the Federal Reserve Syst... http://www.federalreserve.gov/ <NA> # 3 2022-02-05 2022-02-05 Federal Reserve Bank of Philadelphia https://www.philadelphiafed.org/ <NA> # 4 2022-02-05 2022-02-05 Federal Reserve Bank of St. Louis http://www.stlouisfed.org/ <NA> # 6 2022-02-05 2022-02-05 Federal Financial Institutions Examination Cou... http://www.ffiec.gov/ <NA> # 11 2022-02-05 2022-02-05 Dow Jones & Company http://www.dowjones.com <NA>
- tags(realtime_start: date | None = None, realtime_end: date | None = None, tag_names: list[str] | None = None, tag_group_id: TagGroupID = None, search_text: str | None = None, order_by: OrderBy = OrderBy.series_count, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
tag_group_id (enums.TagGroupID) – A tag group id to filter tags by type.
search_text (str) – The words to find matching tags with.
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get FRED tags. Optionally, filter results by tag name, tag group, or search. FRED tags are attributes assigned to series. See the related request fred/related_tags.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.tags().head() # group_id notes created popularity series_count # name # 14 years + gen 2012-08-06 19:40:56+00:00 -6 2 # 2-month + gen 2012-08-06 19:34:05+00:00 -62 2 # 2-week gen 2012-05-25 16:29:34+00:00 -6 2 # 30 to 34 years gen 2013-10-10 21:13:04+00:00 -13 2 # 3-family + gen 2012-08-06 19:48:11+00:00 -49 2
- tags_series(tag_names: list[str] | None = None, exclude_tag_names: list[str] | None = None, realtime_start: date | None = None, realtime_end: date | None = None, order_by: OrderBy = OrderBy.series_id, sort_order: SortOrder = SortOrder.asc) DataFrame[source]
- Parameters:
tag_names (Optional[list[str]]) – Tuple of tag names that series match all of.
exclude_tag_names (Optional[list[str]]) – Tuple of tag names that series match none of.
realtime_start (datetime.date) – The start of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
realtime_end (datetime.date) – The end of the real-time period. For more information, see [Real-Time Periods](https://fred.stlouisfed.org/docs/api/fred/realtime_period.html).
order_by (enums.OrderBy) – Order results by values of the specified attribute.
sort_order (enums.SortOrder) – Sort results is ascending or descending order for attribute values specified by order_by.
- Return type:
Description
Get the series matching all tags in the tag_names parameter and no tags in the exclude_tag_names parameter.Example
fred = FRED(api_key="abcdefghijklmnopqrstuvwxyz123456") fred.tags_series(tag_names=['food', 'oecd']).head() # realtime_start realtime_end title observation_start observation_end frequency frequency_short units units_short seasonal_adjustment seasonal_adjustment_short last_updated popularity group_popularity notes # id # AUSCPICORAINMEI 2022-02-05 2022-02-05 Consumer Price Index: All Items Excluding Food... 1972-01-01 2020-01-01 Annual A Index 2015=100 Index 2015=100 Not Seasonally Adjusted NSA 2021-02-17 18:27:39+00:00 1 12 Copyright, 2016, OECD. Reprinted with permissi... # AUSCPICORQINMEI 2022-02-05 2022-02-05 Consumer Price Index: All Items Excluding Food... 1971-04-01 2021-07-01 Quarterly Q Index 2015=100 Index 2015=100 Not Seasonally Adjusted NSA 2021-12-14 21:57:04+00:00 12 12 Copyright, 2016, OECD. Reprinted with permissi... # AUSCPIFODAINMEI 2022-02-05 2022-02-05 Consumer Price Index: Food for Australia 1977-01-01 2017-01-01 Annual A Index 2010=100 Index 2010=100 Not Seasonally Adjusted NSA 2018-03-09 21:12:09+00:00 1 2 Copyright, 2016, OECD. Reprinted with permissi... # AUSCPIFODQINMEI 2022-02-05 2022-02-05 Consumer Price Index: Food for Australia 1976-07-01 2018-01-01 Quarterly Q Index 2010=100 Index 2010=100 Not Seasonally Adjusted NSA 2018-04-24 19:51:04+00:00 2 2 Copyright, 2016, OECD. Reprinted with permissi... # AUTCPICORAINMEI 2022-02-05 2022-02-05 Consumer Price Index: All Items Excluding Food... 1966-01-01 2020-01-01 Annual A Index 2015=100 Index 2015=100 Not Seasonally Adjusted NSA 2021-03-16 22:37:57+00:00 0 1 Copyright, 2016, OECD. Reprinted with permissi...
- class pystlouisfed.ALFRED(api_key: str, ratelimiter_enabled: bool = True, ratelimiter_max_calls: int = 120, ratelimiter_period: timedelta | None = None, request_params: dict | None = None)[source]
ALFRED stands for Archival Federal Reserve Economic Data. ALFRED archives FRED data by adding the real-time period when values were originally released and later revised. For instance on February 2, 1990, the US Bureau of Labor Statistics reported the US unemployment rate for the month of January, 1990 as 5.3 percent. Over 6 years later on March 8, 1996, the US unemployment rate for the same month January, 1990 was revised to 5.4 percent.
- class pystlouisfed.FREDMaps(api_key: str, ratelimiter_enabled: bool = False, ratelimiter_max_calls: int = 120, ratelimiter_period: timedelta = datetime.timedelta(seconds=60), request_params: dict | None = None)[source]
- Maps provide a cross-sectional perspective that lets you compare regions on a map while complementing and expanding the data analysis you get on a time-series graph.
FRED has 9 types (
pystlouisfed.enums.ShapeType) of maps:U.S. counties
U.S. metro areas
U.S. states
nations
Federal Reserve Districts
Census regions
Census divisions
BEA regions
NECTAs (New England city and town areas)
- Parameters:
api_key (str) – 32 character alpha-numeric lowercase string
request_params (dict) – HTTP GET method parameters, see https://docs.python-requests.org/en/latest/api/#requests.request
- regional_data(series_group: str, region_type: RegionType, date: date, season: Seasonality, units: str = 'Dollars', start_date: date | None = None, frequency: Frequency | None = None, transformation: Unit = Unit.lin, aggregation_method: AggregationMethod = AggregationMethod.avg) DataFrame[source]
- Parameters:
series_group (str) – The ID for a group of seriess found in FRED.
region_type (enums.RegionType) – The region you want want to pull data for.
date (datetime.date) – The date you want to pull a series group data from.
season (enums.Seasonality) – The seasonality of the series group.
units (str) – The units of the series you want to pull.
start_date (datetime.date) – The start date you want to request series group data from. This allows you to pull a range of data.
frequency (enums.Frequency) – Frequency automatically assigns the default frequency of the map when using the Request Wizard above. The parameter can be used as a frequency aggregation feature. The maps frequency aggregation feature converts higher frequency data series into lower frequency data series (e.g. converts a monthly data series into an annual data series). In maps, the highest frequency data is daily, and the lowest frequency data is annual. There are 3 aggregation methods available- average, sum, and end of period. See the aggregation_method parameter.
transformation (enums.Unit) – A key that indicates a data value transformation.
aggregation_method (enums.AggregationMethod) – One of the following values: ‘avg’, ‘sum’, ‘eop’
- Return type:
Description
This request returns a cross section of regional data.Example
fred_maps = FREDMaps(api_key="abcdefghijklmnopqrstuvwxyz123456") fred_maps.regional_data( series_group='882', date=date(2013, 1, 1), start_date=datetime.date(2014, 1, 1), region_type=RegionType.state, frequency=Frequency.anual, season=Seasonality.not_seasonally_adjusted ) # region code value series_id year # 0 Texas 48 46739 TXPCPI 2014-01-01 # 1 Mississippi 28 34624 MSPCPI 2014-01-01 # 2 Hawaii 15 45448 HIPCPI 2014-01-01 # 3 Kentucky 21 37226 KYPCPI 2014-01-01 # ...
- series_data(series_id: str, date: date | None = None, start_date: date | None = None) DataFrame[source]
- Parameters:
series_id (str) – The FRED series_id you want to request maps data for. Not all series that are in FRED have geographical data.
date (datetime.date) – The date you want to request series group data from.
start_date (datetime.date) – The start date you want to request series group data from. This allows you to pull a range of data.
- Return type:
Description
This request returns a cross section of regional data for a specified release dateIf no date is specified, the most recent data available are returned.Example
fred_maps = FREDMaps(api_key="abcdefghijklmnopqrstuvwxyz123456") fred_maps.series_data(series_id='WIPCPI') # region code value series_id year # 0 Louisiana 22 54622 LAPCPI 2022-01-01 # 1 Nevada 32 61282 NVPCPI 2022-01-01 # 2 Maryland 24 70730 MDPCPI 2022-01-01 # 3 Arizona 4 56667 AZPCPI 2022-01-01 # 4 New York 36 78089 NYPCPI 2022-01-01
- series_group(series_id: str) SeriesGroup[source]
- Parameters:
series_id (str) – Series ID
- Return type:
Description
This request returns the meta information needed to make requests for FRED data.Minimum and maximum date are also supplied for the data range available.Example
fred_maps = FREDMaps(api_key="abcdefghijklmnopqrstuvwxyz123456") group = geo_fred.series_group(series_id="SMU56000000500000001a") # SeriesGroup(title='All Employees: Total Private', region_type='state', series_group='1223', season='NSA', units='Thousands of Persons', frequency='a', min_date=datetime.date(1990, 1, 1), max_date=datetime.date(2020, 1, 1))
- shapes(shape: ShapeType) GeoDataFrame[source]
- Parameters:
shape (enums.ShapeType) – Shape
- Return type:
Description
This request returns shape files from FRED in GeoJSON format.Examples
Get country polygons:
from pystlouisfed import FREDMaps, ShapeType fred_maps = FREDMaps(api_key="abcdefghijklmnopqrstuvwxyz123456") shapes = fred_maps.shapes(shape=ShapeType.country) # geometry hc-group hc-middle-x hc-middle-y hc-key hc_a2 name labelrank country-abbrev subregion region-wb iso-a3 iso-a2 woe-id continent # 0 POLYGON ((3991.000 8611.000, 4005.000 8598.000... admin0 0.48 0.54 fo FO Faroe Islands 6 Faeroe Is. Northern Europe Europe & Central Asia FRO FO 23424816 Europe # 1 POLYGON ((-605.000 6652.000, -606.000 6652.000... admin0 0.57 0.58 um UM United States Minor Outlying Islands 5 U.S. MOI Seven seas (open ocean) East Asia & Pacific UMI UM 28289407 North America # 2 MULTIPOLYGON (((556.000 8034.000, 559.000 8032... admin0 0.68 0.68 us US United States of America 2 U.S.A. Northern America North America USA US 23424977 North America # 3 MULTIPOLYGON (((8389.000 7914.000, 8390.000 79... admin0 0.52 0.66 jp JP Japan 2 Japan Eastern Asia East Asia & Pacific JPN JP 23424856 Asia # 4 POLYGON ((5849.000 6344.000, 5852.000 6341.000... admin0 0.58 0.41 sc SC Seychelles 6 Syc. Eastern Africa Sub-Saharan Africa SYC SC 23424941 Seven seas (open ocean) # 5 MULTIPOLYGON (((6818.000 7133.000, 6820.000 71... admin0 0.34 0.43 in IN India 2 India Southern Asia South Asia IND IN 23424848 Asia
Plot with Matplotlib:
from pystlouisfed import FREDMaps, ShapeType import matplotlib.pyplot as plt gdf = FREDMaps(api_key="abcdefghijklmnopqrstuvwxyz123456") \ .shapes(shape=ShapeType.state) \ .plot(figsize=(12, 8)) plt.show()
Plot with Plotly:
from pystlouisfed import FREDMaps, ShapeType import plotly.express as px gdf = FREDMaps(api_key="abcdefghijklmnopqrstuvwxyz123456") \ .shapes(shape=ShapeType.state) \ .to_crs(epsg=4326) \ .set_index("name") fig = px.choropleth( gdf, geojson=gdf.geometry, locations=gdf.index, color="fips", ) fig.update_layout(width=1200, height=1000, showlegend=False) fig.update_geos(fitbounds="locations", visible=False) fig.show()
or plot
pystlouisfed.ShapeType.country
- class pystlouisfed.FRASER[source]
- FRASER is a digital library of U.S. economic, financial, and banking history—particularly the history of the Federal Reserve System.Providing economic information and data to the public is an important mission for the St. Louis Fed started by former St. Louis Fed Research Director Homer Jones in 1958.FRASER began as a data preservation and accessibility project of the Federal Reserve Bank of St. Louis in 2004 and now provides access to data and policy documents from the Federal Reserve System and many other institutions.
https://fraser.stlouisfed.org/ https://research.stlouisfed.org/docs/api/fraser/
- get_record(identifier: str) Record[source]
- Return type:
Description
This request returns a single record from the FRASER repository.Example
from pystlouisfed import FRASER record = FRASER().get_record(identifier='oai:fraser.stlouisfed.org:title:176') print(record)
<record xmlns="http://www.openarchives.org/OAI/2.0/"> <header> <identifier>oai:fraser.stlouisfed.org:title:176</identifier> <datestamp>2023-12-01T14:55:47Z</datestamp> <setSpec>author:524</setSpec> <setSpec>author:8499</setSpec> <setSpec>subject:4145</setSpec> <setSpec>subject:6824</setSpec> <setSpec>subject:4293</setSpec> <setSpec>theme:8</setSpec> <setSpec>theme:97</setSpec> </header> <metadata> <mods xmlns="http://www.loc.gov/mods/v3" xmlns:default="http://www.loc.gov/mods/v3" default:xsi="http://www.loc.gov/standards/mods/v3/mods-3-5.xsd" default:schemaLocation="http://www.loc.gov/standards/mods/v3/mods-3-5.xsd"> <name> <role> <roleTerm>creator</roleTerm> </role> <namePart>United States. Congress. Senate. Committee on Finance</namePart> <namePart type="date">1815-</namePart> <recordInfo> <recordIdentifier>524</recordIdentifier> </recordInfo> </name> <name> <role> <roleTerm>contributor</roleTerm> </role> <namePart>Seventy-Second Congress</namePart> <namePart type="date">1931-1933</namePart> <recordInfo> <recordIdentifier>8499</recordIdentifier> </recordInfo> </name> <genre>government publication</genre> <subject> <theme> <theme>Great Depression</theme> <recordInfo> <recordIdentifier>8</recordIdentifier> </recordInfo> </theme> <theme> <theme>Meltzer's History of the Federal Reserve - Primary Sources</theme> <recordInfo> <recordIdentifier>97</recordIdentifier> </recordInfo> </theme> <topic> <topic>Economic conditions</topic> <recordInfo> <recordIdentifier>4145</recordIdentifier> </recordInfo> </topic> <topic> <topic>Congressional hearings</topic> <recordInfo> <recordIdentifier>6824</recordIdentifier> </recordInfo> </topic> <geographic> <geographic>United States</geographic> <recordInfo> <recordIdentifier>4293</recordIdentifier> </recordInfo> </geographic> </subject> <language>eng</language> <titleInfo> <title>Investigation of Economic Problems</title> <subTitle>Hearings Before the Committee on Finance, United States Senate</subTitle> <titlePartNumber>Seventy-Second Congress, Second Session, Pursuant to S. Res. 315, February 13 to 28, 1933</titlePartNumber> </titleInfo> <identifier type="oclc">4350587</identifier> <originInfo> <place>Washington</place> <issuance>monographic</issuance> <sortDate>1933-02-13</sortDate> <publisher>Government Printing Office</publisher> <dateIssued>February 13-28, 1933</dateIssued> </originInfo> <relatedItem type="series"> <titleInfo> <title>Congressional Documents</title> </titleInfo> <recordInfo> <recordIdentifier>5292</recordIdentifier> </recordInfo> </relatedItem> <classification authority="sudocs">Y 4.F 49:Ec 7/</classification> <typeOfResource>text</typeOfResource> <accessCondition>http://rightsstatements.org/vocab/NoC-US/1.0/</accessCondition> <physicalDescription> <form>print</form> <extent>1246 pages</extent> <digitalOrigin>reformatted digital</digitalOrigin> <internetMediaType>application/pdf</internetMediaType> </physicalDescription> <location> <url>https://fraser.stlouisfed.org/oai/title/investigation-economic-problems-176</url> <url access="preview">https://fraser.stlouisfed.org/images/record-thumbnail.jpg</url> <url access="raw object">https://fraser.stlouisfed.org/oai/docs/historical/senate/1933sen_investeconprob/1933sen_investeconprob.pdf</url> </location> <contentType>title</contentType> </mods> </metadata> </record>
- list_identifiers(ignore_deleted: bool = False, set: str | None = None) BaseOAIIterator[source]
- Parameters:
set (str) –
str, This parameter specifies the setSpec value and limits the records that are retrieved to only those in the specified set Ignore this parameter to return all records.- Return type:
sickle.iterator.BaseOAIIterator
Description
This request returns headers for records in the FRASER repository.A resumptionToken can be used to retrieve all records using multiple requests.Example
from pystlouisfed import FRASER for header in FRASER().list_identifiers(): print(header.identifier) # oai:fraser.stlouisfed.org:title:1 # oai:fraser.stlouisfed.org:title:7 # oai:fraser.stlouisfed.org:title:37 # oai:fraser.stlouisfed.org:title:38 # oai:fraser.stlouisfed.org:title:39 # ...
- list_records(ignore_deleted: bool = False, set: str | None = None) BaseOAIIterator[source]
- Parameters:
set (str) – This parameter specifies the setSpec value and limits the records that are retrieved to only those in the specified set. Ignore this parameter to return all records.
- Return type:
sickle.iterator.BaseOAIIterator
Description
This request returns title records from the FRASER repository.A resumptionToken can be used to retrieve all records using multiple requests.Additional information about an individual title, including the title’s child records, can be retrieved using the GetRecord request.Example
from pystlouisfed import FRASER for record in FRASER().list_records(): print(record.get_metadata())
First record metadata:
{ "name": [None], "role": [None], "roleTerm": ["creator"], "namePart": ["United States. Women's Bureau"], "recordInfo": [None, None], "recordIdentifier": ["770", "243"], "genre": ["government publication"], "language": ["eng"], "titleInfo": [None, None, None, None], "title": [ "15 Years After College: A Study of Alumnae of the Class of 1945", "Bulletin of the Women's Bureau", "Bulletin of the Women's Bureau", "Women's Bureau Bulletin" ], "subTitle": ["Women's Bureau Bulletin, No. 283"], "originInfo": [None], "place": ["Washington"], "issuance": ["monographic"], "sortDate": ["1962-01-01"], "publisher": ["Govt. Print. Off."], "dateIssued": ["1962"], "relatedItem": [None], "sortOrder": ["b0283"], "typeOfResource": ["text"], "physicalDescription": [None], "form": ["print"], "extent": ["32 pages"], "digitalOrigin": ["reformatted digital"], "internetMediaType": ["application/pdf"], "contentType": ["title"], "location": [None], "url": [ "https://fraser.stlouisfed.org/oai/title/15-years-college-a-study-alumnae-class-1945-5549", "https://fraser.stlouisfed.org/images/record-thumbnail.jpg" ], "accessCondition": [ "For more information on rights relating to this item, please see: https://fraser.stlouisfed.org/oai/title/15-years-college-a-study-alumnae-class-1945-5549" ] }
- list_sets() BaseOAIIterator[source]
- Return type:
sickle.iterator.BaseOAIIterator
Description
This request returns the set structure for records in the FRASER repository.A resumptionToken can be used to retrieve the complete set structure using multiple requests.Example
from pystlouisfed import FRASER for set in FRASER().list_sets(): print(set) # <set xmlns="http://www.openarchives.org/OAI/2.0/"><setSpec>author</setSpec><setName>Authors</setName></set> # <set xmlns="http://www.openarchives.org/OAI/2.0/"><setSpec>author:1</setSpec><setName>Council of Economic Advisers (U.S.)</setName></set> # <set xmlns="http://www.openarchives.org/OAI/2.0/"><setSpec>author:10</setSpec><setName>United States. Federal Open Market Committee</setName></set> # <set xmlns="http://www.openarchives.org/OAI/2.0/"><setSpec>author:10064</setSpec><setName>Quarles, Randal Keith, 1957-</setName></set> # <set xmlns="http://www.openarchives.org/OAI/2.0/"><setSpec>author:10087</setSpec><setName>Dana, William B. (William Buck), 1829-1910</setName></set> # ...