Special Notes: Added Helpers and Return Object Properties (FedFred 3.0+)#

Starting from version 3.0, the fedfred library introduces new helper methods and additional properties in return objects. These enhancements make it easier to interact with the FRED® API while ensuring full compatibility and clean code design.

This page details these important features.

—

New Helper Methods in FedFred#

The fedfred.helpers module now includes additional helper methods to facilitate data handling and conversion.

Added Helper Methods#

Examples of New Helper Methods#

  • Using fedfred.helpers.FredHelpers.pd_frequency_conversion() to convert frequency strings:

    from fedfred.helpers import FredHelpers

freq_str = "BW" # FedFred frequency string for "Biweekly"
pd_freq = FredHelpers.pd_frequency_conversion(freq_str)
print(pd_freq)  # Output: '2W'

  • Using fedfred.helpers.FredHelpers.to_pd_series() to convert DataFrame to Series:

    from fedfred.helpers import FredHelpers
import pandas as pd

# Sample DataFrame
df = pd.DataFrame({
    'date': ['2020-01-01', '2020-02-01', '2020-03-01'],
    'value': [100, 200, 300]
}).set_index('date')

series = FredHelpers.to_pd_series(df, "value")
print(series)
# Output:
# date
# 2020-01-01    100
# 2020-02-01    200
# 2020-03-01    300
# Name: value, dtype: int64

—

Additional Properties in Return Objects#

Several return objects in the fedfred.objects module have been enhanced with additional properties to provide more context and information.

Enhanced Return Object Properties#

New Properties:

—

Global API Key Configuration#

To simplify API key management, FedFred now supports setting a global API key that will be used across all instances of fedfred.clients.FredAPI.

Setting a Global API Key#

You can set a global API key using the :function:`fedfred.config.set_api_key(api_key)` function:

import fedfred as fd
fd.set_api_key("your_global_api_key")

Overriding the Global API Key#

You can still override the global API key by providing an api_key parameter when instantiating fedfred.clients.FredAPI:

from fedfred.clients import FredAPI

# This instance uses the global API key
fred_global = FredAPI()

# This instance uses a specific API key
fred_specific = FredAPI(api_key="your_specific_api_key")

Special Notes: Parameter Conversion and Nested Classes (FedFred 2.0+)#

Starting from version 2.0, the fedfred library introduces automatic parameter conversion and nested class access. These enhancements make it easier to interact with the FRED® API while ensuring full compatibility and clean code design.

This page details these important features.

—

Parameter Conversion in FedFred#

FedFred automatically converts method parameters into formats accepted by the FRED API, simplifying the user experience.

Supported Conversions#

  • datetime.datetime objects:

    Automatically converted to YYYY-MM-DD formatted strings.

    Example:

    from datetime import datetime
fred.get_series_observations(
    series_id="GNPCA",
    observation_start=datetime(2020, 1, 1)
)
# Converts to: "2020-01-01"

  • list of str or str:

    Lists are converted into semicolon-delimited strings.

    Example:

    fred.get_tags(tag_names=["nation", "usa", "economy"])
# Converts to: "nation;usa;economy"

  • Optional[Union[str, list[str]]]:

    Accepts either a string or a list of strings seamlessly.

    Example:

    fred.get_related_tags(tag_names="nation")
fred.get_related_tags(tag_names=["nation", "usa"])

  • Optional[Union[str, datetime.datetime]]:

    Accepts either a string date or a datetime object.

    Example:

    fred.get_series_observations(
    series_id="GNPCA",
    observation_start="2020-01-01",
    observation_end=datetime(2021, 1, 1)
)

Helper Methods for Conversion#

Parameter conversion is handled internally by helper methods in the fedfred.helpers.FredHelpers class:

See Resources for more about helper utilities.

—

Examples of Parameter Conversion#

  • Using datetime.datetime parameters:

    from datetime import datetime
fred.get_series_observations(
    series_id="GNPCA",
    observation_start=datetime(2020, 1, 1),
    observation_end=datetime(2021, 1, 1)
)

  • Using list parameters:

    fred.get_tags(tag_names=["sticky", "price", "nation"])

  • Mixing str and list parameters:

    fred.get_related_tags(tag_names="nation")
fred.get_related_tags(tag_names=["nation", "usa"])

—

Accessing Nested Classes in fedfred.clients.FredAPI#

FedFred’s fedfred.clients.FredAPI contains nested classes that expand functionality for asynchronous (async) and geospatial (GeoDataFrame) data retrieval.

Available Nested Classes#

  • fedfred.clients.FredAPI.AsyncAPI (accessed via fred.Async ):

    import asyncio
from fedfred.clients import FredAPI

fred = FredAPI(api_key="your_api_key")
async_api = fred.Async

async def main():
    categories = await async_api.get_category_children(category_id=0)
    for category in categories:
        print(category.name)

asyncio.run(main())

  • fedfred.clients.FredAPI.MapsAPI (accessed via fred.Maps ):

    from fedfred.clients import FredAPI

fred = FredAPI(api_key="your_api_key")
maps_api = fred.Maps

regional_data = maps_api.get_series_data(
    series_id="SMU53000000500000001",
    date="2023-01-01"
)
print(regional_data)

  • fedfred.clients.FredAPI.AsyncAPI.AsyncMapsAPI (accessed via fred.Async.Maps ):

    import asyncio
from fedfred.clients import FredAPI

fred = FredAPI(api_key="your_api_key")
async_maps_api = fred.Async.Maps

async def main():
    regional_data = await async_maps_api.get_series_data(
        series_id="SMU53000000500000001",
        date="2023-01-01"
    )
    print(regional_data)

asyncio.run(main())

—