Developer & Institutional Access

CERES API

Programmatic access to CERES predictions, hypotheses, and Admin1 signal data. Free for academic and humanitarian use. Institutional tiers available for organisations requiring higher volume or custom integration.

§ 1 — Access

Access Tiers

CERES API access is free for academic institutions and humanitarian organisations. All tiers share the same endpoints and data quality — the difference is rate limits and support.

Tier A
Open Research
Free
  • All prediction endpoints
  • All hypothesis data
  • Admin1 signal breakdown
  • 100 requests / day
  • Academic & NGO use
Tier B
Institutional
€500–2,000 / month
  • All Open Research features
  • 5,000 requests / day
  • Webhook alerts on Tier-I events
  • White-label PDF reports
  • Dedicated support
Tier C
Sovereign / Custom
Contact us
  • All Institutional features
  • Unlimited requests
  • Custom region coverage
  • Private deployment option
  • SLA & integration support

To request API access, email hello@northflow.no with your organisation name and intended use. Academic and humanitarian requests are approved within 48 hours.

§ 2 — Base URL

Connection

# Production
Base URL: https://ceres.northflow.no/api

# All endpoints require the version prefix
GET https://ceres.northflow.no/api/v1/predictions

# Authentication (Tier B/C)
Authorization: Bearer YOUR_API_KEY

# Open Research: no authentication required
GET https://ceres.northflow.no/api/v1/predictions
§ 3 — Endpoints

Predictions

GET/v1/predictionsAll active regional forecasts
# Returns all monitored regions with current forecast
GET /v1/predictions?tier=1&format=json

# Response
{
  "run_id": "CERES-20260228-160603",
  "generated_at": "2026-02-28T16:06:03Z",
  "horizon_days": 90,
  "predictions": [
    {
      "region_id": "SDN",
      "region_name": "Sudan",
      "p_ipc3_plus": 0.966,
      "ci_lower": 0.923,
      "ci_upper": 0.984,
      "tier": 1,
      "composite_stress": 0.51,
      "primary_driver": "conflict"
    }
  ]
}
GET/v1/predictions/{region_id}Single region detail
GET /v1/predictions/SDN

# Returns full prediction with hypothesis IDs
{
  "region_id": "SDN",
  "p_ipc3_plus": 0.966,
  "p_ipc4_plus": 0.676,
  "ci_lower": 0.923,
  "ci_upper": 0.984,
  "hypothesis_ids": ["H-SDN-001", "H-SDN-002", "H-SDN-003"]
}

Query Parameters

ParameterTypeDescription
tieroptionalFilter by tier: 1, 2, or 3
formatoptionaljson (default) or csv
run_idoptionalRetrieve a specific historical run

Hypotheses

GET/v1/hypotheses/{id}Full hypothesis with evidence records
GET /v1/hypotheses/H-SDN-001

{
  "id": "H-SDN-001",
  "region_id": "SDN",
  "rank": 1,
  "archetype": "conflict-driven",
  "confidence": 0.88,
  "text": "Armed conflict has severely disrupted agricultural labour...",
  "evidence": [
    {
      "source": "ACLED",
      "variable": "conflict_events_4wk",
      "observed": 312,
      "threshold": 50,
      "direction": "above",
      "verdict": "SUPPORTS"
    }
  ]
}

Admin1 Resolution

GET/v1/admin1/{country_id}Sub-national signal breakdown
GET /v1/admin1/ETH

# Returns Admin1 units for Ethiopia
{
  "country": "ETH",
  "units": [
    {
      "admin1_id": "ETH-OR",
      "name": "Oromia",
      "composite_stress": 0.61,
      "ipc_phase_current": 3,
      "signals": { "chirps": -1.8, "ndvi": -0.14 ... }
    }
  ]
}
§ 4 — Response Format

Response Format

All endpoints return JSON. Dates are ISO 8601. Probabilities are floats in [0, 1]. Confidence intervals are 90% bootstrap CIs.

# Standard envelope
{
  "run_id": "CERES-20260228-160603",
  "generated_at": "2026-02-28T16:06:03Z",
  "horizon_days": 90,
  "reference_date": "2026-02-28",
  "data": { ... }
}
# Error envelope
{
  "error": "region_not_found",
  "message": "Region XYZ is not currently monitored",
  "status": 404
}

All probabilities follow the same field pattern: p_ipc3plus_90d, ci_90_low, ci_90_high.

§ 5 — Attribution

Attribution Requirements

All use of CERES data — whether in publications, dashboards, or operational systems — requires attribution to Northflow Technologies and CERES.

# Required attribution string
"Source: CERES (Calibrated Early-warning & Risk Evaluation System),
 Northflow Technologies, 2026. ceres.northflow.no"

# For academic publications, also cite the methodology pre-print
"Northflow Technologies (2026). CERES: Calibrated Early-warning &
 Risk Evaluation System. arXiv:2026.XXXXX"

CERES predictions are provided under a Creative Commons Attribution 4.0 International licence (CC BY 4.0). Commercial use requires a Tier B or C agreement.