insseption

JSON API + Python client for INSSE TEMPO-Online (Romania’s National Institute of Statistics).

• HTTP JSON API — open /api/v1/... in a browser; responses are indented application/json
• Python package — from insseption import Client
• UI — optional static frontend under / when deployed with nginx

Production target: https://insse.csaladen.es (ROEM AWS / Traefik)

INSSE reuse terms

Python client

Not on PyPI yet — install from GitHub (or a local checkout):

pip install "git+https://github.com/csaladenes/insseption.git"
# or, from a clone:
pip install .

from insseption import Client

with Client() as c:                       # https://insse.csaladen.es/api/v1
    print(c.health())
    print(c.context(lang="en")["nodes"][:3])
    meta = c.matrix("POP105A", lang="en")
    data = c.query("POP105A", lang="en")  # default totals / latest year
    print(data["columns"], data["row_count"])

Point at a local server:

Client("http://127.0.0.1:8787/api/v1")

CLI:

insseption --base-url http://127.0.0.1:8787/api/v1 health
insseption --base-url http://127.0.0.1:8787/api/v1 query POP105A

JSON API (/api/v1)

Interactive docs: /docs · OpenAPI: /openapi.json

Example in browser:

https://insse.csaladen.es/api/v1/matrices/POP105A/query?lang=en

POST body:

{
  "lang": "en",
  "selections": { "5": [4931], "1": [1] }
}

Run the API locally

python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[server]"
uvicorn insseption.main:app --host 127.0.0.1 --port 8787

Deploy (ROEM AWS Traefik stack)

Integrated into the existing covid19-romania compose (same pattern as fastapi):

• Host path: /home/ec2-user/covid19-romania/insseption/
• Service: insseption in docker-compose.yml
• Traefik: Host:insse.csaladen.es → :8787
• Networks: web + internal

# on ROEM
cd /home/ec2-user/covid19-romania
# edit/sync ./insseption (rsync --exclude .env) and ensure ./insseption/.env (OPENROUTER_API_KEY). Guide: https://insse.csaladen.es/docs
docker-compose up -d --build --no-deps insseption
curl -sS https://insse.csaladen.es/api/v1/health

Floating chat agent (separate container)

GEM-style NL agent in ./agent (OpenRouter → TEMPO via the JSON API). The agent container stays on the internal Docker network; the API reverse-proxies /agent/*:

# on ROEM (after syncing ./insseption/agent and compose service)
docker-compose up -d --build --no-deps insseption insseption-agent
curl -sS https://insse.csaladen.es/agent/health

Host smoke harness

# API + docs cite + chat.js + agent against production (or set INSSEPTION_HOST)
python3 scripts/harness.py
# lighter API-only check:
INSSEPTION_BASE=https://insse.csaladen.es/api/v1 python3 scripts/smoke.py

License

MIT — © Dénes Csala (GitHub). Hosted on ROEM (AWS / Traefik). Data remains subject to INSSE reuse terms.