maps module

The maps module provides functions to request data from the FRED API Maps endpoints.

The FRED Maps API is a web service that allows developers to write programs and build applications to harvest data and shape files of series available on the maps found in the FRED website hosted by the Economic Research Division of the Federal Reserve Bank of St. Louis. Not all series that are in FRED have geographical data.

GeoseriesData

Bases: BaseModel

Represents metadata about an economics data series. Endpoint documentation.

GeoseriesInfo

Bases: BaseModel

Represents geo series information. Endpoint documentation.

MapApiParameters

Bases: BaseModel

Represents the parameters accepted by the FRED Maps endpoints.

get_geoseries

get_geoseries(series_id: str, api_key: ApiKeyType = None, start_date: Optional[str] = None, end_date: Optional[str] = None, return_format: ReturnFormats = 'pandas') -> GeoseriesData

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

For example, you can request Per Capita Personal Income by State (series_id: WIPCPI) over a specific time period. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest. Not all series that are in FRED have geographical data.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None
start_date	str	Define start date. YYYY-MM-DD formatted string.	None
end_date	str	Define the end date. YYYY-MM-DD formatted string.	None
return_format	Literal[json, pandas] | ReturnFormat	Define how to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.	'pandas'

Returns:

Type	Description
GeoseriesData	GeoseriesData object containing the geoseries data and metadata.

get_geoseries_info

get_geoseries_info(series_id: str, api_key: ApiKeyType = None) -> GeoseriesInfo

Request the metadata for a given geo series id. Endpoint documentation.

Parameters:

Name	Type	Description	Default
series_id	str	Series id of interest.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None

Returns:

Type	Description
GeoseriesInfo	An instance of GeoseriesInfo.

get_shape_files

get_shape_files(shape: Literal['bea', 'msa', 'frb', 'necta', 'state', 'country', 'county', 'censusregion', 'censusdivision'], api_key: ApiKeyType = None) -> JsonType

Request shape files from FRED in Well-known text (WKT) format.

Parameters:

Name	Type	Description	Default
shape	One of "bea", "msa", "frb", "necta", "state", "country", "county", "censusregion", "censusdivision"	Define the shape of Well-known text (WKT) data.	required
api_key	str | None	FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.	None

Returns:

Type	Description
dict	Dictionary representing the json response.