Open data · /api/scenario.json

API documentation

Every input feeding the predictor is exposed at a single endpoint as static JSON. Rebuilt whenever the source scrapes commit new data (DWS publishes weekly; CCT publishes weekly on a different day). Each block in the response carries its own reportDate, so consumers should trust those dates rather than the time of the request. Licence: CC0 — use it however you like.

Endpoint

GET https://capetowndamlevels.co.za/api/scenario.json

Response shape

{
  "generatedAt": "2026-04-27T12:00:00.000Z",
  "license": "CC0-1.0",
  "documentation": "https://capetowndamlevels.co.za/predictor/api/",
  "methodology": "https://capetowndamlevels.co.za/predictor/methodology/",

  "initialCondition": {
    "reportDate": "2026-04-20",
    "combinedPct": 44.7,
    "fscMcm": 889.3,
    "source": "https://www.dws.gov.za/hydrology/Weekly/RiverSystems.aspx?river=CT"
  },

  "currentConsumption": {
    "reportDate": "2026-04-20",
    "mldPerDay": 859,
    "perPersonLpd": 147,
    "source": "https://resource.capetown.gov.za/.../damlevels.pdf"
  },

  "seasonalPattern": {
    "fscMl": 898221,
    "baselineConsumptionMld": 900,
    "monthly": [
      { "month": 1, "meanDeltaPct": -9.71, "stddevDeltaPct": 4.72, "n": 6 },
      ... 11 more months ...
    ],
    "sourceReadings": 148,
    "coverage": { "firstYear": 2017, "lastYear": 2026 }
  },

  "thresholds": {
    "dayZeroPct": 13.5,
    "severeRestrictionsPct": 20,
    "physicalFloorPct": 10,
    "framework": "Five-band drought response (CCT Weekly Dashboard)",
    "bands": [ ... 5 bands ... ]
  }
}

Field reference

initialCondition.combinedPct: Combined WCWSS storage as % of full storage capacity. Sourced daily from the South African Department of Water and Sanitation Cape Town river systems page.
currentConsumption.mldPerDay: Total daily water use across all sources in megalitres per day, as reported by the City of Cape Town Weekly Water Dashboard. Includes water provided to Stellenbosch and Drakenstein.
seasonalPattern.monthly[i].meanDeltaPct: Mean change in combined storage % from the start to end of month i+1, averaged across {coverage.firstYear}-{coverage.lastYear}. Negative = drawdown month, positive = recovery month.
seasonalPattern.monthly[i].stddevDeltaPct: Inter-year standard deviation of the same delta. Captures rainfall variability — high stddev = wide range of possible outcomes.
seasonalPattern.monthly[i].n: Number of year-pairs contributing to the mean and stddev for that month. Months with n < 3 are flagged in the build script as having low confidence.
thresholds.dayZeroPct: The City of Cape Town Water Outlook (January 2018) operational trigger for Day Zero. Always 13.5 unless the City revises the framework.

Caching & freshness

Generated at build time and served from Netlify's edge with Cache-Control: public, max-age=0, must-revalidate — the CDN holds the bytes but revalidates on each request, so a redeploy propagates immediately. The site rebuilds daily on the scrape cron, but the underlying source data updates at upstream cadence (DWS weekly, CCT weekly): use the per-block reportDate fields in the response to judge freshness rather than wall-clock time.

Licence

The compiled JSON is released under CC0-1.0 — public domain dedication. The underlying source data belongs to its respective publishers (DWS, City of Cape Town); please credit them when republishing.

← Back to predictor Methodology →