### Install pystlouisfed from PyPI Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/doc/install.rst Installs the pystlouisfed package from PyPI using pip. This is the recommended installation method. ```console python3 -m pip install pystlouisfed ``` -------------------------------- ### Get a Source by ID Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Retrieve a Source object by its ID. The example uses source_id=1 and shows the resulting Source object with its attributes. ```python from pystlouisfed import FRED 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/') ``` -------------------------------- ### DataFrame output example Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Example output of a pandas DataFrame returned by pystlouisfed methods, showing the column names, data types, and memory usage. ```text Index: 47 entries, AITGCBN to IEABCSN Data columns (total 15 columns): # Column Non-Null Count Dtype --- ------ -------------- ----- 0 realtime_start 47 non-null datetime64[ns] 1 realtime_end 47 non-null datetime64[ns] 2 title 47 non-null string 3 observation_start 47 non-null datetime64[ns] 4 observation_end 47 non-null datetime64[ns] 5 frequency 47 non-null category 6 frequency_short 47 non-null category 7 units 47 non-null category 8 units_short 47 non-null category 9 seasonal_adjustment 47 non-null category 10 seasonal_adjustment_short 47 non-null category 11 last_updated 47 non-null datetime64[ns, UTC] 12 popularity 47 non-null int64 13 group_popularity 47 non-null int64 14 notes 47 non-null string dtypes: category(6), datetime64[ns, UTC](1), datetime64[ns](4), int64(2), string(2) memory usage: 25.0 KB ``` -------------------------------- ### Downloading series with rate limiting Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Example of downloading all series with the tags 'daily' and 'nsa' while excluding 'discontinued', using the built-in rate limiting. ```python from pystlouisfed import FRED fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') series = fred.tags_series(tag_names=['daily', 'nsa'], exclude_tag_names=['discontinued']) for series_id in series.index.values: df = fred.series_observations(series_id=series_id) ``` -------------------------------- ### Clone pystlouisfed from GitHub Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/doc/install.rst Clones the pystlouisfed repository from GitHub. This is an alternative to installing from PyPI. ```console git clone https://github.com/TomasKoutek/pystlouisfed ``` -------------------------------- ### Get a Category by ID Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Retrieve a Category object by its ID. The example uses category_id=125 and shows the resulting Category object with its attributes. ```python from pystlouisfed import FRED fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') category = fred.category(category_id=125) # Category(id=125, name='Trade Balance', parent_id=13) ``` -------------------------------- ### Calling series_observations with enums Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Example of calling series_observations with the AggregationMethod and Frequency enums. ```python from pystlouisfed import FRED, AggregationMethod, Frequency fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') df = fred.series_observations(series_id='T10Y2Y', aggregation_method=AggregationMethod.end_of_period, frequency=Frequency.weekly_ending_friday) ``` -------------------------------- ### FRASER metadata example for a record Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Example metadata returned for the FRASER record 'oai:fraser.stlouisfed.org:title:176' when printed by the preceding snippet. It shows the structure with fields like accessCondition, creator names, URLs, and a nested theme entry referencing Meltzer's History of the Federal Reserve. ```json { "accessCondition": ["http://rightsstatements.org/vocab/NoC-US/1.0/"], "classification": ["Y 4.F 49:Ec 7/"], "contentType": ["title"], "dateIssued": ["February 13-28, 1933"], "digitalOrigin": ["reformatted digital"], "extent": ["1246 pages"], "form": ["print"], "genre": ["government publication"], "geographic": [None, "United States"], "identifier": ["4350587"], "internetMediaType": ["application/pdf"], "issuance": ["monographic"], "language": ["eng"], "location": [None], "name": [None, None], "originInfo": [None], "physicalDescription": [None], "place": ["Washington"], "publisher": ["Government Printing Office"], "recordInfo": [None, None, None, None, None, None, None, None], "relatedItem": [None], "role": [None, None], "roleTerm": ["creator", "contributor"], "sortDate": ["1933-02-13"], "recordIdentifier": ["524", "8499", "8", "97", "4145", "6824", "4293", "5292"], "subTitle": ["Hearings Before the Committee on Finance, United States Senate"], "subject": [None], "namePart": [ "United States. Congress. Senate. Committee on Finance", "1815-", "Seventy-Second Congress", "1931-1933" ], "theme": [ None, "Great Depression", None, "Meltzer\"s History of the Federal Reserve - Primary Sources" ], "title": ["Investigation of Economic Problems", "Congressional Documents"], "titleInfo": [None, None], "titlePartNumber": ["Seventy-Second Congress, Second Session, Pursuant to S. Res. 315, February 13 to 28, 1933"], "topic": [None, "Economic conditions", None, "Congressional hearings"], "typeOfResource": ["text"], "url": [ "https://fraser.stlouisfed.org/oai/title/investigation-economic-problems-176", "https://fraser.stlouisfed.org/images/record-thumbnail.jpg", "https://fraser.stlouisfed.org/oai/docs/historical/senate/1933sen_investeconprob/1933sen_investeconprob.pdf" ] } ``` -------------------------------- ### Inspect DataFrame info for category series Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Display DataFrame info for a category series. The example fetches series for category 125 and prints detailed info including memory usage. Requires a valid FRED API key. ```python from pystlouisfed import FRED fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') df = fred.category_series(125) print(df.info(verbose=True, memory_usage='deep')) ``` -------------------------------- ### Search series by text Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Search for series by text using FRED.series_search. The example searches for 'monetary service index' and prints the first five rows of the resulting DataFrame. ```python from pystlouisfed import FRED fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') df = fred.series_search(search_text='monetary service index') print(df.head()) ``` -------------------------------- ### Plot FRED Maps shape data with plotly choropleth Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Use FREDMaps.shapes() to get a GeoDataFrame, transform to EPSG:4326, and plot with plotly.express.choropleth. Requires an API key and the plotly and geopandas libraries. The example sets a fixed figure size and fits the map to the data bounds. ```python import plotly.express as px from pystlouisfed import FREDMaps, ShapeType gdf = FREDMaps(api_key="abcdefghijklmnopqrstuvwxyz123456") \ .shapes(shape=ShapeType.country) \ .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() ``` -------------------------------- ### FRED series search output Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Example output from FRED series search showing the DataFrame structure with columns like realtime_start, title, frequency, units, and notes. The output includes multiple Monetary Services Index series with their metadata. ```text 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 ... ``` -------------------------------- ### Get category series as DataFrame Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Retrieve all series for a specific category (category_id=125) as a pandas DataFrame and print the first five rows. The output shows the DataFrame columns and sample rows. ```python from pystlouisfed import FRED fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') df = fred.category_series(category_id=125) print(df.head()) ``` ```text 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 ... ``` -------------------------------- ### Plot FRED series with matplotlib Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Plot FRED series observations using matplotlib. The example fetches the T10Y2Y series and plots the 'value' column with a grid. Requires a valid FRED API key. ```python from matplotlib import pyplot as plt from pystlouisfed import FRED fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') # T10Y2Y - 10-Year Treasury Constant Maturity Minus 2-Year Treasury Constant Maturity df = fred.series_observations(series_id='T10Y2Y') df.plot(y='value', grid=True) plt.show() ``` -------------------------------- ### Plot FRED series with Plotly Express Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Plot FRED series observations using Plotly Express with an OLS trendline. The example fetches the SP500 series and creates a scatter plot with a red trendline. Requires a valid FRED API key. ```python import plotly.express as px from pystlouisfed import FRED fred = FRED(api_key='3a3380d8e2f1c64b28f3bb4805ca6c22') 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() ``` -------------------------------- ### Retrieve FRED Maps series data for a specific series ID Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Use FREDMaps.series_data() to fetch data for a given series ID (e.g., 'WIPCPI'). The method returns a DataFrame with columns for region, code, value, series_id, and year. The example prints the first five rows, showing sample output for the series. ```python from pystlouisfed import FREDMaps fred_maps = FREDMaps(api_key="abcdefghijklmnopqrstuvwxyz123456") fred_maps.series_data(series_id='WIPCPI') print(fred_maps.head()) # 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 ``` -------------------------------- ### Show help for FRED.series_search Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Display the detailed documentation for the FRED.series_search method using the built-in help function. ```python from pystlouisfed import FRED help(FRED.series_search) ``` -------------------------------- ### Fetch all GDP revisions with realtime_start Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Requests all historical revisions for GDP by setting realtime_start to an early date, yielding 3068 values. ```python from pystlouisfed import FRED from datetime import date fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') df = fred.series_observations(series_id='GDP', realtime_start=date(1776, 7, 4)) print(len(df)) # 3068 ``` -------------------------------- ### Fetch GDP revisions for a date range and show output Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Fetches GDP observations for a specific real-time range and displays the output showing how the value for 2021-07-01 changed across revisions. ```python from pystlouisfed import FRED from datetime import date fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') df = fred.series_observations(series_id='GDP', realtime_start=date(2021, 11, 1), realtime_end=date(2022, 1, 1)) df.loc['2021-07-01':'2021-07-01'] ``` ```text realtime_start realtime_end value date 2021-07-01 2021-11-01 2021-11-23 23173.496 2021-07-01 2021-11-24 2021-12-21 23187.042 2021-07-01 2021-12-22 2022-01-01 23202.344 ``` -------------------------------- ### Fetch current FRED observations for GDP Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Fetches the current FRED observations for the GDP series using default real-time settings, returning 303 values. ```python from pystlouisfed import FRED fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') df = fred.series_observations(series_id='GDP') print(len(df)) # 303 ``` -------------------------------- ### Fetch a FRASER record by OAI-PMH identifier Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Use this snippet to fetch metadata for a FRASER publication via its OAI-PMH identifier. It initializes the FRASER client, retrieves a record with the given identifier, extracts its metadata, and prints it. ```python from pystlouisfed import FRASER fraser = FRASER() record = fraser.get_record(identifier='oai:fraser.stlouisfed.org:title:176') metadata = record.get_metadata() print(metadata) ``` -------------------------------- ### FRED.series_observations method signature Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Signature of the FRED.series_observations method, showing the optional parameters and their default values using pystlouisfed enums. ```python def series_observations( self, series_id: str, realtime_start: date = None, realtime_end: date = None, sort_order: enums.SortOrder = enums.SortOrder.asc, observation_start: date = date(1776, 7, 4), observation_end: date = date(9999, 12, 31), units: enums.Unit = enums.Unit.lin, frequency: enums.Frequency = None, aggregation_method: enums.AggregationMethod = enums.AggregationMethod.average, output_type: enums.OutputType = enums.OutputType.realtime_period, vintage_dates: List[str] = None ) -> pd.DataFrame: ``` -------------------------------- ### AggregationMethod enum definition Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/README.md Definition of the AggregationMethod enum, showing the available values and their aliases. ```python from enum import Enum class AggregationMethod(Enum): """ A key that indicates the aggregation method used for frequency aggregation. """ avg = 'avg' """ Average (same as `pystlouisfed.enums.AggregationMethod.average`) """ average = 'avg' """ Average (same as `pystlouisfed.enums.AggregationMethod.avg`) """ sum = 'sum' """ Sum """ eop = 'eop' """ End of Period (same as `pystlouisfed.enums.AggregationMethod.end_of_period`) """ end_of_period = 'eop' """ End of Period (same as `pystlouisfed.enums.AggregationMethod.eop`) """ ``` -------------------------------- ### FRED Maps regional_data units parameter effect Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/doc/strange.rst Shows that the units parameter in FRED Maps regional_data only changes the title and units attribute in the response, not the actual data values. The first pair uses units=ABC, the second uses units=SOME-UNIT-PARAMETER; both return identical observations. ```text https://api.stlouisfed.org/geofred/regional/data?series_group=882&date=2013-01-01®ion_type=state&units=ABC&frequency=a&season=NSA ``` ```xml ... ``` ```text https://api.stlouisfed.org/geofred/regional/data?series_group=882&date=2013-01-01®ion_type=state&units=SOME-UNIT-PARAMETER&frequency=a&season=NSA ``` ```xml ... ``` -------------------------------- ### FRED.series_observations timezone-sensitive call Source: https://github.com/tomaskoutek/pystlouisfed/blob/master/doc/strange.rst Calls series_observations with today's date as both realtime_start and realtime_end. In the Europe/Prague timezone at 2:00am, this can trigger a 'Bad Request. Variable realtime_start can not be after today's date…' error because FRED/ALFRED uses the US/Central timezone (UTC−06:00). ```python from pystlouisfed import FRED from datetime import date fred = FRED(api_key='abcdefghijklmnopqrstuvwxyz123456') fred.series_observations(series_id='GDP', realtime_start=date.today(), realtime_end=date.today()) ```