Metadata-Version: 2.4
Name: fredq
Version: 0.3.0
Summary: LLM-friendly CLI for raw FRED (Federal Reserve Economic Data) API JSON.
Project-URL: Homepage, https://github.com/joce/fredq
Project-URL: Repository, https://github.com/joce/fredq
Project-URL: Issues, https://github.com/joce/fredq/issues
Author-email: Jocelyn Legault <jocelynlegault@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,economic-data,federal-reserve,fred,llm-tools,macro
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Utilities
Requires-Python: <4.0,>=3.10
Requires-Dist: httpx<1.0,>=0.28
Requires-Dist: polars<2.0,>=1.41
Requires-Dist: typing-extensions>=4.13
Description-Content-Type: text/markdown

# fredq

[![CI](https://github.com/joce/fredq/actions/workflows/ci.yml/badge.svg)](https://github.com/joce/fredq/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/joce/fredq/graph/badge.svg)](https://codecov.io/gh/joce/fredq)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![GitHub License](https://img.shields.io/github/license/joce/fredq)](https://github.com/joce/fredq/blob/main/LICENSE)

FRED Query — Federal Reserve Economic Data on the command line.

fredq brings the [FRED](https://fred.stlouisfed.org/docs/api/fred/) (Federal
Reserve Economic Data) HTTP endpoints to the command line. It is built for
scripts, agents, and quick terminal work that needs the JSON returned by the
FRED API.

The project stays deliberately close to the source. It does not reshape FRED
responses, define economic domain models, or add a discovery API beyond CLI
help.

## Features

- Raw FRED JSON on stdout, with no pretty-printing or interpretation.
- Endpoint-specific commands for every public FRED API endpoint.
- Generated help that includes examples, parameters, and known value sets.
- Typed Parquet output for `series observations` when a long time series is
  more useful as a columnar table than as JSON.
- ALFRED point-in-time support (`--realtime-start`, `--realtime-end`,
  `series vintage-dates`).
- GeoFRED / Maps regional data (`geofred` subcommands): regional time series,
  all-region snapshots, series-group metadata, and GeoJSON shape files.

## Install

fredq is a Python 3.10+ project. Install it as a tool with
[uv](https://docs.astral.sh/uv/) or with pip:

```powershell
uv tool install fredq
# or
pip install fredq
```

Then run:

```powershell
fredq --help
```

### From Source

To run from a local checkout (development):

```powershell
uv sync --all-groups
uv run fredq --help
```

Or install the checkout as a tool:

```powershell
uv tool install .
fredq --help
```

## API Key

The FRED API requires a free API key. Request one at
<https://fred.stlouisfed.org/docs/api/api_key.html>.

fredq reads the key from, in order:

1. The `FRED_API_KEY` environment variable.
2. The first non-empty line of `~/.fredq/api_key`.
3. The `--api-key` flag (visible in process listings; prefer the env var).

On POSIX systems, restrict the key file so only your user can read it:

```bash
chmod 600 ~/.fredq/api_key
```

fredq emits a warning if the file is readable by group or world. To disable
the file fallback entirely (for hermetic runs), set `FREDQ_DISABLE_KEY_FILE=1`
or pass `--no-key-file`.

fredq never prints, logs, or echoes the API key. The key is also redacted
from URLs in error messages and from any httpx debug logs emitted under
`--verbose`.

## Quick Start

Show metadata for a series:

```powershell
uv run fredq series show GNPCA
```

Fetch a series' observations:

```powershell
uv run fredq series observations CPIAUCSL
```

Apply a unit transformation and frequency aggregation:

```powershell
uv run fredq series observations CPIAUCSL --units pch --frequency m
```

Search for a series by keyword:

```powershell
uv run fredq series search "10-year treasury" --limit 10
```

Browse the FRED category tree from the root:

```powershell
uv run fredq category children 0
```

List recent economic releases:

```powershell
uv run fredq release list --limit 10
```

List recent release publication dates across all releases:

```powershell
uv run fredq release calendar --limit 20
```

Show metadata for a specific release (53 = GDP):

```powershell
uv run fredq release show 53
```

Find all series tagged with a set of FRED tags:

```powershell
uv run fredq tag series "usa;monthly;cpi" --limit 25
```

ALFRED point-in-time: see what GDP looked like on a past date:

```powershell
uv run fredq series vintage-dates GNPCA
uv run fredq series observations GNPCA --realtime-start 2024-09-25
```

Fetch GeoFRED regional data — per-capita income by state for one year:

```powershell
uv run fredq geofred series-group WIPCPI
uv run fredq geofred series-data WIPCPI --start-date 2022-01-01
```

## Parquet Output

`series observations` can write a typed Parquet table instead of raw JSON.
Parquet output is included in a plain install — no extra required. Pass
`--format parquet --out PATH`:

```powershell
uv run fredq series observations CPIAUCSL --units pch --frequency m \
  --format parquet --out cpi_yoy.parquet
```

On success a single JSON descriptor line goes to stdout (the file format, out
path, row count, byte size). The Parquet schema is `date` (date32), `value`
(float64), `realtime_start` (date32), `realtime_end` (date32). FRED's
missing-value sentinel `.` is written as `NaN`. The full response envelope
(count, offset, limit, observation range, units, sort order) and the request
context (units, frequency, realtime range) are stored as schema key-value
metadata so the table is self-describing.

Parquet writes are scoped to `series observations` only; every other command
stays JSON-only, and rejects `--format parquet` with a usage error. Parquet
output assumes FRED's default observation layout (one row per observation);
fredq does not expose FRED's alternative `output_type` modes.

## Discovering IDs

Most commands take an ID as a positional argument. If you don't know one yet,
start with the commands that need no ID, then chain:

```powershell
# Find a series ID by keyword
uv run fredq series search "unemployment rate" --limit 10

# List the catalogs
uv run fredq release list --limit 1000  # release IDs
uv run fredq source list                # source IDs
uv run fredq tag list --limit 50        # tag names

# Walk the category tree from the root (0 = root)
uv run fredq category children 0
```

Then use the ID with the matching command:

```powershell
uv run fredq series observations DGS10
uv run fredq category series 106
uv run fredq release series 10
```

## Commands

Use root help to see the command list:

```powershell
uv run fredq --help
```

Current commands, grouped by how often they're reached for:

**Daily-driver fetches**

| Command | FRED data |
| --- | --- |
| `series show` | Show metadata for one FRED series (title, units, frequency, observation range). |
| `series observations` | Fetch the observation values for one FRED series. |

**Series discovery**

| Command | FRED data |
| --- | --- |
| `series search` | Search FRED series by keyword. |
| `series search-tags` | List tags for a series full-text search. |
| `series search-related-tags` | List tags related to a search and existing tag filter. |
| `tag series` | List series matching a set of FRED tags. |
| `tag list` | List all FRED tags. |
| `tag related` | List tags related to an existing tag filter. |

**Series-bound analysis**

| Command | FRED data |
| --- | --- |
| `series vintage-dates` | List vintage dates (revision dates) for one FRED series. |
| `series categories` | List categories that contain a given series. |
| `series tags` | List tags assigned to a FRED series. |
| `series release` | Show the release that a FRED series belongs to. |
| `series updates` | List recently updated FRED series. |

**Category browse**

| Command | FRED data |
| --- | --- |
| `category show` | Show metadata for one FRED category. |
| `category children` | List child categories of a FRED category. |
| `category related` | List categories related to a given FRED category. |
| `category series` | List series belonging to one FRED category. |
| `category tags` | List tags for series in one FRED category. |
| `category related-tags` | List tags related to a category and existing tag filter. |

**Releases and calendar**

| Command | FRED data |
| --- | --- |
| `release list` | List all FRED economic data releases. |
| `release calendar` | List release dates across all FRED releases. |
| `release show` | Show metadata for one FRED release. |
| `release dates` | List publication dates for one FRED release. |
| `release series` | List series belonging to one FRED release. |
| `release sources` | List sources for one FRED release. |
| `release tags` | List tags for one FRED release. |
| `release related-tags` | List tags related to a release and existing tag filter. |
| `release tables` | Fetch the hierarchical data table for one FRED release. |

**Sources**

| Command | FRED data |
| --- | --- |
| `source list` | List all FRED data sources. |
| `source show` | Show metadata for one FRED source. |
| `source releases` | List releases published by one FRED source. |

**GeoFRED / Maps (`geofred` subcommands)**

| Command | FRED data |
| --- | --- |
| `geofred series-group` | Show GeoFRED series-group metadata (region type, season, frequency, units). |
| `geofred series-data` | Fetch the regional time series for one FRED series. |
| `geofred regional-data` | Fetch a regional snapshot — all regions for a single date. |
| `geofred shapes` | Download a GeoJSON shape file for a region type, to `--out`. |

The GeoFRED endpoints use a different base URL and return regional data keyed by
FIPS code. `geofred shapes` returns Highcharts-format GeoJSON whose coordinates
are in a Lambert Conformal Conic projection (not WGS84); reproject before mixing
with lat/lon basemaps. See `fredq geofred --help` for the full subcommand list.

A bare group prints its list of subcommands; each leaf command has its own
adaptive help:

```powershell
uv run fredq series --help              # group: lists the series subcommands
uv run fredq series observations --help # leaf: full endpoint help
uv run fredq series search --help
uv run fredq release calendar --help
```

Leaf-command help is the primary documentation surface. It shows the FRED target
endpoint, accepted parameters, allowed value sets, defaults, and examples.

## Dates, Booleans, and Tag Lists

Date parameters accept:

- `YYYY-MM-DD` calendar dates.
- ISO 8601 datetimes (the time component is dropped; UTC assumed for naive
  values).
- Unix timestamps in seconds (≥10 digits).

Boolean parameters accept common true and false forms such as `true`, `false`,
`1`, `0`, `yes`, and `no`.

Tag lists (`--tag-names`, `--exclude-tag-names`) use semicolons as
separators, matching FRED's wire format:

```powershell
uv run fredq tag series "usa;annual"
```

## ALFRED Point-in-Time

Most endpoints accept `--realtime-start` and `--realtime-end` to view data
as of a historical date (the [ALFRED](https://alfred.stlouisfed.org/)
archival API). Combined with `series vintage-dates`, this lets you replay
what an analyst would have seen on a specific past date — useful for
backtests and for distinguishing data revisions from real-time signals.

```powershell
# When were GNP revisions published?
uv run fredq series vintage-dates GNPCA

# What did GNP look like on 2024-09-25?
uv run fredq series observations GNPCA \
  --realtime-start 2024-09-25 --realtime-end 2024-09-25
```

## Output Contract

fredq writes the FRED response body to stdout exactly as returned. This makes
it easy to pipe into tools that expect JSON:

```powershell
uv run fredq series show GNPCA | jq .
uv run fredq release list --limit 25 | jq '.releases[].name'
```

Diagnostics, warnings, and errors are written to stderr. The exit code is
`0` on success, `1` on a FRED request failure, and `2` on a usage or
configuration error.

## Development

Install development dependencies:

```powershell
uv sync --all-groups
```

Run the test suite:

```powershell
uv run pytest
```

Run checks locally:

```powershell
uv run black --check .
uv run ruff format --check --diff .
uv run ruff check .
uv run pyright
uv run pytest -n auto
```

Run the full project check, including Python checks across supported
versions and spelling:

```powershell
uv run tox
```

When adding or changing command metadata, update validation, adaptive help,
and tests together. Then verify the relevant command against FRED with its
help, minimal required parameters, and representative optional parameters.

## License

fredq is released under the MIT License. See [LICENSE](LICENSE).
