Skip to content
imibare

How-to guide

Load data

This guide shows how to use imibare.load() and imibare.catalog() to work with datasets programmatically.

Install

Terminal window
pip install imibare

Load a dataset

import imibare as imi


df = imi.load("rw.nisr.cpi.monthly")

Returns a pandas DataFrame. The file is cached at ~/.imibare/cache/ on first download.

Filter by date range

# By year
df = imi.load("rw.nisr.cpi.monthly", start=2020, end=2023)


# By exact date
df = imi.load("rw.bnr.fx.daily", start="2024-01-01", end="2024-12-31")


# From a date to the present
df = imi.load("rw.bnr.fx.daily", start="2024-01-01")

start and end are inclusive. Both are optional.

Load as a Polars DataFrame

df = imi.load("rw.nisr.cpi.monthly", engine="polars")

Requires polars to be installed: pip install polars.

Load a historical version

# Load the snapshot as it existed on 2025-06-01
df = imi.load("rw.nisr.cpi.monthly", version="2025-06-01")

This queries the Iceberg snapshot on or before the given date. It requires the [iceberg] extra and the R2 Data Catalog credentials described under Credentials below. The default (no version argument) needs no credentials.

Force a fresh download

df = imi.load("rw.nisr.cpi.monthly", force_download=True)

Bypasses the local cache and re-downloads from the imibare API.

Browse the catalog

# All datasets
datasets = imi.catalog()


# Filter by country
datasets = imi.catalog(country="RW")


# Filter by topic
datasets = imi.catalog(topic="prices")


# Filter by frequency
datasets = imi.catalog(frequency="monthly")


# Combine filters
datasets = imi.catalog(country="RW", topic="monetary")


# Print IDs and names
for d in datasets:
    print(d.id, d.name)

Inspect dataset metadata

datasets = imi.catalog(country="RW")
d = datasets[0]


print(d.id)               # "rw.nisr.cpi.monthly"
print(d.institution)      # "National Institute of Statistics of Rwanda"
print(d.coverage_start)   # "2009-01"
print(d.pipeline)         # "automated" | "curated" | "stale"
print(d.formats)          # ["csv", "json", "parquet"]


for col in d.columns:
    print(col.name, col.type, col.description)

Use all available datasets in a loop

import imibare as imi


for d in imi.catalog(country="RW"):
    if d.pipeline == "automated":
        df = imi.load(d.id)
        print(f"{d.id}: {len(df)} rows, columns: {df.columns.tolist()}")

Credentials

The default load(dataset_id) path needs no credentials. It fetches the latest data from the public imibare API (https://api.imibare.org); only catalog() reads bundled metadata fully offline. To point the loader at a different API host, such as a mirror or a local instance, set IMIBARE_API_URL.

The versioned path (load(dataset_id, version=...)) is the exception. It queries an Iceberg snapshot directly and requires the [iceberg] extra plus the R2 Data Catalog credentials:

Terminal window
export R2_ACCOUNT_ID=<your-account-id>
export R2_BUCKET=imibare-data
export R2_CATALOG_URL=<catalog-rest-endpoint>
export R2_CATALOG_TOKEN=<cloudflare-api-token>

See How to query with DuckDB for direct object access.

Reference

Full parameter documentation: Python package reference