REST API

Use the REST API when you want imibare data from any language or tool that can make HTTP requests. The base URL is https://api.imibare.org; every route begins with /v1/, returns JSON unless it downloads a file, allows cross-origin requests, and needs no authentication.

Choose an endpoint

The API separates discovery from data transfer so you do not need to download a whole dataset just to learn its columns. Start with the endpoint that matches the job you have to do.

List datasets

GET /v1/datasets returns all published dataset records. Add query parameters to narrow the list before you decide which ID to download.

A successful response has a datasets list and a meta object. meta.total is the number of records after filtering, while meta.filters echoes the filters the request used.

# Every published dataset
curl https://api.imibare.org/v1/datasets

# Kenyan datasets
curl "https://api.imibare.org/v1/datasets?country=KE"

# Monthly price datasets
curl "https://api.imibare.org/v1/datasets?topic=prices&frequency=monthly"

Inspect a dataset

GET /v1/datasets/{id} returns the complete current record for 1 dataset. Use it before analysis when you need the publisher’s source link, the column definitions, or the version you are citing.

GET /v1/datasets/rw.nisr.cpi.monthly

Read the record

last_updated and last_checked are deliberately different. A source can be checked today without publishing new data, and treating the check date as an update would make the record misleading.

A missing ID returns 404 Not Found with an error field. The record may also include catalog-page presentation fields, such as finding, which can change without altering the data.

curl https://api.imibare.org/v1/datasets/rw.nisr.cpi.monthly

Download the current file

GET /v1/data/{id}/download streams the latest published version. Use it for an analysis or a local archive, because /preview is designed for inspection rather than bulk transfer.

The default Parquet response is application/octet-stream, CSV is text/csv, and JSON is application/json. Every download carries an ETag, so send it in If-None-Match when you want the server to reply 304 Not Modified without another file transfer.

# Latest Parquet file
curl -L -o rw.nisr.cpi.monthly.parquet "https://api.imibare.org/v1/data/rw.nisr.cpi.monthly/download"

# Current CSV file
curl -L -o cpi.csv "https://api.imibare.org/v1/data/rw.nisr.cpi.monthly/download?format=csv"

An unsupported format returns 400 Bad Request with the requested format and the allowed formats. An unknown dataset, or a known dataset without published rows, returns 404 Not Found with an error field and, where available, the dataset_id.

Preview and filter rows

GET /v1/data/{id}/preview returns the latest rows as JSON. Use it for a chart, a small inspection, or a filtered result; use the download route when you need the entire dataset.

A row response contains id, rows, count, total, offset, and limit. count is the size of this page, while total is the number of rows that matched before pagination.

# The first 2 rows of the general CPI series
curl "https://api.imibare.org/v1/data/rw.nisr.cpi.monthly/preview?category=general_index_(cpi)&limit=2"

# Every category used by CPI
curl "https://api.imibare.org/v1/data/rw.nisr.cpi.monthly/preview?distinct=category"

With distinct, the response replaces rows with values and reports their count. A filter or distinct column that the dataset does not have returns 400 Bad Request and names the available filterable columns.

Search the catalog

GET /v1/search performs case-insensitive full-text search. Pass a non-empty q parameter, and we search dataset IDs, names, country codes and names, institutions, topics, notes, and tags.

curl "https://api.imibare.org/v1/search?q=exchange+rate"

A successful response contains results, the original query, and total. Each result is a compact dataset record with its ID, name, country, institution, topic, frequency, and pipeline state.

A request without q returns 400 Bad Request with {"error": "q parameter is required"}. Search is for discovery, so use GET /v1/datasets/{id} after you choose a result.

Check pipeline status

GET /v1/status reports the health of scheduled scrapers over a rolling window. It powers the status page, but it is useful in automated checks too.

uptime_pct measures whether the source could be read on schedule, not whether the API itself was available. Read incidents when a series changes unexpectedly, because the note may explain a source correction or interrupted run.

Handle errors, caching, and limits

All errors use JSON with an error field and may add context such as dataset_id. The status code tells you whether to change your request, choose another dataset, or retry later.

Successful catalog and data responses are cacheable for up to 1 hour. Errors are never cached, and the status response uses its own shorter cache policy because the state can change more quickly.

The API is public infrastructure, so download a file once and cache it rather than paging through /preview for a full dataset. We may rate-limit sustained heavy traffic to keep the service useful for everyone.