Metadata-Version: 2.4
Name: fred-stl
Version: 0.7.0
Summary: A Python library for the FRED API (Federal Reserve Bank of St. Louis)
Author: Otto Hermann
Author-email: Otto Hermann <ojhermann@gmail.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Typing :: Typed
Requires-Dist: geojson-pydantic>=2.1.1
Requires-Dist: pydantic>=2.12.5
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/ojhermann-org/fred
Project-URL: Repository, https://github.com/ojhermann-org/fred
Project-URL: Issues, https://github.com/ojhermann-org/fred/issues
Description-Content-Type: text/markdown

# fred-stl

A Python library for the [FRED API](https://fred.stlouisfed.org/docs/api/fred/) (Federal Reserve Economic Data, St. Louis Fed).

> **Work in progress** — the library is being built incrementally. New endpoint groups are added with each minor release.

## Installation

```bash
pip install fred-stl
```

## Requirements

- Python 3.13+
- A [FRED API key](https://fred.stlouisfed.org/docs/api/api_key.html) (free, requires registration)

## Quick start

```python
import json
import urllib.parse
import urllib.request

from fred import category, for_request

params = category.RequestParams(
    api_key="your-api-key",
    file_type=category.FileType.json,
    category_id=0,
)

url = f"{category.ENDPOINT}?{urllib.parse.urlencode(for_request(params))}"

with urllib.request.urlopen(url) as resp:
    data = json.loads(resp.read())

response = category.Response.model_validate(data)
print(response.categories[0].name)  # "Categories"
```

## Usage

Each FRED endpoint is exposed as a module at the top level of the `fred` package. Every module provides:

- `RequestParams` — a typed, validated model for building requests
- `Response` — a typed, validated model for parsing responses
- `ENDPOINT` — the API endpoint URL
- Any enum types needed to construct a request (e.g. `FileType`, `SortOrder`)

Use `for_request` to convert a `RequestParams` instance into a `dict[str, str]` ready for any HTTP client:

```python
from fred import for_request, releases

params = releases.RequestParams(
    api_key="your-api-key",
    file_type=releases.FileType.json,
)

query = for_request(params)  # {"api_key": "...", "file_type": "json", ...}
```

## Available endpoints

### Category

| Module | Endpoint |
|--------|----------|
| `category` | `fred/category` |
| `category_children` | `fred/category/children` |
| `category_related` | `fred/category/related` |
| `category_series` | `fred/category/series` |
| `category_tags` | `fred/category/tags` |
| `category_related_tags` | `fred/category/related_tags` |

### Releases

| Module | Endpoint |
|--------|----------|
| `releases` | `fred/releases` |
| `releases_dates` | `fred/releases/dates` |
| `release` | `fred/release` |
| `release_dates` | `fred/release/dates` |
| `release_series` | `fred/release/series` |
| `release_sources` | `fred/release/sources` |
| `release_tags` | `fred/release/tags` |
| `release_related_tags` | `fred/release/related_tags` |
| `release_tables` | `fred/release/tables` |

### Series

| Module | Endpoint |
|--------|----------|
| `series` | `fred/series` |
| `series_categories` | `fred/series/categories` |
| `series_observations` | `fred/series/observations` |
| `series_release` | `fred/series/release` |
| `series_search` | `fred/series/search` |
| `series_search_tags` | `fred/series/search/tags` |
| `series_search_related_tags` | `fred/series/search/related_tags` |
| `series_tags` | `fred/series/tags` |
| `series_updates` | `fred/series/updates` |
| `series_vintagedates` | `fred/series/vintagedates` |

### Sources

| Module | Endpoint |
|--------|----------|
| `sources` | `fred/sources` |
| `source` | `fred/source` |
| `source_releases` | `fred/source/releases` |

### Tags

| Module | Endpoint |
|--------|----------|
| `tags` | `fred/tags` |
| `tags_related` | `fred/related_tags` |
| `tags_series` | `fred/tags/series` |


### Maps (GeoFRED)

| Module | Endpoint |
|--------|----------|
| `geofred_shapes` | `geofred/shapes/file` |

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md).
