for your information

For developers

A clean REST API, typed SDKs, an OpenAPI spec, and a CLI that pipes cleanly into jq. No magic, no SDK lock-in.

Get your API key OpenAPI docs →

The API in 30 seconds

All endpoints under https://api.eolas.fyi. Authentication is X-API-Key.

GET /v1/datasets

List every dataset with title, source, namespace, description. No auth required.

GET /v1/datasets/{name}

Metadata for one dataset. No auth required.

GET /v1/datasets/{name}/data 🔑

Stream rows. Query params: start, end, limit, format (json/csv), dimensions.

GET /v1/datasets/{name}/preview

First 10 rows, no auth. Useful for catalog UIs and schema introspection.

# Quick taste
curl -H "X-API-Key: $EOLAS_API_KEY" \
  "https://api.eolas.fyi/v1/datasets/nz_cpi/data?start=2020-01-01&limit=5"

Full reference + try-it-now at api.eolas.fyi/docs (Swagger UI).

SDKs

Typed, documented, drift-detected. Source on GitHub.

🐍

Python — `eolas-data`

pip install eolas-data
from eolas_data import Client
c = Client("your_key")
df = c.get("nz_cpi", start="2020-01-01")

· Literal[...] autocomplete on dataset names
· Optional [polars], [geo], [plot]
· Auto-converts geospatial datasets to GeoDataFrame

PyPI ↗ GitHub ↗ Docs ↗

📊

R — `eolas`

remotes::install_github("phildonovan/eolas-r")
library(eolas)
eolas_key("your_key")
df <- eolas_get("nz_cpi", start = "2020-01-01")

· Per-source helpers: eolas_get_statsnz() etc.
· eolas_plot() returns a ggplot2 object
· Auto-converts geospatial to sf when available

GitHub ↗ Docs ↗

Building in another language? The OpenAPI spec at /openapi.json generates SDKs for ~30 languages via openapi-generator.

CLI — for shell scripts & agents

Same package, plus an eolas binary. Auto-detects piping: rich tables interactive, NDJSON when piped.

pip install eolas-data[cli]
eolas auth set-key
eolas health

# Discover
eolas datasets list --source "Stats NZ" --json | jq '.[].name'
eolas datasets info nz_cpi

# Fetch
eolas get nz_cpi --format csv --out cpi.csv
eolas get nz_cpi --start 2020-01-01 --format json | jq '.[].value'

# Schedule (cron / Task Scheduler)
eolas schedule add nz_cpi --daily --out ~/data/cpi.csv
eolas schedule list

Distinct exit codes per error class (auth=2, rate-limit=3, not-found=4) for clean shell-script integration.

Rate limits & errors

Status	Meaning	Action
`200`	OK	—
`401`	Missing / invalid API key	Check `X-API-Key` header
`403`	Key inactive, or Enterprise endpoint without Enterprise plan	Reactivate / upgrade
`404`	Dataset name doesn't exist	`GET /v1/datasets` for current names
`429`	Monthly quota exhausted	Upgrade plan, or wait for next month
`5xx`	Server error	Retry with backoff; check status

Row caps (50,000 on Free/Starter) are signalled in the X-Plan-Row-Cap response header. Quota remaining is in X-RateLimit-Remaining.

Build something

Free tier is 10 requests/month — enough to wire up a prototype.

Get your API key