econchile

Chilean macroeconomic data (Banco Central de Chile) for Python.

econchile is a thin, practical client for the BCCh SIE REST web service. It downloads official series (UF, USD, TPM, IPC_VAR, IPC_INDEX, IMACEC, PIB), parses them into clean, typed data, and keeps a local SQLite cache so repeat queries are instant and your scripts survive API outages.

Install

Once v0.1 is on PyPI: pip install econchile. Until then, install from source:

git clone <repo-url> econchile
cd econchile
pip install -e .

Requires Python 3.10+.

Authentication

Request a free API token from the BCCh statistics database (SIE), see the official API documentation.

export BCCH_TOKEN="your-token-here"

The library reads BCCH_TOKEN from the environment — it does not load .env files itself. The token is required for v0.1.

Quickstart

from econchile import BcchClient, Series

client = BcchClient()

# Last 3 months of the UF (daily)
result = client.get(Series.UF, "2024-01-01", "2024-03-31")

for obs in result.observations:
    print(obs.date, obs.value)

Dates are always YYYY-MM-DD. Missing observations have value=None.

The two clients

from econchile.offline import OfflineClient

client = OfflineClient()
result = client.get(Series.USD, "2024-01-01", "2024-03-31")  # survives API outages

Available series (v0.1)

More series are planned. Use client.list_series() for the full catalog and client.search("ipc") to find series by keyword:

hits = client.search("ipc")     # matches name, code, Spanish and English titles
for meta in hits:
    print(meta.series_id, meta.spanish_title)

Gotchas

• Date format: pass YYYY-MM-DD to get(); the library converts the API's native DD-MM-YYYY for you.
• Missing data: the BCCh API marks gaps as "ND". These become value=None, not zeros or exceptions, check for None before using a value.
• Representations: IPC_VAR is a monthly % change, IPC_INDEX is a base-2023 index. Same variable, different meaning.
• Cache freshness: cached results are reused for 24 hours by default; configure via ttl_seconds on BcchClient(...) or OfflineClient(...) (the cache lives at ~/.econchile/cache.db).
• Errors: unknown series raise KeyError, malformed dates raise ValueError, API failures raise BcchApiError and BcchOfflineError when the offline fallback is also exhausted.

API

• BcchClient.get(series, desde, hasta, use_cache=True) — fetch a series over a date range; returns a SeriesResult.
• OfflineClient.get(series, desde, hasta) — same, but API-first with cache fallback.
• BcchClient.search(keyword) — case- and accent-insensitive catalog search → list[SeriesMeta].
• BcchClient.list_series() — all series metadata → list[SeriesMeta].
• BcchClient.clear_cache() — empty the local cache (returns the number of rows removed).

A SeriesResult has:

• series — the Series member
• observations — list of Observation(date: str, value: float | None)
• fetched_at — timestamp (UTC)
• source — "api", "cache", or "partial"
• metadata — series info (titles, frequency, representation)

Development

pip install -e . && pip install pytest
python -m pytest tests/

License

MIT