Load data

Use this guide when you are working in Python and want a DataFrame. We use imibare.load() to retrieve data and imibare.catalog() to find dataset IDs and inspect their metadata.

Install

Install the package in the Python environment where you will run the code. Add polars only if you want load() to return Polars DataFrames.

pip install imibare
pip install polars  # optional, for engine="polars"

Choose a loading path

All paths begin with a permanent dataset ID, such as rw.nisr.cpi.monthly. Use the catalog to find one if you do not already know it.

Load the current dataset

import imibare as imi

rwanda_cpi = imi.load("rw.nisr.cpi.monthly")
kenya_cpi = imi.load("ke.knbs.cpi.monthly")

load() returns pandas by default. The first request stores the downloaded file under ~/.imibare/cache/; for 1 hour after that, load() reuses it without a request.

Limit the dates

Pass years for annual or broad date filtering, or ISO dates when you need precise bounds. Both start and end are optional, and both bounds are included in the result.

# Years
cpi_2020_to_2023 = imi.load("rw.nisr.cpi.monthly", start=2020, end=2023)

# Exact daily dates
usd_2024 = imi.load("rw.bnr.fx.daily", start="2024-01-01", end="2024-12-31")

# A date through the latest published row
recent_fx = imi.load("rw.bnr.fx.daily", start="2024-01-01")

Return Polars

Install Polars first, then choose it with the engine argument. This is useful when the rest of your analysis already uses Polars and you do not want an extra conversion step.

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

Work from the cache

When a cached file is older than 1 hour, we ask the API whether it changed. The API either confirms the cached version or sends a replacement; if the API cannot be reached, load() returns the cached copy and raises a UserWarning that says when it was last confirmed current.

A dataset you have never loaded cannot be read offline. Pass force_download=True when you need to skip the cache and request the newest available file.

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

Find IDs and inspect metadata

The package includes the catalog that was current when your installed version was released, so this step also works offline. Filter it before loading when you want to discover coverage by country, topic, or frequency.

# Catalog records
all_datasets = imi.catalog()
kenya = imi.catalog(country="KE")
monthly = imi.catalog(frequency="monthly")
kenya_monthly = imi.catalog(country="KE", frequency="monthly")

# Inspect one record
dataset = kenya_monthly[0]
print(dataset.id)
print(dataset.institution)
print(dataset.coverage_start)
print(dataset.pipeline)  # "automated", "curated", or "stale"

for column in dataset.columns:
    print(column.name, column.type, column.description)

topic is a metadata category, not necessarily the third part of an ID. For example, rw.nisr.cpi.monthly has the metadata topic prices.

Load a set of datasets

Use the catalog records as the input to a loop when you need the same operation across a defined set. Read each dataset’s columns before assuming that equally frequent datasets share a schema.

for dataset in imi.catalog(country="KE", frequency="monthly"):
    frame = imi.load(dataset.id)
    print(f"{dataset.id}: {len(frame)} rows, columns: {frame.columns.tolist()}")

Use another API host

The default host is https://api.imibare.org, and it does not need credentials. Set IMIBARE_API_URL only when you are using a mirror or a local API instance.

export IMIBARE_API_URL=http://localhost:8787

Read a historical version

imi.load(dataset_id, version="YYYY-MM-DD") can read the version published on a given date from our Iceberg tables. This needs the [iceberg] extra and R2 Data Catalog credentials, which we do not issue publicly, so public access serves the latest version only.

The Python package reference lists the required environment variables and every load() parameter.