### Install Development Dependencies

Source: https://pyfredapi.readthedocs.io/en/latest/references/CONTRIBUTING

Install the package along with its development dependencies.

```bash
pip install '.[dev]'
```

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

### Install pyfredapi

Source: https://pyfredapi.readthedocs.io/en/latest

Install the library using pip, optionally including plotting dependencies.

```bash
pip install pyfredapi

# install with plotting dependencies
pip install 'pyfredapi[plot]'
```

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

### Setup pyfredapi

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/releases

Initialize the library and import necessary tools for pretty printing.

```python
from rich.pretty import pprint

import pyfredapi as pf
```

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

### Setup Environment

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/maps

Import necessary libraries for data manipulation, visualization, and API interaction.

```python
import geopandas as gpd
import matplotlib.pyplot as plt
from rich import print

import pyfredapi as pf
```

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

### Install Pre-commit Hooks

Source: https://pyfredapi.readthedocs.io/en/latest/references/CONTRIBUTING

Set up pre-commit to ensure code quality standards are met before commits.

```bash
pre-commit install
```

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

### GET /releases

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Retrieves all releases of economic data.

```APIDOC
## GET /releases

### Description
Get all releases of economic data.

### Method
GET

### Parameters
#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API releases/ endpoint.

### Response
#### Success Response (200)
- **response** (Dictionary) - Dictionary representing the Json response.
```

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

### GET /series/observation (initial release)

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Get the observations or data values for the initial release of an economic data series. Includes only the initial release of the series and excludes all revisions.

```APIDOC
## GET /series/observation (initial release)

### Description
Get the observations or data values for the initial release of an economic data series. Includes only the the initial release of the series and excludes all revisions.

### Method
GET

### Endpoint
/series/observation

### Parameters
#### Query Parameters
- **series_id** (str) - Required - Series id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **return_format** (Literal['json', 'pandas', 'polars']) - Optional - In what format to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `series/observation` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Response
#### Success Response (200)
- **dict | DataFrame | DataFrame** - Description not specified in source.
```

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

### GET /release/tables

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Retrieves release table trees for a given release.

```APIDOC
## GET /release/tables

### Description
Get release table trees for a given release.

### Method
GET

### Parameters
#### Query Parameters
- **release_id** (int) - Required - Release id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API release/tables/ endpoint.

### Response
#### Success Response (200)
- **response** (Dictionary) - Dictionary representing the Json response.
```

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

### GET /release/sources

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Retrieves the sources for a specific economic data release.

```APIDOC
## GET /release/sources

### Description
Get the sources for a release of economic data.

### Method
GET

### Parameters
#### Query Parameters
- **release_id** (int) - Required - Release id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API release/sources/ endpoint.

### Response
#### Success Response (200)
- **response** (Dictionary) - Dictionary representing the Json response.
```

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

### GET /release/tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Retrieves the FRED tags for a specific release.

```APIDOC
## GET /release/tags

### Description
Get the FRED tags for a release.

### Method
GET

### Parameters
#### Query Parameters
- **release_id** (int) - Required - Release id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API release/tags/ endpoint.

### Response
#### Success Response (200)
- **response** (Dictionary) - Dictionary representing the Json response.
```

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

### GET /series/releases

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Get the FRED release for an economic data series by ID.

```APIDOC
## GET /series/releases

### Description
Get the FRED release for an economic data series by ID.

### Method
GET

### Endpoint
/series/releases

### Parameters
#### Query Parameters
- **series_id** (str) - Required - Series id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `series/releases` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Response
#### Success Response (200)
- **dict** - Dictionary representing the json response.
```

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

### Run Project Tests

Source: https://pyfredapi.readthedocs.io/en/latest/references/CONTRIBUTING

Execute the test suite using either pytest or tox to verify the environment setup.

```bash
pytest tests/
```

```bash
tox
```

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

### GET /series

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Get an economic data series information by ID.

```APIDOC
## GET /series

### Description
Get an economic data series information by ID.

### Method
GET

### Endpoint
/series

### Parameters
#### Query Parameters
- **series_id** (str) - Required - Series id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `series/` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Response
#### Success Response (200)
- **SeriesInfo** - An instance of SeriesInfo.
```

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

### GET /releases/dates

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Retrieves release dates for all releases of economic data.

```APIDOC
## GET /releases/dates

### Description
Get release dates for all releases of economic data.

### Method
GET

### Parameters
#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API releases/dates endpoint.

### Response
#### Success Response (200)
- **response** (Dictionary) - Dictionary representing the Json response.
```

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

### Get All Sources

Source: https://pyfredapi.readthedocs.io/en/latest/references/sources

Retrieves a comprehensive list of all available economic data sources from the FRED API.

```APIDOC
## GET /fred/sources

### Description
Get all sources of economic data.

### Method
GET

### Endpoint
/fred/sources

### Parameters
#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `sources/` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Response
#### Success Response (200)
- **Dictionary representing the Json response**

### Request Example
```json
{
  "api_key": "YOUR_API_KEY",
  "other_param": "value"
}
```

### Response Example
```json
{
  "type": "object",
  "properties": {
    "sources": {
      "type": "array",
      "items": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}}}
    }
  }
}
```
```

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

### GET /series/observation (as of date)

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Get the observations or data values for an economic data series made on or before a specific date. Retrieves the latest data known for the series as of the date provided.

```APIDOC
## GET /series/observation (as of date)

### Description
Get the observations or data values for an economic data series made on or before a specific date. Retrieves the latest data known for the series as of the date provided. This includes any revisions to the data series made before or on the date, but excludes any revisions made after the date.

### Method
GET

### Endpoint
/series/observation

### Parameters
#### Query Parameters
- **series_id** (str) - Required - Series id of interest.
- **date** (str) - Required - Include only data revisions made on or before this date.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **return_format** (Literal['json', 'pandas']) - Optional - In what format to return the response. Must be either 'json' or 'pandas'. Defaults to 'pandas'.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `series/observation` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Response
#### Success Response (200)
- **dict | DataFrame | DataFrame** - Description not specified in source.
```

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

### Quick Start Data Retrieval

Source: https://pyfredapi.readthedocs.io/en/latest

Retrieve series information using either an environment variable or by passing the API key directly to the function.

```python
import pyfreadpi as pf

# api key set as environment variable
pf.get_series_info(series_id="GDP")

# api key passed to function
pf.get_series_info(series_id="GDP", api_key="my_api_key")
```

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

### GET /series/categories

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Get the categories for an economic data series by ID.

```APIDOC
## GET /series/categories

### Description
Get the categories for an economic data series by ID.

### Method
GET

### Endpoint
/series/categories

### Parameters
#### Query Parameters
- **series_id** (str) - Required - Series id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `series/categories` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Response
#### Success Response (200)
- **dict** - Dictionary representing the json response.
```

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

### GET get_release

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Fetches a specific release of economic data by its ID.

```APIDOC
## GET get_release

### Description
Get a release of economic data.

### Parameters
#### Path Parameters
- **release_id** (int) - Required - Release id of interest.

#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API release/ endpoint.

### Response
#### Success Response (200)
- **response** (dict) - Dictionary representing the Json response.
```

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

### Get and Process Shape Files

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/maps

Retrieve shape files and merge them with regional data for mapping.

```python
state_shapes_files = pf.get_shape_files(shape="state")
```

```python
pf.get_shape_files(shape="state")
```

```python
state_shapes_files
```

```python
state_gdf = gpd.GeoDataFrame.from_features(state_shapes_files["features"])
```

```python
joined_df = state_gdf[["geometry", "state_fips"]].merge(
    per_capita_personal_income_by_state_df,
    left_on=["state_fips"],
    right_on=["code"],
)
```

```python
joined_df.date.max()
```

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

### GET get_release_dates

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Fetches release dates for a specific release of economic data.

```APIDOC
## GET get_release_dates

### Description
Get release dates for a release of economic data.

### Parameters
#### Path Parameters
- **release_id** (int) - Required - Release id of interest.

#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API release/dates/ endpoint.

### Response
#### Success Response (200)
- **response** (dict) - Dictionary representing the Json response.
```

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

### GET get_category

Source: https://pyfredapi.readthedocs.io/en/latest/references/category

Retrieves a specific category by its ID.

```APIDOC
## GET get_category

### Description
Get category by ID.

### Parameters
#### Query Parameters
- **category_id** (str | None) - Optional - Category id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (KwargsType) - Optional - Additional parameters to FRED API category/ endpoint.

### Response
#### Success Response (200)
- **dict** - Dictionary representing the json response.
```

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

### GET get_release_series

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Fetches the series associated with a specific release of economic data.

```APIDOC
## GET get_release_series

### Description
Get the series on a release of economic data.

### Parameters
#### Path Parameters
- **release_id** (int) - Required - Release id of interest.

#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API release/release_series/ endpoint.

### Response
#### Success Response (200)
- **response** (dict) - Dictionary representing the Json response.
```

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

### Get Source Releases

Source: https://pyfredapi.readthedocs.io/en/latest/references/sources

Retrieves a list of economic data releases associated with a specific source.

```APIDOC
## GET /fred/source/releases

### Description
Get the releases for a source.

### Method
GET

### Endpoint
/fred/source/releases

### Parameters
#### Query Parameters
- **source_id** (int) - Required - Source id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `source/releases` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Response
#### Success Response (200)
- **Dictionary representing the Json response**

### Request Example
```json
{
  "source_id": 1,
  "api_key": "YOUR_API_KEY",
  "other_param": "value"
}
```

### Response Example
```json
{
  "type": "object",
  "properties": {
    "releases": {
      "type": "array",
      "items": {"type": "object", "properties": {"id": {"type": "integer"}, "name": {"type": "string"}}}
    }
  }
}
```
```

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

### GET get_category_tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/category

Retrieves FRED tags for a category by category ID.

```APIDOC
## GET get_category_tags

### Description
Get the FRED tags for a category by category ID.

### Parameters
#### Query Parameters
- **category_id** (str | None) - Optional - Category id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **return_format** (str | ReturnFormat) - Optional - Define how to return the response. Must be either 'json' or 'pandas'.
- **kwargs** (dict) - Optional - Additional parameters to FRED API category/children endpoint.

### Response
- **dict | DataFrame** - Returns the tags in the specified format.
```

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

### GET /series/search

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Searches for economic data series that match the provided search text.

```APIDOC
## GET /series/search

### Description
Get economic data series that match search text.

### Parameters
#### Query Parameters
- **search_text** (str) - Required - The text to match against.
- **api_key** (str | None) - Optional - FRED API key.
- **search_type** (Literal['full_text', 'series_id']) - Optional - Defines which type of search to perform. Defaults to 'full_text'.
- **return_format** (Literal['json', 'pandas', 'polars']) - Optional - Format of the response. Defaults to 'pandas'.
- **kwargs** (dict) - Optional - Additional parameters to FRED API series/observation endpoint.
```

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

### Get Geo-series Information

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/maps

Retrieve metadata for a specific series ID.

```python
info = pf.get_geoseries_info(series_id="WIPCPI")
print(info)
```

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

### Get Source Details

Source: https://pyfredapi.readthedocs.io/en/latest/references/sources

Retrieves detailed information about a specific economic data source using its ID.

```APIDOC
## GET /fred/source

### Description
Get a source of economic data.

### Method
GET

### Endpoint
/fred/source

### Parameters
#### Query Parameters
- **source_id** (int) - Required - Source id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `source/` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Response
#### Success Response (200)
- **Dictionary representing the Json response**

### Request Example
```json
{
  "source_id": 1,
  "api_key": "YOUR_API_KEY",
  "other_param": "value"
}
```

### Response Example
```json
{
  "type": "object",
  "properties": {
    "source": {
      "type": "object",
      "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string"},
        "link": {"type": "string"}
      }
    }
  }
}
```
```

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

### Pass additional parameters to the FRED API

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

Uses keyword arguments to pass extra parameters like observation start and end dates to the API.

```python
extra_parameters = {
    "observation_start": "2020-01-01",
    "observation_end": "2020-12-31",
}

gdp_df = pf.get_series(series_id="GDP", **extra_parameters)
```

```python
gdp_df
```

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

### GET /series/tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Retrieves the FRED tags for a specific economic data series by its ID.

```APIDOC
## GET /series/tags

### Description
Get the FRED tags for an economic data series by ID.

### Parameters
#### Query Parameters
- **series_id** (str) - Required - Series id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API series/tags endpoint.
```

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

### GET get_release_related_tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Fetches related FRED tags for one or more tags within a release.

```APIDOC
## GET get_release_related_tags

### Description
Get the related FRED tags for one or more FRED tags within a release.

### Parameters
#### Path Parameters
- **release_id** (int) - Required - Release id of interest.
- **tag_names** (str) - Required - A semicolon delimited list of tag names.

#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API release/related_tags/ endpoint.

### Response
#### Success Response (200)
- **response** (dict) - Dictionary representing the Json response.
```

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

### Get Series Data as JSON

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

Fetch series data and specify return_format='json' to receive the data as a list of dictionaries, which can be useful for further JSON processing.

```python
gdp_json = pf.get_series(series_id="GDP", return_format="json")
```

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

### SeriesCollection Metadata Listing Methods

Source: https://pyfredapi.readthedocs.io/en/latest/references/series_collection

Provides methods to list metadata for all series within the collection, including start date, end date, frequency, seasonality, measurement units, and series IDs with their titles.

```APIDOC
### list_end_date
```python
list_end_date() -> None
```

List the series' latest date.

### list_frequency
```python
list_frequency() -> None
```

List the series' frequency.

### list_seasonality
```python
list_seasonality() -> None
```

List the series' seasonality.

### list_series
```python
list_series() -> None
```

List the series' id and title.

### list_start_date
```python
list_start_date() -> None
```

List the series' earliest date.

### list_units
```python
list_units() -> None
```

List the series' measurement units.
```

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

### GET /series/updates

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Retrieves the FRED updates for a specific economic data series by its ID.

```APIDOC
## GET /series/updates

### Description
Get the FRED updates for an economic data series by ID.

### Parameters
#### Query Parameters
- **series_id** (str) - Required - Series id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API series/updates endpoint.
```

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

### GET get_category_series

Source: https://pyfredapi.readthedocs.io/en/latest/references/category

Retrieves series information for each series within a specified category ID.

```APIDOC
## GET get_category_series

### Description
Get the series info for each series in a category by category ID.

### Parameters
#### Path Parameters
- **category_id** (str) - Required - Category id of interest.

#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API category/children endpoint.

### Response
- **dict** - A dictionary where the keys are series ids and the values for SeriesInfo objects.
```

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

### Tags API - Get Tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/tags

Retrieves a list of all FRED tags. This function corresponds to the FRED API's tags/ endpoint.

```APIDOC
## GET /fred/tags

### Description
Get FRED tags.

### Method
GET

### Endpoint
/fred/tags

### Parameters
#### Query Parameters
- **api_key** (str) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `tags/` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Request Example
```json
{
  "api_key": "YOUR_API_KEY"
}
```

### Response
#### Success Response (200)
- **response** (dict) - A dictionary representing the json response.

#### Response Example
```json
{
  "tags": [
    {
      "id": "gdp",
      "name": "Gross Domestic Product",
      "units": {
        "id": "4",
        "name": "Billions of Dollars",
        "short": "$"
      },
      "series_count": 100
    }
  ]
}
```
```

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

### Tags API - Get Series Matching Tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/tags

Retrieves series that match all specified tag names. This function corresponds to the FRED API's tags/series endpoint.

```APIDOC
## GET /fred/tags/series

### Description
Get the series matching all tags in the tag_names parameter.

### Method
GET

### Endpoint
/fred/tags/series

### Parameters
#### Query Parameters
- **tag_names** (str) - Required - A semicolon delimited list of tag names that series match all of.
- **api_key** (str) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `tags/series` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Request Example
```json
{
  "tag_names": "gdp;monthly",
  "api_key": "YOUR_API_KEY"
}
```

### Response
#### Success Response (200)
- **response** (dict) - A dictionary representing the json response.

#### Response Example
```json
{
  "seriess": [
    {
      "id": "GDP1",
      "title": "Gross Domestic Product, Monthly",
      "realtime_start": "2023-01-01",
      "realtime_end": "2023-01-01",
      "last_updated": "2023-01-01T10:00:00Z",
      "observation_start": "1959-01-01",
      "observation_end": "2022-12-01",
      "frequency": "m",
      "frequency_short": "m",
      "units": "Billions of Chained 2017 Dollars",
      "units_short": "Bil. of Chn. 2017 $',
      "seasonal_adjustment": "Not Seasonally Adjusted",
      "seasonal_adjustment_short": "NSA",
      "last_updated_raw": "2023-01-01T10:00:00Z",
      "popularity": 50,
      "notes": ""
    }
  ]
}
```
```

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

### GET /series/related_tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Retrieves related FRED tags for one or more FRED tags matching a series search.

```APIDOC
## GET /series/related_tags

### Description
Get the related FRED tags for one or more FRED tags matching a series search.

### Parameters
#### Query Parameters
- **search_text** (str) - Required - The text to match against.
- **tag_names** (str) - Required - A semicolon delimited list of tag names.
- **api_key** (str | None) - Optional - FRED API key.
- **return_format** (Literal['json', 'pandas', 'polars']) - Optional - Format of the response. Defaults to 'pandas'.
- **kwargs** (dict) - Optional - Additional parameters to FRED API series/observation endpoint.
```

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

### Get Series Data as Pandas DataFrame

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

Retrieve the latest data for a given series using get_series. By default, the data is returned as a pandas DataFrame with appropriate data types inferred for columns.

```python
gdp_df = pf.get_series(series_id="GDP")
```

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

### Get All Releases for a Series - pyfredapi

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Fetches observations or data values for all releases associated with a given economic data series ID. The function allows specifying the return format as JSON, pandas, or polars DataFrame. Additional parameters for the FRED API 'series/observation' endpoint can be passed via kwargs.

```python
get_series_all_releases(series_id: str, api_key: ApiKeyType = None, return_format: ReturnFormats = 'pandas', **kwargs: KwargsType) -> ReturnTypes
```

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

### Build and View Documentation

Source: https://pyfredapi.readthedocs.io/en/latest/references/CONTRIBUTING

Generate the project documentation using Sphinx and open the index file in a browser.

```bash
make html -C docs/
```

```bash
open docs/_build/html/index.html
```

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

### Get Series Metadata

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

Use get_series_info to retrieve metadata for a specific FRED series. The function returns a SeriesInfo object containing details like observation dates, frequency, and units.

```python
gdp_info = pf.get_series_info(series_id="GDP")

# Using rich to pretty print the SeriesInfo
rprint(gdp_info)
```

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

### Get categories for a series

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/category

Use `get_series_categories` to find the category or categories associated with a given FRED series ID. This is useful when you have a series in mind but don't know its related categories.

```python
pprint(pf.get_series_categories(series_id="UNRATE"))
```

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

### Initialize Development Environment with Hatch

Source: https://pyfredapi.readthedocs.io/en/latest/references/CONTRIBUTING

Create and activate a virtual environment for the project using hatch.

```bash
hatch env create
hatch shell
```

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

### Get Series Observations - pyfredapi

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Retrieves observations or data values for a specified economic data series ID. It supports JSON or pandas DataFrame return formats and accepts additional FRED API parameters. The API key defaults to FRED_API_KEY environment variable if not provided.

```python
get_series(series_id: str, api_key: ApiKeyType = None, return_format: ReturnFormats = 'pandas', **kwargs: KwargsType) -> ReturnTypes
```

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

### Initialize pyfredapi

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/sources

Import the library to begin making API calls.

```python
import pyfredapi as pf
```

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

### Import pyfredapi and Rich

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

Import necessary libraries for interacting with the FRED API and for pretty-printing output.

```python
from rich import print as rprint
from rich.pretty import pprint

import pyfredapi as pf
```

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

### GET get_category_children

Source: https://pyfredapi.readthedocs.io/en/latest/references/category

Retrieves the children of a specific category by its ID.

```APIDOC
## GET get_category_children

### Description
Get category children by category ID.

### Parameters
#### Query Parameters
- **category_id** (str | None) - Optional - Category id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API category/children endpoint.

### Response
#### Success Response (200)
- **dict** - Dictionary representing the json response.
```

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

### Retrieve all releases

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/releases

Fetch metadata for all available releases and inspect the count or specific entries.

```python
all_releases = pf.get_releases()
```

```python
print(f"Number of release = {all_releases['count']}")
```

```python
releases = all_releases["releases"]
```

```python
pprint(releases[0:3])
```

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

### Initialize SeriesCollection

Source: https://pyfredapi.readthedocs.io/en/latest/references/series_collection

Creates a new instance of SeriesCollection to manage multiple FRED series.

```python
__init__(series_id: Union[Sequence[str], str], api_key: Union[str, None] = None, rename: Union[Dict[str, str], Callable[[str], str], None] = None, drop_realtime: bool = True, sleep: float = 0.1, **kwargs)
```

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

### Show Figure

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/maps

Renders the figure window.

```python
fig.show()
```

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

### Create a SeriesCollection

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series_collection

Initialize a new SeriesCollection instance with a list of series IDs.

```python
sc = pf.SeriesCollection(series_id=["GDP"])
```

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

### Configure Matplotlib Backend

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/maps

Checks the current backend and switches to the 'agg' backend for non-interactive rendering.

```python
import matplotlib

print(matplotlib.get_backend())
matplotlib.use("agg")
```

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

### GET get_category_related

Source: https://pyfredapi.readthedocs.io/en/latest/references/category

Retrieves related categories for a given category ID.

```APIDOC
## GET get_category_related

### Description
Get related categories by category ID.

### Parameters
#### Query Parameters
- **category_id** (str) - Required - Category id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **kwargs** (dict) - Optional - Additional parameters to FRED API category/children endpoint.

### Response
#### Success Response (200)
- **dict** - Dictionary representing the json response.
```

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

### Retrieve the initial release of an economic series

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

Fetches only the first release of the specified economic series.

```python
gdp_initial_release_df = pf.get_series_initial_release("GDP")
gdp_initial_release_df.tail()
```

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

### Set FRED API Key Environment Variable

Source: https://pyfredapi.readthedocs.io/en/latest

Configure the API key by adding an export command to shell configuration files.

```bash
export FRED_API_KEY="your_api_key"
```

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

### Import necessary libraries

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/category

Imports the required libraries for data analysis and visualization, including pyfredapi.

```python
import operator

import matplotlib.pyplot as plt
import seaborn as sns
from rich.pretty import pprint

import pyfredapi as pf
```

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

### GET get_category_related_tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/category

Retrieves related FRED tags for a category by category ID.

```APIDOC
## GET get_category_related_tags

### Description
Get the related FRED tags for a category by category ID.

### Parameters
#### Query Parameters
- **category_id** (str | None) - Optional - Category id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **return_format** (str | ReturnFormat) - Optional - Define how to return the response. Must be either 'json' or 'pandas'.
- **kwargs** (dict) - Optional - Additional parameters to FRED API category/children endpoint.

### Response
#### Success Response (200)
- **dict | DataFrame | DataFrame** - The related tags in the requested format.
```

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

### Prepare Data for Plotting

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/category

Merges unemployment data into a long format and calculates the minimum and maximum dates for plotting.

```python
long_df = unemployment_sc.merge_long()
min_date = min(long_df["date"].dt.date)
max_date = max(long_df["date"].dt.date)
```

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

### Retrieve series releases as of a specific date

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

Fetches all releases of a series that were known on or before the provided date.

```python
gdp_090122_df = pf.get_series_asof_date("GDP", date="2022-09-01")
gdp_090122_df.tail()
```

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

### Inspect source metadata

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/sources

Retrieve a subset of the sources list to view individual source details.

```python
sources["sources"][0:3]
```

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

### Retrieve all tags

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/tags

Fetch the complete list of tags available in the FRED database.

```python
tags = pf.get_tags()
```

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

### Retrieve release information

Source: https://pyfredapi.readthedocs.io/en/latest/references/releases

Fetches details for a specific economic data release using its ID.

```python
release_info = get_release(release_id=53)
```

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

### Retrieve all economic data sources

Source: https://pyfredapi.readthedocs.io/en/latest/references/sources

Fetches a list of all available economic data sources from the FRED API.

```python
get_sources(api_key: ApiKeyType = None, **kwargs: KwargsType) -> JsonType
```

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

### Retrieve all FRED sources

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/sources

Fetch the complete list of data sources available through the FRED API.

```python
sources = pf.get_sources()
```

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

### Retrieve releases for a specific source

Source: https://pyfredapi.readthedocs.io/en/latest/references/sources

Fetches all releases associated with a given source ID.

```python
get_source_release(source_id: int, api_key: ApiKeyType = None, **kwargs: KwargsType)
```

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

### GET /series/vintagedates

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Retrieves the historical dates when a series' data values were revised or new data values were released.

```APIDOC
## GET /series/vintagedates

### Description
Get the dates in history when a series' data values were revised or new data values were released.

### Parameters
#### Query Parameters
- **series_id** (str) - Required - Series id of interest.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None.
- **kwargs** (dict) - Optional - Additional parameters to FRED API series/vintagedates endpoint.

### Response
#### Success Response (200)
- **List[str]** - List of strings representing the available vintage dates.
```

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

### Retrieve single release metadata

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/releases

Fetch metadata for a specific release using its ID.

```python
employment_cost_index = pf.get_release(release_id="11")
```

```python
pprint(employment_cost_index)
```

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

### Retrieve series matching tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/tags

Fetches series that match all provided tag names.

```python
get_series_matching_tags(tag_names: str, api_key: ApiKeyType = None, **kwargs: KwargsType) -> JsonType
```

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

### Open Series URL

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

The SeriesInfo object provides a convenient method to open the corresponding series page on the FRED website in a new browser tab.

```python
gdp_info.open_url()
```

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

### SeriesCollection Initialization

Source: https://pyfredapi.readthedocs.io/en/latest/references/series_collection

Initializes a SeriesCollection object to manage multiple FRED economic series. It can accept a single series ID or a sequence of IDs, and allows for custom renaming, dropping real-time data, and setting a sleep interval between API requests.

```APIDOC
## SeriesCollection
A collection of `pyfredapi.SeriesData` objects.
Useful when you need to collect and manage multiple economic series. Provides methods for listing metadata, collecting data, and merging data together in long or wide formats.

### __init__
```python
__init__(series_id: Union[Sequence[str], str], api_key: Union[str, None] = None, rename: Union[Dict[str, str], Callable[[str], str], None] = None, drop_realtime: bool = True, sleep: float = 0.1, **kwargs)
```

Create an instance of SeriesCollection.

Parameters:
Name | Type | Description | Default  
---|---|---|---  
`series_id` |  `Sequence[str] | str` |  Sequence of series IDs to add to collection. |  _required_  
`api_key` |  `str | None` |  FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables. |  `None`  
`drop_realtime` |  `bool` |  Indicates if you want to drop the realtime columns. |  `True`  
`rename` |  `Union[Dict[str, str], Callable[[str], str], None]` |  Label to give series. Defaults to series ID. |  `None`  
`sleep` |  `float` |  Time to sleep between requests. Defaults to 0.1. |  `0.1`  
`**kwargs` |  `dict` |  Additional parameters to FRED API `series/` endpoint. Refer to the FRED documentation for a list of all possible parameters. |  `{}`  
```

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

### Get all series in a category

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/category

Use `get_category_series` to retrieve all series belonging to a specific category ID. This function returns a dictionary of `SeriesInfo` objects.

```python
all_unemployment_series = pf.get_category_series(category_id=32447)
```

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

### Retrieve all releases of an economic series

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series

Fetches every observation for each release of a specified economic series.

```python
gdp_all_releases_df = pf.get_series_all_releases("GDP")
gdp_all_releases_df.tail()
```

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

### Accessing SeriesData

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series_collection

Demonstrate equality between attribute and bracket access, and retrieve metadata or dataframe tails.

```python
sc.GDP == sc["GDP"]
```

```python
pprint(sc.GDP.info)
```

```python
sc.GDP.df.tail()
```

```python
pprint(sc["GDP"].info)
```

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

### Retrieve series for a release

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/releases

Fetch the series associated with a specific release ID.

```python
series = pf.get_release_series(release_id="11")
```

```python
series["seriess"][0]
```

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

### Retrieve shape files with get_shape_files

Source: https://pyfredapi.readthedocs.io/en/latest/references/maps

Requests shape files in Well-known text (WKT) format for specified geographical boundaries.

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

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

### Tags API - Get Related Tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/tags

Retrieves related FRED tags for a given set of tag names. This function corresponds to the FRED API's related_tags/ endpoint.

```APIDOC
## GET /fred/related_tags

### Description
Get related FRED tags for one or more FRED tags.

### Method
GET

### Endpoint
/fred/related_tags

### Parameters
#### Query Parameters
- **tag_names** (str) - Required - A semicolon delimited list of tag names that series match all of.
- **api_key** (str) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in the environment.
- **kwargs** (dict) - Optional - Additional parameters to FRED API `related_tags/` endpoint. Refer to the FRED documentation for a list of all possible parameters.

### Request Example
```json
{
  "tag_names": "gdp;nsa",
  "api_key": "YOUR_API_KEY"
}
```

### Response
#### Success Response (200)
- **response** (dict) - A dictionary representing the json response.

#### Response Example
```json
{
  "related_tags": [
    {
      "tag": {
        "key": "monthly",
        "unit": {
          "id": "99",
          "name": "Not Seasonally Adjusted",
          "short": "NSA"
        },
        "series_count": 1000
      }
    }
  ]
}
```
```

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

### Create SeriesCollection with specific series

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/category

Constructs a `SeriesCollection` object using a list of series IDs and a dictionary mapping series IDs to their desired names. This prepares the data for downloading.

```python
series_id = [series.id for series in seasonally_adjusted_unemployment_series]
```

```python
series_names = {
    series_info.id: series_info.title
    for series_info in seasonally_adjusted_unemployment_series
}
```

```python
unemployment_sc = pf.SeriesCollection(series_id=series_id, rename=series_names)
```

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

### Retrieve a specific economic data source

Source: https://pyfredapi.readthedocs.io/en/latest/references/sources

Fetches details for a specific source using its ID. Requires a valid FRED API key or an environment variable.

```python
get_source(source_id: int, api_key: ApiKeyType = None, **kwargs: KwargsType) -> JsonType
```

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

### Open FRED Webpage for a Series

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Opens the FRED webpage for a given economic data series. This function is part of the SeriesInfo class.

```python
open_url()
```

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

### Retrieve FRED tags

Source: https://pyfredapi.readthedocs.io/en/latest/references/tags

Fetches general FRED tags information.

```python
get_tags(api_key: ApiKeyType = None, **kwargs: KwargsType) -> JsonType
```

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

### Series Module - get_series_all_releases

Source: https://pyfredapi.readthedocs.io/en/latest/references/series

Retrieves all release dates for a given economic data series ID.

```APIDOC
## GET /series/{series_id}/releases

### Description
Get the observations or data values for all releases an economic data series by ID.

### Method
GET

### Endpoint
/series/{series_id}/releases

### Parameters
#### Path Parameters
- **series_id** (str) - Required - Series id of interest.

#### Query Parameters
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.
- **sort_order** (Literal['asc', 'desc']) - Optional - The order in which to sort the results. Defaults to 'sort_order'.
- **offset** (int) - Optional - The starting offset for results.
- **limit** (int) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "series_id": "GDP"
}
```

### Response
#### Success Response (200)
- **releases** (list) - A list of release objects, each containing 'release_id', 'series_id', 'date', and 'name'.

#### Response Example
```json
{
  "releases": [
    {
      "release_id": 100,
      "series_id": "GDP",
      "date": "2023-01-26",
      "name": "Gross Domestic Product, Third Estimate"
    }
  ]
}
```
```

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

### get_shape_files

Source: https://pyfredapi.readthedocs.io/en/latest/references/maps

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

```APIDOC
## GET /maps/shape

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

### Method
GET

### Endpoint
/maps/shape

### Parameters
#### Query Parameters
- **shape** (Literal['bea', 'msa', 'frb', 'necta', 'state', 'country', 'county', 'censusregion', 'censusdivision']) - Required - Define the shape of Well-known text (WKT) data.
- **api_key** (str | None) - Optional - FRED API key. Defaults to None. If None, will search for FRED_API_KEY in environment variables.

### Response
#### Success Response (200)
- **dict** (dict) - Dictionary representing the json response.

### Response Example
```json
{
  "example": "JSON response object"
}
```
```

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

### Create Bar Chart of Latest Unemployment Data

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/category

Generates a bar chart showing the unemployment rate for each series on the latest available date. Requires Seaborn and Matplotlib.

```python
sns.set(rc={"figure.figsize": (11.7, 8.27)})
ax = sns.barplot(
    data=long_df[long_df["date"] == max(long_df["date"])],
    x="series",
    y="value",
    hue="series",
)
plt.xticks(rotation=290)
ax.set(
    xlabel="Series",
    xticklabels=[],
    ylabel="Unemployment Rate",
    title=f"U.S. Unemployment Rate, Seasonally Adjusted, {max_date}",
)
sns.move_legend(ax, "best")
```

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

### Rename series with a dictionary

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/series_collection

Use a dictionary to map original series IDs to custom names during initialization.

```python
new_names = {
    "CPIAUCSL": "cpi_all_items",
    "CPILFESL": "cpi_all_items_less_food_and_energy",
}

cpi_sc = pf.SeriesCollection(series_id=["CPIAUCSL", "CPILFESL"], rename=new_names)
```

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

### Count total sources

Source: https://pyfredapi.readthedocs.io/en/latest/tutorials/sources

Determine the number of sources returned in the sources dictionary.

```python
len(sources["sources"])
```

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

### Retrieve Category Information

Source: https://pyfredapi.readthedocs.io/en/latest/references/category

Fetches category details by ID using the get_category function.

```python
>>> import pyfredapi as pf
>>> pf.get_category(category_id=125)
```