API documentation

Every input feeding the predictor is exposed at a single endpoint as static JSON. Updated daily at the same time the underlying scrapes run. 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

Generated at build time and served as a static asset with Cache-Control: public, max-age=86400. The site rebuilds daily on the scrape cron, so the data is at most ~24 hours stale.

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.