Dataset IDs - Docs

Use a dataset ID whenever you load data, call the API, or build a download URL. We keep the ID short enough to type and stable enough to cite, so it carries 4 pieces of identity in one string.

Read an ID

Every published dataset uses 4 lowercase segments separated by dots. The country comes first so a new country can join the catalog without changing an existing ID.

{country_iso2}.{institution_slug}.{topic}.{frequency}

Segment	Example	Meaning
`country_iso2`	`rw`, `ke`	ISO 3166-1 alpha-2 country code
`institution_slug`	`nisr`, `knbs`	Institution that published the data
`topic`	`cpi`, `fx`, `fiscal-operations`	What this particular dataset measures; hyphens are allowed
`frequency`	`monthly`, `daily`, `annual`	How often the source publishes the series

For example, rw.nisr.cpi.monthly is Rwanda, published by NISR, about the Consumer Price Index, and published monthly.

Find an ID

The catalog is the complete current list. You can also call imi.catalog() from Python or request GET /v1/datasets from the API.

ID	Institution	Dataset	Frequency
`rw.nisr.cpi.monthly`	NISR	Consumer Price Index	Monthly
`rw.bnr.fx.daily`	BNR	Official exchange rates	Daily
`rw.minecofin.fiscal-operations.annual`	MINECOFIN	General government fiscal operations	Annual
`rw.rssb.contributions.annual`	RSSB	Contributions by scheme	Annual
`ke.knbs.cpi.monthly`	KNBS	Consumer Price Index	Monthly
`ke.cbk.inflation.monthly`	CBK	Inflation rates	Monthly

Country codes

We use lowercase ISO 3166-1 alpha-2 codes inside IDs. A country added later receives its own code, and the IDs already in the catalog do not change.

Code	Country
`rw`	Rwanda
`ke`	Kenya

Institution slugs

The institution segment identifies the publisher. It is not an informal abbreviation, so use the slug from this table rather than inventing one.

Rwanda

Slug	Institution
`nisr`	National Institute of Statistics of Rwanda
`bnr`	National Bank of Rwanda
`minecofin`	Ministry of Finance and Economic Planning
`rssb`	Rwanda Social Security Board
`rra`	Rwanda Revenue Authority
`rura`	Rwanda Utilities Regulatory Authority
`rdb`	Rwanda Development Board
`naeb`	National Agricultural Export Development Board

Kenya

Slug	Institution
`knbs`	Kenya National Bureau of Statistics
`cbk`	Central Bank of Kenya

Topic and frequency

The topic segment is a dataset-specific slug. There is no closed topic list because a new dataset often needs a new name; cpi, fx, and wage-employment-by-industry are all valid examples.

Do not confuse this segment with the metadata topic that imi.catalog(topic=...) and GET /v1/datasets?topic= filter. For example, rw.nisr.cpi.monthly has cpi in its ID but uses the metadata topic prices.

Frequency	Meaning
`daily`	Each trading or calendar day
`monthly`	Each calendar month
`quarterly`	Each fiscal or calendar quarter
`annual`	Each calendar or fiscal year
`irregular`	No fixed cycle, as with surveys and censuses

Keep IDs permanent

Once an ID is published, we do not rename or remove it. A reader who cited a dataset needs the same ID to keep resolving, even after a source changes its layout or stops publishing new rows.

Situation	What we do	Why
Dataset becomes stale	Keep the ID and label its pipeline `stale`	Past data and its provenance remain useful
Incompatible schema change	Publish a new ID with a suffix, such as `rw.nisr.cpi.monthly.v2`	Old code and citations keep their meaning
Add another country	Add that country’s prefix to new IDs	Existing IDs stay unchanged
Missing country prefix	Reject `nisr.cpi.monthly`	The country is required for a multi-country catalog

Turn an ID into a URL or table name

The API uses the ID unchanged in the download path. Iceberg table names replace dots with underscores, while hyphens remain and need SQL quoting.

rw.nisr.cpi.monthly
https://api.imibare.org/v1/data/rw.nisr.cpi.monthly/download

rw.minecofin.fiscal-operations.annual
"rw_minecofin_fiscal-operations_annual"