Water balance

Base URL: $BUSINESS_API

The object

scopestring · optional

one of system, dma

dma_idstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
statusstring · optional

one of computed, partial_data, insufficient_data

system_input_litersinteger · optional
billed_authorized_litersinteger · optional
unbilled_authorized_litersinteger · optional
authorized_consumption_litersinteger · optional
water_losses_litersinteger · optional
apparent_losses_litersinteger · optional · nullable
real_losses_litersinteger · optional · nullable
loss_splitstring · optional

one of computed_from_assumption, insufficient_data

apparent_loss_assumption_bpinteger · optional
non_revenue_water_litersinteger · optional
non_revenue_water_bpinteger · optional
dmas_totalinteger · optional
dmas_computedinteger · optional
dmasarray of IWAWaterBalance · optional
warningsarray of string · optional
The object
{
  "scope": "system",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "status": "computed",
  "system_input_liters": 1,
  "billed_authorized_liters": 1,
  "unbilled_authorized_liters": 1,
  "authorized_consumption_liters": 1342,
  "water_losses_liters": 1,
  "apparent_losses_liters": 1,
  "real_losses_liters": 1,
  "loss_split": "computed_from_assumption",
  "apparent_loss_assumption_bp": 1,
  "non_revenue_water_liters": 1,
  "non_revenue_water_bp": 1,
  "dmas_total": 125000,
  "dmas_computed": 1,
  "dmas": [],
  "warnings": [
    "warning"
  ]
}

IWA water balance for the whole system with per-DMA detail

Logs

GET /water-balance

Computes the IWA water balance for the whole network over a window by balancing every DMA and adding up those with enough data; the response includes the per-DMA detail, system input, billed and unbilled authorised consumption, water losses and non-revenue water. DMAs with insufficient data are excluded from the totals with a warning, and the status is computed, partial_data or insufficient_data accordingly. Water losses are split into apparent and real only when apparent_loss_bp is given. Read-only; requires network read access.

Parameters

fromstring · query · required

Required start of the window as an RFC 3339 timestamp; the window must end after it and span at most 366 days.

tostring · query · required

Required end of the window as an RFC 3339 timestamp, later than from.

apparent_loss_bpinteger · query · optional

Optional assumed apparent losses as basis points of authorised consumption, an integer from 0 to 10000 (100 = 1%); when omitted, losses are not split into apparent and real.

Returns

200 OK

Show attributes
scopestring · optional

one of system, dma

dma_idstring · optional
period_startstring (date-time) · optional
period_endstring (date-time) · optional
statusstring · optional

one of computed, partial_data, insufficient_data

system_input_litersinteger · optional
billed_authorized_litersinteger · optional
unbilled_authorized_litersinteger · optional
authorized_consumption_litersinteger · optional
water_losses_litersinteger · optional
apparent_losses_litersinteger · optional · nullable
real_losses_litersinteger · optional · nullable
loss_splitstring · optional

one of computed_from_assumption, insufficient_data

apparent_loss_assumption_bpinteger · optional
non_revenue_water_litersinteger · optional
non_revenue_water_bpinteger · optional
dmas_totalinteger · optional
dmas_computedinteger · optional
dmasarray of IWAWaterBalance · optional
warningsarray of string · optional

Errors 400 · 403

Permissions network:read · Roles: admin, analyst, field_reader, field_supervisor, operations, owner, viewer

curl -X GET "$BUSINESS_API/water-balance" \
  -H "Authorization: Bearer sk_test_..."
Response 200
{
  "scope": "system",
  "dma_id": "dma_2gE3tiwbLQQnDGcrVkstPO8Bjkg",
  "period_start": "2026-11-19T09:30:00Z",
  "period_end": "2026-11-19T09:30:00Z",
  "status": "computed",
  "system_input_liters": 1,
  "billed_authorized_liters": 1,
  "unbilled_authorized_liters": 1,
  "authorized_consumption_liters": 1342,
  "water_losses_liters": 1,
  "apparent_losses_liters": 1,
  "real_losses_liters": 1,
  "loss_split": "computed_from_assumption",
  "apparent_loss_assumption_bp": 1,
  "non_revenue_water_liters": 1,
  "non_revenue_water_bp": 1,
  "dmas_total": 125000,
  "dmas_computed": 1,
  "dmas": [],
  "warnings": [
    "warning"
  ]
}