API reference

AfriRate API

One REST endpoint per dataset. JSON in, JSON out. Same shape across all 6 countries. Free tier is 60 req/min, 300 req/day — enough for most apps without billing.

Authentication

Every /api/v1/* endpoint requires a key. Create one on the dashboard after signing in. Pass it either way:

Authorization: Bearer ar_xxxxxxxxxxxxxxxxxxxxxxxx

# or as a query param
?api_key=ar_xxxxxxxxxxxxxxxxxxxxxxxx

Header form is preferred — query params leak into logs and browser history.

Base URL

https://afrirate.statotec.com/api/v1/

All endpoints below are relative to this base. HTTPS only.

Errors

Errors use a consistent envelope.

{
  "error": {
    "code": "rate_limited",
    "message": "Daily request limit (300) reached. Upgrade or wait until UTC midnight.",
    "status": 429
  },
  "meta": { "timestamp": "2026-05-17T10:00:00Z" }
}

Status	Code	Meaning
400	`bad_request`	Missing or invalid parameter.
401	`unauthorized`	Missing or invalid API key.
403	`forbidden`	Key revoked or account disabled.
404	`not_found`	No data for the requested filter (e.g. inflation for a country whose source doesn't publish it).
429	`rate_limited`	Daily or per-minute limit hit.
500	`internal`	Something went wrong on our side. Retry; if persistent, file an issue.

Rate limits

Free tier: 60 requests / minute, 300 / day. Premium plans raise both — see pricing.

Every response carries:

X-RateLimit-Limit:        60
X-RateLimit-Remaining:    57
X-RateLimit-Reset:        1779000420
X-Daily-Limit:           300
X-Daily-Remaining:       293

GET/api/v1/rates/latest

Latest exchange rates, filterable by country and/or pair.

Parameter	Required	Description
country	optional	ISO 3166-1 alpha-2 country code. · e.g. `ZW`
base	optional	ISO 4217 base currency code. · e.g. `USD`
quote	optional	ISO 4217 quote currency code. · e.g. `ZWG`

Example request

curl "https://afrirate.statotec.com/api/v1/rates/latest?country=ZW&base=USD&quote=ZWG" \
  -H "Authorization: Bearer ar_xxx..."

Example response

{
  "data": [
    {
      "source": "rbz",
      "country": "ZW",
      "base": "USD",
      "quote": "ZWG",
      "rate": "25.8135",
      "bid":  "25.1682",
      "ask":  "26.4588",
      "rate_date":  "2026-05-15",
      "scraped_at": "2026-05-15T08:14:22Z"
    }
  ],
  "meta": { "timestamp": "2026-05-17T10:00:00Z", "count": 1 }
}

GET/api/v1/inflation/latest

Latest inflation figures for a country. Only countries whose central bank publishes inflation will return rows.

Parameter	Required	Description
country	required	ISO 3166-1 alpha-2 country code. · e.g. `ZW`

Example request

curl "https://afrirate.statotec.com/api/v1/inflation/latest?country=ZW" \
  -H "Authorization: Bearer ar_xxx..."

Example response

{
  "data": [
    {
      "source": "rbz",
      "country": "ZW",
      "denomination": "USD",
      "period_date": "2026-04-01",
      "mom": "1.06",
      "yoy": "2.16",
      "cpi_index": "124.76"
    }
  ],
  "meta": { "timestamp": "2026-05-17T10:00:00Z", "count": 1 }
}

GET/api/v1/gold/latest

Latest central-bank gold-coin prices. Currently only RBZ (Zimbabwe).

Parameter	Required	Description
country	required	ISO 3166-1 alpha-2 country code. · e.g. `ZW`

Example request

curl "https://afrirate.statotec.com/api/v1/gold/latest?country=ZW" \
  -H "Authorization: Bearer ar_xxx..."

Example response

{
  "data": [
    {
      "source": "rbz",
      "country": "ZW",
      "product": "mosi_oa_tunya",
      "priced_in": "USD",
      "selling_price": "4805.64",
      "prev_pm_fix":  "4576.80",
      "price_date":   "2026-04-06"
    }
  ],
  "meta": { "timestamp": "2026-05-17T10:00:00Z", "count": 1 }
}

GET/api/v1/countries

List every country AfriRate covers, with its local currency and slug.

Example request

curl "https://afrirate.statotec.com/api/v1/countries" \
  -H "Authorization: Bearer ar_xxx..."

Example response

{
  "data": [
    { "code": "ZW", "slug": "zimbabwe",     "name": "Zimbabwe",     "currency": "ZWG" },
    { "code": "ZA", "slug": "south-africa", "name": "South Africa", "currency": "ZAR" },
    ...
  ],
  "meta": { "timestamp": "2026-05-17T10:00:00Z", "count": 6 }
}

GET/api/v1/health

Service health probe. Public, no key required. Returns 200 with current scrape health per source.

Example request

curl "https://afrirate.statotec.com/api/v1/health" \
  -H "Authorization: Bearer ar_xxx..."

Example response

{
  "status": "ok",
  "sources": [
    { "code": "sarb", "country": "ZA", "last_success_at": "2026-05-17T18:00:11Z", "consecutive_failures": 0 },
    ...
  ]
}