AsyncMapsAPI Class¶

class fedfred.FredAPI.AsyncAPI.AsyncMapsAPI(parent)¶

Bases: object

The Async.Maps sub-class contains async methods for interacting with the FRED® Maps API and GeoFRED endpoints.

Parameters:: parent (FredAPI.AsyncAPI)

async get_regional_data(series_group, region_type, date, season, units, geodataframe_method='geopandas', start_date=None, transformation=None, frequency=None, aggregation_method=None)¶

Get GeoFRED regional data

Retrieve regional data for a specified series group and date from the FRED Maps API.

Parameters:

series_group (str) – The series group for which you want to request regional data.
region_type (str) – The type of region for which you want to request data. Options are ‘bea’, ‘msa’, ‘frb’, ‘necta’, ‘state’, ‘country’, ‘county’, ‘censusregion’, or ‘censusdivision’.
date (str | datetime) – The date for which you want to request regional data. String format: YYYY-MM-DD.
season (str) – The seasonality of the data. Options include ‘seasonally_adjusted’ or ‘not_seasonally_adjusted’.
units (str) – The units of the data. Options are ‘lin’, ‘chg’, ‘ch1’, ‘pch’, ‘pc1’, ‘pca’, ‘cch’, ‘cca’ and ‘log’.
geodataframe_method (str, optional) – The method to use for creating the GeoDataFrame. Options are ‘geopandas’, ‘dask’ or ‘polars’. Default is ‘geopandas’.
start_date (str, optional) – The start date for the range of data you want to request. Format: YYYY-MM-DD.
transformation (str, optional) – The data transformation to apply. Options are ‘lin’, ‘chg’, ‘ch1’, ‘pch’, ‘pc1’, ‘pca’, ‘cch’, ‘cca’, and ‘log’.
frequency (str, optional) – The frequency of the data. Options are ‘d’, ‘w’, ‘bw’, ‘m’, ‘q’, ‘sa’, ‘a’, ‘wef’, ‘weth’, ‘wew’, ‘wetu’, ‘wem’, ‘wesu’, ‘wesa’, ‘bwew’and ‘bwem’.
aggregation_method (str, optional) – The aggregation method to use. Options are ‘avg’, ‘sum’, and ‘eop’.

Returns:

If geodataframe_method is ‘geopandas’. Dask GeoPandas GeoDataframe: If geodataframe_method is ‘dask’. Polars GeoDataframe: If geodataframe_method is ‘polars’.

Return type:

GeoPandas GeoDataframe

Raises:

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

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredMapsAPI('your_api_key').Async.Maps
>>>     regional_data = fred.get_regional_data(series_group='882', date='2013-01-01', region_type='state', units='Dollars', frequency='a', season='NSA')
>>>     print(regional_data.head())
>>> asyncio.run(main())
name                                                    geometry hc-group  ...  value  series_id
Massachusetts  MULTIPOLYGON (((9727 7650, 10595 7650, 10595 7...   admin1  ...  56119     MAPCPI
Washington     MULTIPOLYGON (((-77 9797, -56 9768, -91 9757, ...   admin1  ...  47448     WAPCPI
California     POLYGON ((-833 8186, -50 7955, -253 7203, 32 6...   admin1  ...  48074     CAPCPI
Oregon         POLYGON ((-50 7955, -833 8186, -851 8223, -847...   admin1  ...  39462     ORPCPI
Wisconsin      MULTIPOLYGON (((6206 8297, 6197 8237, 6159 815...   admin1  ...  42685     WIPCPI
[5 rows x 21 columns]

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

async get_series_data(series_id, geodataframe_method='geopandas', date=None, start_date=None)¶

Get GeoFRED series data

This request returns a cross section of regional data for a specified release date. If no date is specified, the most recent data available are returned.

Parameters:

series_id (string, required) – The FRED series_id you want to request maps data for. Not all series that are in FRED have geographical data.
geodataframe_method (str, optional) – The method to use for creating the GeoDataFrame. Options are ‘geopandas’ ‘polars’, or ‘dask’. Default is ‘geopandas’.
date (string | datetime, optional) – The date you want to request series group data from. String format: YYYY-MM-DD
start_date (string | datetime, optional) – The start date you want to request series group data from. This allows you to pull a range of data. String format: YYYY-MM-DD

Returns:

If geodataframe_method is ‘geopandas’. Dask GeoPandas GeoDataframe: If geodataframe_method is ‘dask’. Polars GeoDataframe: If geodataframe_method is ‘polars’.

Return type:

GeoPandas GeoDataframe

Raises:

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

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredMapsAPI('your_api_key').Async.Maps
>>>     series_data = fred.get_series_data('SMU56000000500000001')
>>>     print(series_data.head())
>>> asyncio.run(main())
name                                                    geometry  ...             series_id
Washington     MULTIPOLYGON (((-77 9797, -56 9768, -91 9757, ...  ...  SMU53000000500000001
California     POLYGON ((-833 8186, -50 7955, -253 7203, 32 6...  ...  SMU06000000500000001
Oregon         POLYGON ((-50 7955, -833 8186, -851 8223, -847...  ...  SMU41000000500000001
Wisconsin      MULTIPOLYGON (((6206 8297, 6197 8237, 6159 815...  ...  SMU55000000500000001

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

async get_series_group(series_id)¶

Get a GeoFRED series group

This request returns the meta information needed to make requests for FRED data. Minimum and maximum date are also supplied for the data range available.

Parameters:: series_id (str, required) – The FRED series id you want to request maps meta information for. Not all series that are in FRED have geographical data.
Returns:: If multiple series groups are returned.
Return type:: List[SeriesGroup]
Raises:: ValueError – If the API request fails or returns an error.

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredMapsAPI('your_api_key').Async.Maps
>>>     series_group = await fred.get_series_group('SMU56000000500000001')
>>>     print(series_group)
>>> asyncio.run(main())
'State Personal Income'

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

async get_shape_files(shape, geodataframe_method='geopandas')¶

Get GeoFRED shape files

This request returns shape files from FRED in GeoJSON format.

Parameters:

shape (str, required) – The type of shape you want to pull GeoJSON data for. Available Shape Types: ‘bea’ (Bureau of Economic Anaylis Region), ‘msa’ (Metropolitan Statistical Area), ‘frb’ (Federal Reserve Bank Districts), ‘necta’ (New England City and Town Area), ‘state’, ‘country’, ‘county’ (USA Counties), ‘censusregion’ (US Census Regions), ‘censusdivision’ (US Census Divisons).
geodataframe_method (str, optional) – The method to use for creating the GeoDataFrame. Options are ‘geopandas’, ‘dask’ or ‘polars’. Default is ‘geopandas’.

Returns:

If dataframe_method is ‘geopandas’. Dask GeoPandas GeoDataframe: If dataframe_method is ‘dask’. Polars GeoDataframe: If dataframe_method is ‘polars’.

Return type:

GeoPandas GeoDataframe

Raises:

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

Example

>>> import fedfred as fd
>>> import asyncio
>>> async def main():
>>>     fred = fd.FredMapsAPI('your_api_key').Async.Maps
>>>     shapefile = fred.get_shape_files('state')
>>>     print(shapefile.head())
>>> asyncio.run(main())
                                            geometry  ...   type
0  MULTIPOLYGON (((9727 7650, 10595 7650, 10595 7...  ...  State
1  MULTIPOLYGON (((-77 9797, -56 9768, -91 9757, ...  ...  State
2  POLYGON ((-833 8186, -50 7955, -253 7203, 32 6...  ...  State
3  POLYGON ((-50 7955, -833 8186, -851 8223, -847...  ...  State
4  MULTIPOLYGON (((6206 8297, 6197 8237, 6159 815...  ...  State
[5 rows x 20 columns]

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