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, EURO, TPM, IPC, IMACEC, PIB, and more), parses them into clean, typed data, and keeps a local SQLite cache so repeat queries are instant and a script can fall back to its last good result when the API fails.

Install

pip install econchile

Requires Python 3.10+. To install from source instead:

git clone https://github.com/cristobal437/econchile.git
cd econchile
pip install -e .

Authentication

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

export BCCH_TOKEN="your-token-here"

Windows PowerShell:

$env:BCCH_TOKEN="your-token-here"

The library reads BCCH_TOKEN from the environment — it does not load .env files itself. The token is only needed when the API is actually called (see Gotchas).

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 import OfflineClient, Series

client = OfflineClient()
result = client.get(Series.USD, "2024-01-01", "2024-03-31")  # if the API fails, serves the cached result of this same query (within the TTL)

Indexed series (v0.2)

The library indexes 28 series for convenient access via Series.NAME or client.get("name"). All codes were live-verified against the BCCh API.

FX & money

Rates

Prices

Activity

Labor

Expectations

External

Macro

Any other BCCh series (raw codes)

The indexed list above covers the most-used macro series. Any other series in the BCCh catalog (~30k) works too: pass its code string to client.get(). The result's series field is then the code string instead of a Series member:

eur_clp = client.get("F072.CLP.EUR.N.O.D", "2024-01-01", "2024-03-31")  # CLP per EUR, not indexed

client.search("keyword") searches the indexed series only (name, code, Spanish and English titles). To find other codes, use the BCCh catalog at si3.bcentral.cl or the series.xlsx asset on the v0.2.0 release.

hits = client.search("ipc")
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 names raise KeyError, malformed or inverted dates (desde after hasta) raise ValueError, API failures raise BcchApiError, and OfflineClient raises BcchOfflineError when the cache fallback is also empty. Import them with from econchile import BcchApiError, BcchOfflineError. No token? Both clients construct fine without one — the token is only needed when the API is actually called: BcchClient cache hits work, and OfflineClient serves cached data (a missing token is treated as an API failure, so the cache fallback applies).
• Offline fallback scope: the cache stores whole queries. OfflineClient can only fall back to a result for the same series and the same desde/hasta, fetched within the TTL (24h by default). A query with a new date window (e.g. "up to today" in a daily cron) has nothing to fall back to.
• Token with special characters: BCCh API tokens may contain / characters. The library URL-encodes them automatically via urllib.parse.urlencode (/ → %2F), so you can paste the token as-is. Only if you build request URLs by hand (e.g. curl) do you need to encode it yourself — urllib.parse.quote(token) — otherwise the BCCh API rejects the request.

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 (or the code string, for raw codes)
• observations — list of Observation(date: str, value: float | None)
• fetched_at — timestamp (UTC)
• source — always "api" today (cache hits return the stored result unchanged)
• metadata — as returned by BCCh: series_id, descripEsp, descripIng, series_infos. For frequency and representation use Series.X.meta()

Development

pip install -e ".[test]"
python -m pytest tests/

Want to see the whole library in action? Run the interactive walkthrough, or open the charts tutorial:

jupyter notebook examples/econchile_walkthrough.ipynb
jupyter notebook examples/charts_tutorial.ipynb

Works without a token for the first sections (catalog, search, errors, offline) — only the live-data cells need BCCH_TOKEN.

License

MIT