Docs

Getting the data

Every dataset is in the portal to explore and download, and in the API for your own systems and spreadsheets. Each record names its source, and each release says what changed.

Accounts are open by invitation during early access. Join early access to get one.

Your first call

1. Sign in at app.unmappedlabs.com, switch on the datasets you need, and create a key under API keys.
2. Ask for the latest exchange rates:

curl https://api.unmappedlabs.com/v1/datasets/reserve-bank-series/latest \
  -H "Authorization: Bearer um_live_your_key"

The answer is JSON: the dataset, its release version, and the records, each with its source.

Keys

Send your key in the Authorization header: Bearer um_live_…. Keys read the datasets your account has switched on, and you can have up to ten, so use one per system and revoke any that leak. For CSV only, a key can go in the address instead (?key=), because spreadsheets can’t send headers; make a separate key for those links.

Without code

In the portal, open a dataset’s Explore and download: filter it, see it as a table, download a CSV for Excel, or make a spreadsheet link that refreshes itself. See spreadsheets below.

Records and paging

GET /v1/datasets/{id}/records returns records a page at a time: 100 as JSON, up to 1,000 as CSV (?limit= asks for fewer). When there are more, the answer has a next link (and a Link header); follow it until next is null.

{
  "dataset": "dam-levels",
  "version": "2026-10-26",
  "count": 227,
  "offset": 0,
  "returned": 100,
  "records": [ … ],
  "next": "https://api.unmappedlabs.com/v1/datasets/dam-levels/records?cursor=…"
}

A next link stays on the release it started on, so a page-through never mixes two releases, even if new data arrives halfway. Time series come newest first.

Filters

Each dataset has its own filters (listed under datasets), and every one takes from and to dates. Combine them freely:

/v1/datasets/reserve-bank-series/records?currency=USD&from=2026-01-01
/v1/datasets/dam-levels/records?province=ZA-WC
/v1/datasets/electricity-tariffs/records?distributor=CPT&category=residential

An unknown parameter is an error that names the filters that work, so a typo never quietly returns everything.

Latest values

GET /v1/datasets/{id}/latest returns the newest record for each currency, rate, dam or tariff: often all a website, dashboard or quote needs. It takes the same filters.

CSV

Add .csv to records or latest (or ?format=csv). Nested values become columns: source.publisher, source.url. Where a record holds a list, such as a tariff’s charges, there’s one row per item, with the record’s own fields repeated. Files are UTF-8 with a byte-order mark, so Excel opens them correctly.

Spreadsheets and Power BI

Build the CSV address with your filters and a key, for example:

https://api.unmappedlabs.com/v1/datasets/reserve-bank-series/records.csv?currency=USD&from=2026-01-01&key=um_live_your_spreadsheet_key

• Google Sheets: in a cell, =IMPORTDATA("the address"). It refreshes about every hour.
• Excel: Data, then From Web, then paste the address. Refresh with Data, Refresh All. To keep the key out of the address, choose Advanced and add a header Authorization with Bearer um_live_…, and leave key off.
• Power BI: Get data, then Web, then the same address (or Advanced with the header).

The portal’s explorer makes these links for you. Every refresh counts towards your daily records, so filter to what you need.

Releases and changes

Data arrives in releases. GET /v1/datasets/{id}/releases lists them, newest first, with how many records each added, changed and removed. Datasets kept current by our daily jobs (rates, exchange rates, dam levels) release when their source has something new; others release as they’re built and checked.

Our promise for v1: changes only add things. We don’t rename or remove a field, endpoint or filter without telling key holders by email at least 90 days before and listing it here. The API is also described for tools at /v1/openapi.json (OpenAPI 3.1), which Postman and code generators read.

Limits

• Records a day: each account can read a set number of records a day across all its keys and the portal’s downloads. The headers X-Daily-Limit, X-Daily-Remaining and X-Daily-Reset say where you stand; it resets at 02:00 South African time.
• Requests a minute: up to 120 per key. Ask us if you need more.
• Use: the data is licensed for your own business and products, as the terms of use set out.

Errors

Every error is JSON: {"error": "…", "message": "…"}.

Code examples

Python, every US dollar rate this year:

import requests

url = "https://api.unmappedlabs.com/v1/datasets/reserve-bank-series/records"
params = {"currency": "USD", "from": "2026-01-01"}
headers = {"Authorization": "Bearer um_live_your_key"}
rows = []
while url:
    page = requests.get(url, params=params, headers=headers, timeout=30).json()
    rows += page["records"]
    url, params = page["next"], None  # the next link carries the filters

JavaScript, the latest level of every Western Cape dam:

const res = await fetch(
  "https://api.unmappedlabs.com/v1/datasets/dam-levels/latest?province=ZA-WC",
  { headers: { Authorization: "Bearer um_live_your_key" } }
);
const { records } = await res.json();
for (const d of records) console.log(d.dam, d.percent_full);

Datasets

The datasets with data so far. Every dataset on the plan is in the catalogue.

curl "https://api.unmappedlabs.com/v1/datasets/electricity-tariffs/records?distributor=CPT" \
  -H "Authorization: Bearer um_live_your_key"

curl "https://api.unmappedlabs.com/v1/datasets/dam-levels/records?station=D3R002" \
  -H "Authorization: Bearer um_live_your_key"

curl "https://api.unmappedlabs.com/v1/datasets/reference-rates/records?rate=prime_lending_rate" \
  -H "Authorization: Bearer um_live_your_key"

curl "https://api.unmappedlabs.com/v1/datasets/reserve-bank-series/records?currency=USD" \
  -H "Authorization: Bearer um_live_your_key"