pystlouisfed

https://github.com/tomaskoutek/pystlouisfed
Admin
pystlouisfed is a Python client for the Federal Reserve Bank of St. Louis APIs, providing access to...
Tokens:33,207
Snippets:133
Trust Score:5.7
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### 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
<class 'pandas.core.frame.DataFrame'>
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&region_type=state&units=ABC&frequency=a&season=NSA
```

```xml
<series_data title="2022 Per Capita Personal Income by State (ABC)" region="state" seasonality="Not Seasonally Adjusted" units="ABC" frequency="Annual">
    <observation date="2013-01-01" region="Arizona" code="04" value="36877" series_id="AZPCPI"/>
    <observation date="2013-01-01" region="Hawaii" code="15" value="43553" series_id="HIPCPI"/>
    ...
```

```text
https://api.stlouisfed.org/geofred/regional/data?series_group=882&date=2013-01-01&region_type=state&units=SOME-UNIT-PARAMETER&frequency=a&season=NSA
```

```xml
<series_data title="2022 Per Capita Personal Income by State (SOME-UNIT-PARAMETER)" region="state" seasonality="Not Seasonally Adjusted" units="SOME-UNIT-PARAMETER" frequency="Annual">
    <observation date="2013-01-01" region="Arizona" code="04" value="36877" series_id="AZPCPI"/>
    <observation date="2013-01-01" region="Hawaii" code="15" value="43553" series_id="HIPCPI"/>
    ...
```

--------------------------------

### 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())
```
Tokens:
Raw