AsyncAPI Class¶

class fedfred.FredAPI.AsyncAPI(parent)¶

Bases: object

The Async sub-class contains async methods for interacting with the Federal Reserve Bank of St. Louis FRED® API.

Parameters:: parent (FredAPI)

async get_category(category_id)¶

Get a FRED Category

Retrieve information about a specific category from the FRED API.

Parameters:: category_id (int) – The ID of the category to retrieve.
Returns:: If multiple categories are returned.
Return type:: List[Category]
Raises:: ValueError – If the response from the FRED API indicates an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     category = await fred.get_category(125)
>>>     for c in category:
>>>         print(category[0].name)
>>> asyncio.run(main())
'Trade Balance'

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/category.html

async get_category_children(category_id, realtime_start=None, realtime_end=None)¶

Get a FRED Category’s Child Categories

Get the child categories for a specified category ID from the FRED API.

Parameters:

category_id (int) – The ID for the category whose children are to be retrieved.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.

Returns:

If multiple categories are returned.

Return type:

List[Category]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = FredAPI('your_api_key').Async
>>>     children = await fred.get_category_children(13)
>>>     for child in children:
>>>         print(child.name)
>>> asyncio.run(main())
'Exports'
'Imports'
'Income Payments & Receipts'
'U.S. International Finance

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/category_children.html

async get_category_related(category_id, realtime_start=None, realtime_end=None)¶

Get a FRED Category’s Related Categories

Get related categories for a given category ID from the FRED API.

Parameters:

category_id (int) – The ID for the category.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.

Returns:

If multiple categories are returned.

Return type:

List[Category]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = FredAPI('your_api_key').Async
>>>     related = await fred.get_category_related(32073)
>>>     for category in related:
>>>         print(category.name)
>>> asyncio.run(main())
'Arkansas'
'Illinois'
'Indiana'
'Kentucky'
'Mississippi'
'Missouri'
'Tennessee'

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/category_related.html

async get_category_related_tags(category_id, realtime_start=None, realtime_end=None, tag_names=None, exclude_tag_names=None, tag_group_id=None, search_text=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get a FRED Category’s Related Tags

Retrieve all tags related to a specified category from the FRED API.

Parameters:

category_id (int) – The ID for the category.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
tag_names (str | list, optional) – A semicolon-delimited list of tag names to include.
exclude_tag_names (str | list, optional) – A semicolon-delimited list of tag names to exclude.
tag_group_id (int, optional) – The ID for a tag group.
search_text (str, optional) – The words to find matching tags with.
limit (int, optional) – The maximum number of results to return.
offset (int, optional) – The offset for the results.
order_by (str, optional) – Order results by values such as ‘series_count’, ‘popularity’, etc.
sort_order (str, optional) – Sort order, either ‘asc’ or ‘desc’.

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the request to the FRED API fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_category_related_tags(125)
>>>     for tag in tags:
>>>         print(tag.name)
>>> asyncio.run(main())
'balance'
'bea'
'nation'
'usa'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/category_related_tags.html

async get_category_series(category_id, realtime_start=None, realtime_end=None, limit=None, offset=None, order_by=None, sort_order=None, filter_variable=None, filter_value=None, tag_names=None, exclude_tag_names=None)¶

Get a FRED Category’s FRED Series

Get the series info for all series in a category from the FRED API.

Parameters:

category_id (int) – The ID for a category.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Used for pagination.
order_by (str, optional) – Order results by values. Options are ‘series_id’, ‘title’, ‘units’, ‘frequency’, ‘seasonal_adjustment’, ‘realtime_start’, ‘realtime_end’, ‘last_updated’, ‘observation_start’, ‘observation_end’, ‘popularity’, ‘group_popularity’.
sort_order (str, optional) – Sort results in ascending or descending order. Options are ‘asc’ or ‘desc’.
filter_variable (str, optional) – The attribute to filter results by. Options are ‘frequency’, ‘units’, ‘seasonal_adjustment’.
filter_value (str, optional) – The value of the filter_variable to filter results by.
tag_names (str | list, optional) – A semicolon-separated list of tag names to filter results by.
exclude_tag_names (str | list, optional) – A semicolon-separated list of tag names to exclude results by.

Returns:

If multiple series are returned.

Return type:

List[Series]

Raises:

ValueError – If the request to the FRED API fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     series = await fred.get_category_series(125)
>>>     for s in series:
>>>         print(s.frequency)
>>> asyncio.run(main())
'Quarterly'
'Annual'
'Quarterly'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/category_series.html

async get_category_tags(category_id, realtime_start=None, realtime_end=None, tag_names=None, tag_group_id=None, search_text=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get a FRED Category’s Tags

Get the all the tags for a category from the FRED API.

Parameters:

category_id (int) – The ID for a category.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
tag_names (str | list, optional) – A semicolon delimited list of tag names to filter tags by.
tag_group_id (int, optional) – A tag group ID to filter tags by type.
search_text (str, optional) – The words to find matching tags with.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Used for pagination.
order_by (str, optional) – Order results by values. Options are ‘series_count’, ‘popularity’, ‘created’, ‘name’. Default is ‘series_count’.
sort_order (str, optional) – Sort results in ascending or descending order. Options are ‘asc’, ‘desc’. Default is ‘desc’.

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the request to the FRED API fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_category_tags(125)
>>>     for tag in tags:
>>>         print(tag.notes)
>>> asyncio.run(main())
'U.S. Department of Commerce: Bureau of Economic Analysis'
'Country Level'
'United States of America'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/category_tags.html

async get_related_tags(realtime_start=None, realtime_end=None, tag_names=None, exclude_tag_names=None, tag_group_id=None, search_text=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED related tags

Retrieve related tags for a given set of tags from the FRED API.

Parameters:

realtime_start (str | datetime, optional) – The start of the real-time period. Strinng format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
tag_names (str | list, optional) – A semicolon-delimited list of tag names to include in the search.
exclude_tag_names (str | list, optional) – A semicolon-delimited list of tag names to exclude from the search.
tag_group_id (str, optional) – A tag group ID to filter tags by group.
search_text (str, optional) – The words to match against tag names and descriptions.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Used for pagination.
order_by (str, optional) – Order results by values. Options: ‘series_count’, ‘popularity’, ‘created’, ‘name’, ‘group_id’.
sort_order (str, optional) – Sort order of results. Options: ‘asc’ (ascending), ‘desc’ (descending). Default is ‘asc’.

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_related_tags()
>>>     for tag in tags:
>>>         print(tag.name)
>>> asyncio.run(main())
'nation'
'usa'
'frb'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/related_tags.html

async get_release(release_id, realtime_start=None, realtime_end=None)¶

Get a FRED release

Get the release for a given release ID from the FRED API.

Parameters:

release_id (int) – The ID for the release.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.

Returns:

If multiple releases are returned.

Return type:

List[Release]

Raises:

ValueError – If the request to the FRED API fails or returns an error.

Example

>>> >>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     release = await fred.get_release(53)
>>>     print(release.name)
>>> asyncio.run(main())
'Gross Domestic Product'

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/release.html

async get_release_dates(release_id, realtime_start=None, realtime_end=None, limit=None, offset=None, sort_order=None, include_releases_dates_with_no_data=None)¶

Get FRED release dates

Get the release dates for a given release ID from the FRED API.

Parameters:

release_id (int) – The ID for the release.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return.
offset (int, optional) – The offset for the results.
sort_order (str, optional) – The order of the results. Possible values are ‘asc’ or ‘desc’.
include_releases_dates_with_no_data (bool, optional) – Whether to include release dates with no data.

Returns:

If multiple release dates are returned.

Return type:

List[ReleaseDate]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     release_dates = await fred.get_release_dates(82)
>>>     for release_date in release_dates:
>>>         print(release_date.date)
>>> asyncio.run(main())
'1997-02-10'
'1998-02-10'
'1999-02-04'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/release_dates.html

async get_release_related_tags(release_id, realtime_start=None, realtime_end=None, tag_names=None, exclude_tag_names=None, tag_group_id=None, search_text=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED release related tags

Get release related tags for a given series search text.

Parameters:

series_search_text (str, optional) – The text to match against economic data series.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
tag_names (str | list, optional) – A semicolon delimited list of tag names to match.
exclude_tag_names (str | list, optional) – A semicolon-separated list of tag names to exclude results by.
tag_group_id (str, optional) – A tag group id to filter tags by type.
tag_search_text (str, optional) – The text to match against tags.
limit (int, optional) – The maximum number of results to return.
offset (int, optional) – The offset for the results.
order_by (str, optional) – Order results by values. Options: ‘series_count’, ‘popularity’, ‘created’, ‘name’, ‘group_id’.
sort_order (str, optional) – Sort order of results. Options: ‘asc’, ‘desc’.
release_id (int)
search_text (str | None)

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_release_related_tags('86')
>>>     for tag in tags:
>>>         print(tag.name)
'commercial paper'
'frb'
'nation'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/release_related_tags.html

async get_release_series(release_id, realtime_start=None, realtime_end=None, limit=None, offset=None, sort_order=None, filter_variable=None, filter_value=None, exclude_tag_names=None)¶

Get FRED release series

Get the series in a release.

Parameters:

release_id (int) – The ID for the release.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Default is 0.
sort_order (str, optional) – Order results by values. Options are ‘asc’ or ‘desc’.
filter_variable (str, optional) – The attribute to filter results by.
filter_value (str, optional) – The value of the filter variable.
exclude_tag_names (str | list, optional) – A semicolon-separated list of tag names to exclude.

Returns:

If multiple series are returned.

Return type:

List[Series]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     series = await fred.get_release_series(51)
>>>     for s in series:
>>>         print(s.id)
>>> asyncio.run(main())
'BOMTVLM133S'
'BOMVGMM133S'
'BOMVJMM133S'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/release_series.html

async get_release_sources(release_id, realtime_start=None, realtime_end=None)¶

Get FRED release sources

Retrieve the sources for a specified release from the FRED API.

Parameters:

release_id (int) – The ID of the release for which to retrieve sources.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD. Defaults to None.
realtime_end (str| datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD. Defaults to None.

Returns:

If multiple sources are returned.

Return type:

List[Series]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     sources = await fred.get_release_sources(51)
>>>     for source in sources:
>>>         print(source.name)
>>> asyncio.run(main())
    'U.S. Department of Commerce: Bureau of Economic Analysis'
    'U.S. Department of Commerce: Census Bureau'

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/release_sources.html

async get_release_tables(release_id, element_id=None, include_observation_values=None, observation_date=None)¶

Get FRED release tables

Fetches release tables from the FRED API.

Parameters:

release_id (int) – The ID for the release.
element_id (int, optional) – The ID for the element. Defaults to None.
include_observation_values (bool, optional) – Whether to include observation values. Defaults to None.
observation_date (str | datetime, optional) – The observation date in YYYY-MM-DD string format. Defaults to None.

Returns:

If multiple elements are returned.

Return type:

List[Element]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     elements = await fred.get_release_tables(53)
>>>     for element in elements:
>>>         print(element.series_id)
>>> asyncio.run(main())
'DGDSRL1A225NBEA'
'DDURRL1A225NBEA'
'DNDGRL1A225NBEA'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/release_tables.html

async get_release_tags(release_id, realtime_start=None, realtime_end=None, tag_names=None, tag_group_id=None, search_text=None, limit=None, offset=None, order_by=None)¶

Get FRED release tags

Get the release tags for a given release ID from the FRED API.

Parameters:

release_id (int) – The ID for the release.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
tag_names (str | list, optional) – A semicolon delimited list of tag names.
tag_group_id (int, optional) – The ID for a tag group.
search_text (str, optional) – The words to find matching tags with.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Default is 0.
order_by (str, optional) – Order results by values. Options are ‘series_count’, ‘popularity’, ‘created’, ‘name’, ‘group_id’. Default is ‘series_count’.

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_release_tags(86)
>>>     for tag in tags:
>>>         print(tag.name)
>>> asyncio.run(main())
'commercial paper'
'frb'
'nation'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/release_tags.html

async get_releases(realtime_start=None, realtime_end=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED releases

Get all economic data releases from the FRED API.

Parameters:

realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return. Default is None.
offset (int, optional) – The offset for the results. Default is None.
order_by (str, optional) – Order results by values such as ‘release_id’, ‘name’, ‘press_release’, ‘realtime_start’, ‘realtime_end’. Default is None.
sort_order (str, optional) – Sort results in ‘asc’ (ascending) or ‘desc’ (descending) order. Default is None.

Returns:

If multiple Releases are returned.

Return type:

List[Releases]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     releases = await fred.get_releases()
>>>     for release in releases:
>>>         print(release.name)
>>> asyncio.run(main())
'Advance Monthly Sales for Retail and Food Services'
'Consumer Price Index'
'Employment Cost Index'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/releases.html

async get_releases_dates(realtime_start=None, realtime_end=None, limit=None, offset=None, order_by=None, sort_order=None, include_releases_dates_with_no_data=None)¶

Get FRED releases dates

Get all release dates for economic data releases from the FRED API.

Parameters:

realtime_start (str, optional) – The start of the real-time period. Format: YYYY-MM-DD.
realtime_end (str, optional) – The end of the real-time period. Format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return. Default is None.
offset (int, optional) – The offset for the results. Default is None.
order_by (str, optional) – Order results by values. Options include ‘release_id’, ‘release_name’, ‘release_date’, ‘realtime_start’, ‘realtime_end’. Default is None.
sort_order (str, optional) – Sort order of results. Options include ‘asc’ (ascending) or ‘desc’ (descending). Default is None.
include_releases_dates_with_no_data (bool, optional) – Whether to include release dates with no data. Default is None.

Returns:

If multiple release dates are returned.

Return type:

List[ReleaseDate]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     release_dates = await fred.get_releases_dates()
>>>     for release_date in release_dates:
>>>         print(release_date.release_name)
>>> asyncio.run(main())
'Advance Monthly Sales for Retail and Food Services'
'Failures and Assistance Transactions'
'Manufacturing and Trade Inventories and Sales'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/releases_dates.html

async get_series(series_id, realtime_start=None, realtime_end=None)¶

Get a FRED series

Retrieve economic data series information from the FRED API.

Parameters:

series_id (str) – The ID for the economic data series.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.

Returns:

If multiple series are returned.

Return type:

List[Series]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     series = await fred.get_series('GNPCA')
>>>     print(series.title)
>>> asyncio.run(main())
'Real Gross National Product'

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series.html

async get_series_categories(series_id, realtime_start=None, realtime_end=None)¶

Get FRED series categories

Get the categories for a specified series.

Parameters:

series_id (str) – The ID for the series.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.

Returns:

If multiple categories are returned.

Return type:

List[Category]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     categories = await fred.get_series_categories('EXJPUS')
>>>     for category in categories:
>>>         print(category.id)
>>> asyncio.run(main())
95
275

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_categories.html

async get_series_observations(series_id, dataframe_method='pandas', realtime_start=None, realtime_end=None, limit=None, offset=None, sort_order=None, observation_start=None, observation_end=None, units=None, frequency=None, aggregation_method=None, output_type=None, vintage_dates=None)¶

Get FRED series observations

Get observations for a FRED series as a pandas or polars DataFrame.

Parameters:

series_id (str) – The ID for a series.
dataframe_method (str, optional) – The method to use to convert the response to a DataFrame. Options: ‘pandas’, ‘polars’, or ‘dask’. Default is ‘pandas’.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return. Default is 100000.
offset (int, optional) – The offset for the results. Used for pagination.
sort_order (str, optional) – Sort results by observation date. Options: ‘asc’, ‘desc’.
observation_start (str | datetime, optional) – The start of the observation period. String format: YYYY-MM-DD.
observation_end (str | datetime, optional) – The end of the observation period. String format: YYYY-MM-DD.
units (str, optional) – A key that indicates a data transformation. Options: ‘lin’, ‘chg’, ‘ch1’, ‘pch’, ‘pc1’, ‘pca’, ‘cch’, ‘cca’, ‘log’.
frequency (str, optional) – An optional parameter to change the frequency of the observations. Options: ‘d’, ‘w’, ‘bw’, ‘m’, ‘q’, ‘sa’, ‘a’, ‘wef’, ‘weth’, ‘wew’, ‘wetu’, ‘wem’, ‘wesu’, ‘wesa’, ‘bwew’, ‘bwem’.
aggregation_method (str, optional) – A key that indicates the aggregation method used for frequency aggregation. Options: ‘avg’, ‘sum’, ‘eop’.
output_type (int, optional) – An integer indicating the type of output. Options: 1 (observations by realtime period), 2 (observations by vintage date, all observations), 3 (observations by vintage date, new and revised observations only), 4 (observations by initial release only).
vintage_dates (str | list, optional) – A comma-separated string of vintage dates. String format: YYYY-MM-DD.

Returns:

If dataframe_method=’pandas’ or is left blank. Polars DataFrame: If dataframe_method=’polars’. Dask DataFrame: If dataframe_method=’dask’.

Return type:

Pandas DataFrame

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     observations = fred.get_series_observations('GNPCA')
>>>     print(observations.head())
>>> asyncio.run(main())
date       realtime_start realtime_end     value
1929-01-01     2025-02-13   2025-02-13  1202.659
1930-01-01     2025-02-13   2025-02-13  1100.670
1931-01-01     2025-02-13   2025-02-13  1029.038
1932-01-01     2025-02-13   2025-02-13   895.802
1933-01-01     2025-02-13   2025-02-13   883.847

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_observations.html

async get_series_release(series_id, realtime_start=None, realtime_end=None)¶

Get FRED series release

Get the release for a specified series from the FRED API.

Parameters:

series_id (str) – The ID for the series.
realtime_start (str, optional) – The start of the real-time period. Format: YYYY-MM-DD. Defaults to None.
realtime_end (str, optional) – The end of the real-time period. Format: YYYY-MM-DD. Defaults to None.

Returns:

If multiple releases are returned.

Return type:

List[Release]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     release = await fred.get_series_release('GNPCA')
>>>     print(release.name)
>>> asyncio.run(main())
'Gross National Product'

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_release.html

async get_series_search(search_text, search_type=None, realtime_start=None, realtime_end=None, limit=None, offset=None, order_by=None, sort_order=None, filter_variable=None, filter_value=None, tag_names=None, exclude_tag_names=None)¶

Get FRED series search

Searches for economic data series based on text queries.

Parameters:

search_text (str) – The text to search for in economic data series. if ‘search_type’=’series_id’, it’s possible to put an ‘*’ in the middle of a string. ‘m*sl’ finds any series starting with ‘m’ and ending with ‘sl’.
search_type (str, optional) – The type of search to perform. Options include ‘full_text’ or ‘series_id’. Defaults to None.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD. Defaults to None.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD. Defaults to None.
limit (int, optional) – The maximum number of results to return. Defaults to None.
offset (int, optional) – The offset for the results. Defaults to None.
order_by (str, optional) – The attribute to order results by. Options include ‘search_rank’, ‘series_id’, ‘title’, etc. Defaults to None.
sort_order (str, optional) – The order to sort results. Options include ‘asc’ or ‘desc’. Defaults to None.
filter_variable (str, optional) – The variable to filter results by. Defaults to None.
filter_value (str, optional) – The value to filter results by. Defaults to None.
tag_names (str | list, optional) – A comma-separated list of tag names to include in the search. Defaults to None.
exclude_tag_names (str | list, optional) – A comma-separated list of tag names to exclude from the search. Defaults to None.

Returns:

If multiple series are returned.

Return type:

List[Series]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     series = await fred.get_series_search('monetary services index')
>>>     for s in series:
>>>         print(s.id)
>>> asyncio.run(main())
'MSIM2'
'MSIM1P'
'OCM1P'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_search.html

async get_series_search_related_tags(series_search_text, realtime_start=None, realtime_end=None, tag_names=None, exclude_tag_names=None, tag_group_id=None, tag_search_text=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED series search related tags

Get related tags for a series search text.

Parameters:

series_search_text (str) – The text to search for series.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
tag_names (str | list, optional) – A semicolon-delimited list of tag names to include.
exclude_tag_names (str | list, optional) – A semicolon-delimited list of tag names to exclude.
tag_group_id (str, optional) – The tag group id to filter tags by type.
tag_search_text (str, optional) – The text to search for tags.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Used for pagination.
order_by (str, optional) – Order results by values. Options are ‘series_count’, ‘popularity’, ‘created’, ‘name’, ‘group_id’.
sort_order (str, optional) – Sort order of results. Options are ‘asc’ (ascending) or ‘desc’ (descending).

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_series_search_related_tags('mortgage rate')
>>>     for tag in tags:
>>>         print(tag.name)
>>> asyncio.run(main())
'conventional'
'h15'
'interest rate'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_search_related_tags.html

async get_series_search_tags(series_search_text, realtime_start=None, realtime_end=None, tag_names=None, tag_group_id=None, tag_search_text=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED series search tags

Get the tags for a series search.

Parameters:

series_search_text (str) – The words to match against economic data series.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
tag_names (str | list, optional) – A semicolon-delimited list of tag names to match.
tag_group_id (str, optional) – A tag group id to filter tags by type.
tag_search_text (str, optional) – The words to match against tags.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Default is 0.
order_by (str, optional) – Order results by values of the specified attribute. Options are ‘series_count’, ‘popularity’, ‘created’, ‘name’, ‘group_id’.
sort_order (str, optional) – Sort results in ascending or descending order. Options are ‘asc’ or ‘desc’. Default is ‘asc’.

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_series_search_tags('monetary services index')
>>>     for tag in tags:
>>>         print(tag.name)
>>> asyncio.run(main())
'academic data'
'anderson & jones'
'divisia'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_search_tags.html

async get_series_tags(series_id, realtime_start=None, realtime_end=None, order_by=None, sort_order=None)¶

Get FRED series tags

Get the tags for a series.

Parameters:

series_id (str) – The ID for a series.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
order_by (str, optional) – Order results by values such as ‘series_id’, ‘name’, ‘popularity’, etc.
sort_order (str, optional) – Sort results in ‘asc’ (ascending) or ‘desc’ (descending) order.

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_series_tags('GNPCA')
>>>     for tag in tags:
>>>         print(tag.name)
>>> asyncio.run(main())
'nation'
'nsa'
'usa'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_tags.html

async get_series_updates(realtime_start=None, realtime_end=None, limit=None, offset=None, filter_value=None, start_time=None, end_time=None)¶

Get FRED series updates

Retrieves updates for a series from the FRED API.

Parameters:

realtime_start (str |, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Used for pagination.
filter_value (str, optional) – Filter results by this value.
start_time (str, optional) – The start time for the updates. Format: HH:MM.
end_time (str, optional) – The end time for the updates. Format: HH:MM.

Returns:

If multiple series are returned.

Return type:

List[Series]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     series = await fred.get_series_updates()
>>>     for s in series:
>>>         print(s.id)
>>> asyncio.run(main())
'PPIITM'
'PPILFE'
'PPIFGS'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_updates.html

async get_series_vintagedates(series_id, realtime_start=None, realtime_end=None, limit=None, offset=None, sort_order=None)¶

Get FRED series vintage dates

Get the vintage dates for a given FRED series.

Parameters:

series_id (str) – The ID for the FRED series.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return.
offset (int, optional) – The offset for the results.
sort_order (str, optional) – The order of the results. Possible values: ‘asc’ or ‘desc’.

Returns:

If multiple vintage dates are returned.

Return type:

List[VintageDate]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     vintage_dates = await fred.get_series_vintagedates('GNPCA')
>>>     for vintage_date in vintage_dates:
>>>         print(vintage_date.vintage_date)
>>> asyncio.run(main())
'1958-12-21'
'1959-02-19'
'1959-07-19'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/series_vintagedates.html

async get_source(source_id, realtime_start=None, realtime_end=None)¶

Get a FRED source

Retrieves information about a source from the FRED API.

Parameters:

source_id (int) – The ID for the source.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD. Defaults to None.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD. Defaults to None.

Returns:

If multiple sources are returned.

Return type:

List[Source]

Raises:

ValueError – If the request to the FRED API fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     source = await fred.get_source(1)
>>>     print(source.name)
>>> asyncio.run(main())
'Board of Governors of the Federal Reserve System'

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/source.html

async get_source_releases(source_id, realtime_start=None, realtime_end=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED source releases

Get the releases for a specified source from the FRED API.

Parameters:

source_id (int) – The ID for the source.
realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return.
offset (int, optional) – The offset for the results.
order_by (str, optional) – Order results by values such as ‘release_id’, ‘name’, etc.
sort_order (str, optional) – Sort order of results. ‘asc’ for ascending, ‘desc’ for descending.

Returns:

If multiple Releases are returned.

Return type:

List[Releases]

Raises:

ValueError – If the request to the FRED API fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key')
>>>     releases = await fred.get_source_releases(1)
>>>     for release in releases:
>>>         print(release.name)
>>> asyncio.run(main())
'G.17 Industrial Production and Capacity Utilization'
'G.19 Consumer Credit'
'G.5 Foreign Exchange Rates'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/source_releases.html

async get_sources(realtime_start=None, realtime_end=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED sources

Retrieve sources of economic data from the FRED API.

Parameters:

realtime_start (str, optional) – The start of the real-time period. Format: YYYY-MM-DD.
realtime_end (str, optional) – The end of the real-time period. Format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return. Default is 1000, maximum is 1000.
offset (int, optional) – The offset for the results. Used for pagination.
order_by (str, optional) – Order results by values. Options are ‘source_id’, ‘name’, ‘realtime_start’, ‘realtime_end’.
sort_order (str, optional) – Sort order of results. Options are ‘asc’ (ascending) or ‘desc’ (descending).
file_type (str, optional) – The format of the returned data. Default is ‘json’. Options are ‘json’, ‘xml’.

Returns:

If multiple sources are returned.

Return type:

List[Source]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     sources = await fred.get_sources()
>>>     for source in sources:
>>>         print(source.name)
>>> asyncio.run(main())
'Board of Governors of the Federal Reserve System'
'Federal Reserve Bank of Philadelphia'
'Federal Reserve Bank of St. Louis'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/sources.html

async get_tags(realtime_start=None, realtime_end=None, tag_names=None, tag_group_id=None, search_text=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED tags

Retrieve FRED tags based on specified parameters.

Parameters:

realtime_start (str | datetime, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str | datetime, optional) – The end of the real-time period. String format: YYYY-MM-DD.
tag_names (str | list, optional) – A semicolon-delimited list of tag names to filter results.
tag_group_id (str, optional) – A tag group ID to filter results.
search_text (str, optional) – The words to match against tag names and descriptions.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Used for pagination.
order_by (str, optional) – Order results by values such as ‘series_count’, ‘popularity’, etc.
sort_order (str, optional) – Sort order of results. ‘asc’ for ascending, ‘desc’ for descending.

Returns:

If multiple tags are returned.

Return type:

List[Tag]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     tags = await fred.get_tags()
>>>     for tag in tags:
>>>         print(tag.name)
>>> asyncio.run(main())
'nation'
'nsa'
'oecd'...

FRED API Documentation:: https://fred.stlouisfed.org/docs/api/fred/tags.html

async get_tags_series(tag_names=None, exclude_tag_names=None, realtime_start=None, realtime_end=None, limit=None, offset=None, order_by=None, sort_order=None)¶

Get FRED tags series

Get the series matching tags.

Parameters:

tag_names (str, optional) – A semicolon delimited list of tag names to include in the search.
exclude_tag_names (str, optional) – A semicolon delimited list of tag names to exclude in the search.
realtime_start (str, optional) – The start of the real-time period. String format: YYYY-MM-DD.
realtime_end (str, optional) – The end of the real-time period. String format: YYYY-MM-DD.
limit (int, optional) – The maximum number of results to return. Default is 1000.
offset (int, optional) – The offset for the results. Default is 0.
order_by (str, optional) – Order results by values. Options: ‘series_id’, ‘title’, ‘units’, ‘frequency’, ‘seasonal_adjustment’, ‘realtime_start’, ‘realtime_end’, ‘last_updated’, ‘observation_start’, ‘observation_end’, ‘popularity’, ‘group_popularity’.
sort_order (str, optional) – Sort results in ascending or descending order. Options: ‘asc’, ‘desc’.

Returns:

If multiple series are returned.

Return type:

List[Series]

Raises:

ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredAPI('your_api_key').Async
>>>     series = await fred.get_tags_series('slovenia')
>>>     for s in series:
>>>         print(s.id)
>>> asyncio.run(main())
'CPGDFD02SIA657N'
'CPGDFD02SIA659N'
'CPGDFD02SIM657N'...

FRED API Documentation: https://fred.stlouisfed.org/docs/api/fred/tags_series.html