econ-lens

Explore public economic time series without leaving the terminal. econ-lens searches and fetches keyless DBnomics data, caches responses locally, applies common transformations, draws terminal charts, and exports clean CSV.

It is deliberately small: one data source, five commands, and no account or configuration file.

Install

econ-lens requires Python 3.10 or newer and uv.

git clone https://github.com/wpasc/econ-lens.git
cd econ-lens
uv tool install .
econ-lens --help

For development, use uv sync --locked and prefix commands with uv run instead of installing the tool globally.

A one-minute tour

Search for a series, inspect it, calculate its year-over-year change, plot it, and export the result:

econ-lens search "us unemployment rate" --limit 5
COLUMNS=100 econ-lens show IMF/IFS/M.US.LUR_PT --start 2023 --last 5
COLUMNS=80 LINES=20 econ-lens plot IMF/IFS/M.US.LUR_PT --transform yoy --start 2023
econ-lens export IMF/IFS/M.US.LUR_PT --transform yoy \
  --start 2024-10 --end 2024-12 --output unemployment-yoy.csv
cat unemployment-yoy.csv

The show command currently produces:

Monthly – United States – Labor Markets, Unemployment Rate, Percent
  IMF/IFS/M.US.LUR_PT  ·  monthly
  2023-01 → 2024-12  ·  24 observations
  ▁▃▂▁▄▃▂▄▄▄▄▄▄▅▅▅▆▇██▇▇█▇
┏━━━━━━━━━┳━━━━━━━┓
┃ Period  ┃ Value ┃
┡━━━━━━━━━╇━━━━━━━┩
│ 2024-08 │  4.20 │
│ 2024-09 │  4.10 │
│ 2024-10 │  4.10 │
│ 2024-11 │  4.20 │
│ 2024-12 │  4.10 │
└─────────┴───────┘

The exported file is ordinary two-column CSV:

period,value
2024-10,7.8947368421052655
2024-11,13.513513513513509
2024-12,10.81081081081079

The output above was captured from DBnomics in July 2026. Public datasets are revised and mirrors refresh on their own schedules, so later output may differ.

Commands

Command	Purpose
econ-lens search QUERY [--limit N]	Find series and print their IDs, names, frequencies, and datasets.
econ-lens show ID	Print metadata, a sparkline, and recent observations.
econ-lens plot ID [ID ...]	Plot up to three series in the terminal.
econ-lens export ID [-o FILE]	Write period,value CSV to a file or standard output.
econ-lens cache info|clear	Inspect or empty the local response cache.

show, plot, and export accept these shared options:

• --transform, -t: yoy, mom, index, or real.
• --start PERIOD, --end PERIOD: inclusive period bounds. A year such as 2020 includes the whole year for monthly and quarterly data.
• --base PERIOD: reference period for index or real.
• --deflator ID: CPI series for real. The default is a current US CPI mirror from OECD.
• --refresh: bypass the 24-hour cache and ask DBnomics again.

Run econ-lens COMMAND --help for command-specific options such as show --last and export --output.

Transformations

• yoy computes (value_t / value_same_period_last_year - 1) × 100. It matches period labels, so a missing month or quarter cannot shift the comparison.
• mom computes the consecutive period change and annualizes it: exponent 12 for monthly data, 4 for quarterly data, and 1 for annual data. Gaps are left missing.
• index rebases values to 100 at --base. Without a base, it uses the first observation in the displayed window.
• real computes nominal_t × (CPI_base / CPI_t). Without a base, it uses the latest common observation. Nominal series and deflator must have the same frequency.

Transformations use the full fetched history before applying --start and --end. This preserves the prior-year observation needed by yoy and allows an explicit base outside the displayed window.

Design notes

Why DBnomics

The keyless FRED CSV endpoint is excellent when a series ID is already known, but it does not offer keyless search. Search is central to this tool. DBnomics provides both search and fetch in a consistent JSON API and covers providers including BLS, Eurostat, IMF, OECD, and ECB.

DBnomics search ranks datasets rather than individual series. econ-lens searches the top dataset matches, searches within each dataset, interleaves the results so one large dataset cannot dominate, then gives a small boost to series names containing the query terms. This is intentionally a thin, explainable ranking layer rather than a search engine of its own.

Cache

Each request is stored as one JSON file under the operating system's user cache directory, keyed by the SHA-256 hash of its URL. Entries expire after 24 hours; --refresh bypasses a valid entry. The payload also records its source URL and fetch time, which keeps the cache inspectable. There is no database, background process, or eviction policy.

Reproducible tests

The default test suite uses recorded, lightly trimmed DBnomics responses and blocks unregistered HTTP requests. It never needs a live service. A separate opt-in smoke test exercises the real API:

uv run ruff check .
uv run ruff format --check .
uv run pytest
uv run pytest -m live

Limitations

• DBnomics mirrors refresh independently of their source agencies and can lag them substantially. For example, the IMF unemployment series in the demo ended at 2024-12 when checked in July 2026. --refresh bypasses the local cache; it cannot make an upstream mirror fresher. The default US CPI deflator uses OECD because that mirror is more current than DBnomics' BLS CPI mirror.
• Search quality is bounded by DBnomics' dataset ranking and the six datasets searched per query. Broad or ambiguous terms may need refinement, and the highest-ranked series may not be the one you intend.
• yoy and mom support monthly, quarterly, and annual frequencies only. real requires exact period-label alignment and equal frequencies; there is no resampling or interpolation.
• Transformations are mechanical. A compatible frequency does not guarantee that a CPI series is economically appropriate for a particular nominal series.
• Missing observations remain gaps in displays and plots and are omitted from CSV exports.
• The cache has no locking or size-based eviction and is intended for one interactive user.

License

MIT