Developers

The calculator behind this site, as a free JSON API. Same engine, same tariffs, same answers.

Version 1.1.0
No API key
30 requests a minute
JSON or plain text
CORS enabled

Overview

Every page on this site calls one calculation engine. The API gives you that engine directly: send usage or a top-up amount, get back the answer, every price block behind it and a ready-made summary.

Base URL https://usmscalculator.brunei.app/api/v1. Amounts are in Brunei dollars. Results are estimates from the published tariffs, not a statement from USMS, DES or PWD. See the disclaimer.

One request

Quickstart

Ask for a household's monthly bill. No sign-up, nothing to install.

Request · curl

curl "https://usmscalculator.brunei.app/api/v1/calculate/bill?kwh=750&m3=40"

Response · 200 (trimmed)

{
  "calculator": "bill",
  "input": {
    "segment": "residential",
    "kwh": 750,
    "m3": 40,
    "months": 1,
    "kva": 140,
    "waterCategory": "02"
  },
  "title": "Residential bill",
  "headline": {
    "label": "Your bill",
    "value": 22.4,
    "unit": "B$",
    "caption": "per month"
  },
  "sentence": "Electricity B$18.00 for 750 kWh and water B$4.40 for 40 m³, each month.",
  "lines": [
    {
      "key": "electricity",
      "label": "Electricity",
      "amount": 18,
      "units": 750,
      "unit": "kWh",
      "start": 0,
      "blocks": [
        {
          "from": 0,
          "to": 600,
          "rate": 0.01,
          "units": 600,
          "cost": 6
        },
        "… 3 more blocks"
      ],
      "position": {
        "index": 1,
        "rate": 0.08,
        "toNext": 1250,
        "nextRate": 0.1
      }
    },
    {
      "key": "water",
      "label": "Water",
      "amount": 4.4,
      "units": 40,
      "unit": "m³",
      "start": 0,
      "blocks": [
        {
          "from": 0,
          "to": 54.54,
          "rate": 0.11,
          "units": 40,
          "cost": 4.4
        },
        "… 1 more blocks"
      ],
      "position": {
        "index": 0,
        "rate": 0.11,
        "toNext": 14.54,
        "nextRate": 0.44
      }
    }
  ],
  "facts": [],
  "assumptions": [
    "Estimate only. Meter rental, arrears and other charges are not included."
  ],
  "tariff": {
    "version": "brunei-1",
    "name": "Brunei Darussalam electricity and water tariffs",
    "currency": "BND",
    "sourceNote": "Electricity rates follow the Department of Electrical Services (DES) tariff page. For water, only the domestic rate for the first 54.54 m³ is printed in the Public Works Department (PWD) water facts; the other water rates were carried over from an earlier calculator. For education and self-estimation only. For official figures or enquiries, contact DES (electricity) or PWD (water)."
  },
  "summary": "Residential bill …"
}

Try it live

Endpoint

Monthly electricity and water bill

GETPOST/api/v1/calculate/bill

Send parameters in the query string, or as a JSON body with POST. All are optional; anything left out uses its default.

segmentstring
Customer type on the account
Default residentialAccepts residential · commercial
kwhnumber
Electricity used in one month, in kWh
Default 0Accepts 0 to 100,000
m3number
Water used in one month, in m³
Default 0Accepts 0 to 10,000
monthsnumber
Billing period to total: 1, 3, 6 or 12 months
Default 1
kvanumber
Subscribed capacity in kVA; commercial price blocks scale with it
Default 140Accepts 1 to 5,000Only for commercial
waterCategorystring
Commercial water category code (02 to 07); each has one flat rate per m³
Default 02Accepts 02 · 03 · 04 · 05 · 06 · 07Only for commercial

GET

curl "https://usmscalculator.brunei.app/api/v1/calculate/bill?kwh=750&m3=40"

POST

curl -X POST https://usmscalculator.brunei.app/api/v1/calculate/bill \
  -H "Content-Type: application/json" \
  -d '{"kwh":750,"m3":40}'

Example response

200 · application/json

{
  "calculator": "bill",
  "input": {
    "segment": "residential",
    "kwh": 750,
    "m3": 40,
    "months": 1,
    "kva": 140,
    "waterCategory": "02"
  },
  "title": "Residential bill",
  "headline": {
    "label": "Your bill",
    "value": 22.4,
    "unit": "B$",
    "caption": "per month"
  },
  "sentence": "Electricity B$18.00 for 750 kWh and water B$4.40 for 40 m³, each month.",
  "lines": [
    {
      "key": "electricity",
      "label": "Electricity",
      "amount": 18,
      "units": 750,
      "unit": "kWh",
      "start": 0,
      "blocks": [
        {
          "from": 0,
          "to": 600,
          "rate": 0.01,
          "units": 600,
          "cost": 6
        },
        {
          "from": 600,
          "to": 2000,
          "rate": 0.08,
          "units": 150,
          "cost": 12
        },
        {
          "from": 2000,
          "to": 4000,
          "rate": 0.1,
          "units": 0,
          "cost": 0
        },
        {
          "from": 4000,
          "to": null,
          "rate": 0.12,
          "units": 0,
          "cost": 0
        }
      ],
      "position": {
        "index": 1,
        "rate": 0.08,
        "toNext": 1250,
        "nextRate": 0.1
      }
    },
    {
      "key": "water",
      "label": "Water",
      "amount": 4.4,
      "units": 40,
      "unit": "m³",
      "start": 0,
      "blocks": [
        {
          "from": 0,
          "to": 54.54,
          "rate": 0.11,
          "units": 40,
          "cost": 4.4
        },
        {
          "from": 54.54,
          "to": null,
          "rate": 0.44,
          "units": 0,
          "cost": 0
        }
      ],
      "position": {
        "index": 0,
        "rate": 0.11,
        "toNext": 14.54,
        "nextRate": 0.44
      }
    }
  ],
  "facts": [],
  "assumptions": [
    "Estimate only. Meter rental, arrears and other charges are not included."
  ],
  "tariff": {
    "version": "brunei-1",
    "name": "Brunei Darussalam electricity and water tariffs",
    "currency": "BND",
    "sourceNote": "Electricity rates follow the Department of Electrical Services (DES) tariff page. For water, only the domestic rate for the first 54.54 m³ is printed in the Public Works Department (PWD) water facts; the other water rates were carried over from an earlier calculator. For education and self-estimation only. For official figures or enquiries, contact DES (electricity) or PWD (water)."
  },
  "summary": "Residential bill\nYour bill: B$22.40 per month\n\nElectricity B$18.00 for 750 kWh and water B$4.40 for 40 m³, each month.\n\nElectricity (750 kWh):\n  600 kWh × B$0.01 = B$6.00\n  150 kWh × B$0.08 = B$12.00\n  Your next kWh costs B$0.08. 1,250 kWh until B$0.10.\n\nWater (40 m³):\n  40 m³ × B$0.11 = B$4.40\n  Your next m³ costs B$0.11. 14.54 m³ until B$0.44.\n\nEstimate only. Check your bill or USMS app for exact charges. For official enquiries, contact DES (electricity) or PWD (water)."
}

Open in playground

Endpoint

Units bought by a prepaid top-up

GETPOST/api/v1/calculate/topup

Send parameters in the query string, or as a JSON body with POST. All are optional; anything left out uses its default.

segmentstring
Customer type on the account
Default residentialAccepts residential · commercial
utilitystring
Which prepaid meter the top-up is for
Default electricityAccepts electricity · water
amountnumber
Top-up amount in B$
Default 0Accepts 0 to 100,000
alreadynumber
B$ already topped up this month; cheaper blocks are used first
Default 0Accepts 0 to 100,000
kvanumber
Subscribed capacity in kVA; commercial price blocks scale with it
Default 140Accepts 1 to 5,000Only for commercial electricity
waterCategorystring
Commercial water category code (02 to 07); each has one flat rate per m³
Default 02Accepts 02 · 03 · 04 · 05 · 06 · 07Only for commercial water

GET

curl "https://usmscalculator.brunei.app/api/v1/calculate/topup?amount=20"

POST

curl -X POST https://usmscalculator.brunei.app/api/v1/calculate/topup \
  -H "Content-Type: application/json" \
  -d '{"amount":20}'

Example response

200 · application/json

{
  "calculator": "topup",
  "input": {
    "segment": "residential",
    "utility": "electricity",
    "amount": 20,
    "already": 0,
    "kva": 140,
    "waterCategory": "02"
  },
  "title": "Residential electricity top-up",
  "headline": {
    "label": "You get",
    "value": 775,
    "unit": "kWh",
    "caption": "for B$20.00 this month"
  },
  "sentence": "B$20.00 buys 775 kWh: 600 kWh at B$0.01 and 175 kWh at B$0.08.",
  "lines": [
    {
      "key": "electricity",
      "label": "Electricity",
      "amount": 20,
      "units": 775,
      "unit": "kWh",
      "start": 0,
      "blocks": [
        {
          "from": 0,
          "to": 600,
          "rate": 0.01,
          "units": 600,
          "cost": 6
        },
        {
          "from": 600,
          "to": 2000,
          "rate": 0.08,
          "units": 175,
          "cost": 14
        },
        {
          "from": 2000,
          "to": 4000,
          "rate": 0.1,
          "units": 0,
          "cost": 0
        },
        {
          "from": 4000,
          "to": null,
          "rate": 0.12,
          "units": 0,
          "cost": 0
        }
      ],
      "position": {
        "index": 1,
        "rate": 0.08,
        "toNext": 1225,
        "nextRate": 0.1
      }
    }
  ],
  "facts": [
    {
      "label": "Average price",
      "value": "B$0.0258 per kWh"
    },
    {
      "label": "Another B$5 would buy",
      "value": "62.5 kWh"
    }
  ],
  "assumptions": [
    "Tiered rates restart each month. Top-ups earlier in the month use up the cheaper blocks first.",
    "Assumes the whole top-up goes to usage, with no arrears or other deductions."
  ],
  "tariff": {
    "version": "brunei-1",
    "name": "Brunei Darussalam electricity and water tariffs",
    "currency": "BND",
    "sourceNote": "Electricity rates follow the Department of Electrical Services (DES) tariff page. For water, only the domestic rate for the first 54.54 m³ is printed in the Public Works Department (PWD) water facts; the other water rates were carried over from an earlier calculator. For education and self-estimation only. For official figures or enquiries, contact DES (electricity) or PWD (water)."
  },
  "summary": "Residential electricity top-up\nYou get: 775 kWh for B$20.00 this month\n\nB$20.00 buys 775 kWh: 600 kWh at B$0.01 and 175 kWh at B$0.08.\n\nElectricity (775 kWh):\n  600 kWh × B$0.01 = B$6.00\n  175 kWh × B$0.08 = B$14.00\n  Your next top-up buys kWh at B$0.08 each. 1,225 kWh until B$0.10.\n\nAverage price: B$0.0258 per kWh\nAnother B$5 would buy: 62.5 kWh\n\nEstimate only. Check your bill or USMS app for exact charges. For official enquiries, contact DES (electricity) or PWD (water)."
}

Open in playground

Endpoint

Monthly cost of charging an EV or plug-in hybrid at home

GETPOST/api/v1/calculate/ev

Send parameters in the query string, or as a JSON body with POST. All are optional; anything left out uses its default.

batteryKwhnumber
Battery size in kWh, from the car's spec sheet
Default 49.92Accepts 1 to 200
rangeKmnumber
Range on a full charge in km; for a plug-in hybrid, its electric-only range
Default 420Accepts 10 to 1,500
phevboolean
true for a plug-in hybrid: daily driving beyond the electric range runs on petrol
Default falseAccepts true · false
fuelLPer100kmnumber
Fuel use of a comparable petrol car in L/100 km; a plug-in hybrid uses it for its petrol km
Default 10Accepts 1 to 30
tankLnumber
Plug-in hybrids only: fuel tank size in litres, for fill-ups and total range
Default 50Accepts 5 to 80Only for plug-in hybrids (phev=true)
fromnumber
Battery % at the start of one charge
Default 20Accepts 0 to 99
tonumber
Battery % at the end of one charge; must be above from
Default 80Accepts 1 to 100
chargeEveryDaysnumber
Alternative to assuming the car starts every day fully charged: the days between charges. When set, a plug-in hybrid's electric driving is capped by what one charge from `from` to `to` supplies, and the result reports charges a month
OptionalAccepts 1 to 30
kmnumber
Distance driven in a month
Default 1000Accepts 0 to 20,000
householdKwhnumber
Household electricity a month without the car; sets the starting price block
Default 500Accepts 0 to 100,000
householdSpendnumber
Alternative to householdKwh: B$ spent on electricity a month without the car. When set, it is converted to kWh at residential rates and householdKwh is ignored
OptionalAccepts 0 to 100,000
petrolPricenumber
RON97 price per litre in B$
Default 0.53Accepts 0 to 10

GET

curl "https://usmscalculator.brunei.app/api/v1/calculate/ev?batteryKwh=49.92&rangeKm=420&km=1000"

POST

curl -X POST https://usmscalculator.brunei.app/api/v1/calculate/ev \
  -H "Content-Type: application/json" \
  -d '{"batteryKwh":49.92,"rangeKm":420,"km":1000}'

Example response

200 · application/json

{
  "calculator": "ev",
  "input": {
    "batteryKwh": 49.92,
    "rangeKm": 420,
    "phev": false,
    "fuelLPer100km": 10,
    "tankL": 50,
    "from": 20,
    "to": 80,
    "km": 1000,
    "householdKwh": 500,
    "petrolPrice": 0.53
  },
  "title": "Electric car (49.92 kWh, 420 km)",
  "headline": {
    "label": "Charging cost",
    "value": 3.46,
    "unit": "B$",
    "caption": "a month, added to your electricity bill",
    "note": "B$49.54 less than petrol",
    "noteTone": "good"
  },
  "sentence": "Driving 1,000 km a month in an electric car uses about 130.74 kWh and adds B$3.46 to your bill, B$49.54 less than petrol (B$53.00).",
  "lines": [
    {
      "key": "ev",
      "label": "EV charging",
      "amount": 3.46,
      "units": 130.74,
      "unit": "kWh",
      "start": 500,
      "blocks": [
        {
          "from": 0,
          "to": 600,
          "rate": 0.01,
          "units": 100,
          "cost": 1
        },
        {
          "from": 600,
          "to": 2000,
          "rate": 0.08,
          "units": 30.74,
          "cost": 2.46
        },
        {
          "from": 2000,
          "to": 4000,
          "rate": 0.1,
          "units": 0,
          "cost": 0
        },
        {
          "from": 4000,
          "to": null,
          "rate": 0.12,
          "units": 0,
          "cost": 0
        }
      ],
      "position": {
        "index": 1,
        "rate": 0.08,
        "toNext": 1369.26,
        "nextRate": 0.1
      }
    }
  ],
  "facts": [
    {
      "group": "Each month",
      "label": "Electricity bill without the car",
      "value": "B$5.00"
    },
    {
      "group": "Each month",
      "label": "Electricity bill with the car",
      "value": "B$8.46"
    },
    {
      "group": "Each month",
      "label": "Petrol car, same distance",
      "value": "B$53.00"
    },
    {
      "group": "One charge, 20% to 80%: 32.95 kWh, B$0.33",
      "label": "Home socket (2 kW)",
      "value": "16 h 28 min"
    },
    {
      "group": "One charge, 20% to 80%: 32.95 kWh, B$0.33",
      "label": "Single-phase wallbox (7 kW)",
      "value": "4 h 42 min"
    },
    {
      "group": "One charge, 20% to 80%: 32.95 kWh, B$0.33",
      "label": "Dual-phase wallbox (16 kW)",
      "value": "2 h 4 min"
    }
  ],
  "assumptions": [
    "Energy use of 11.9 kWh per 100 km, from the 49.92 kWh battery and 420 km range.",
    "Adds 10% for charging losses.",
    "Petrol comparison: a car using 10 L per 100 km of RON97 at B$0.53 per litre.",
    "Charging at home on the residential tariff, on top of your household usage."
  ],
  "tariff": {
    "version": "brunei-1",
    "name": "Brunei Darussalam electricity and water tariffs",
    "currency": "BND",
    "sourceNote": "Electricity rates follow the Department of Electrical Services (DES) tariff page. For water, only the domestic rate for the first 54.54 m³ is printed in the Public Works Department (PWD) water facts; the other water rates were carried over from an earlier calculator. For education and self-estimation only. For official figures or enquiries, contact DES (electricity) or PWD (water)."
  },
  "summary": "Electric car (49.92 kWh, 420 km)\nCharging cost: B$3.46 a month, added to your electricity bill\nB$49.54 less than petrol\n\nDriving 1,000 km a month in an electric car uses about 130.74 kWh and adds B$3.46 to your bill, B$49.54 less than petrol (B$53.00).\n\nEV charging (130.74 kWh):\n  100 kWh × B$0.01 = B$1.00\n  30.74 kWh × B$0.08 = B$2.46\n  Your next kWh costs B$0.08. 1,369.26 kWh until B$0.10.\n\nEach month:\n  Electricity bill without the car: B$5.00\n  Electricity bill with the car: B$8.46\n  Petrol car, same distance: B$53.00\n\nOne charge, 20% to 80%: 32.95 kWh, B$0.33:\n  Home socket (2 kW): 16 h 28 min\n  Single-phase wallbox (7 kW): 4 h 42 min\n  Dual-phase wallbox (16 kW): 2 h 4 min\n\nEstimate only. Check your bill or USMS app for exact charges. For official enquiries, contact DES (electricity) or PWD (water)."
}

Open in playground

Reference data

GET /tariffsEvery rate the calculators use, residential and commercial.
GET /ev-modelsBattery and range for common cars sold in Brunei, to fill in batteryKwh and rangeKm.
GET /openapi.jsonOpenAPI 3.1 description. Import it into Postman, Insomnia or a client generator.

Common car specs (12)

Battery and range for common cars
Car	batteryKwh	rangeKm	phev
BYD Atto 3	49.92	420	false
BYD Dolphin	60.4	420	false
BYD Seal	61.4	480	false
BYD Sealion 6	18.3	125	true
BYD Sealion 7 Performance	82	550	false
Proton E-Mas	70.1	480	false
Neta V	38.5	380	false
Neta U	62.7	460	false
Avatr 11	90	555	false
Kia EV9 AIR	76.1	450	false
Kia EV9 GT-Line	99.8	541	false
Kia EV6	77.4	528	false

Response format

Every calculator returns the same shape, so one renderer handles all three. Add format=text to get only the summary, as plain text.

calculator: Which calculator ran: bill, topup or ev.
input: Your input after defaults were filled in. Echo it back to show what was assumed.
headline: The answer: label, value, unit and a caption. Show this first.
sentence: The answer as one plain sentence.
lines[]: One per utility, with every price block: units, rate and cost. start is what was already used this month before the line (0 on a bill, earlier top-ups on a top-up, the household's own use for an EV), so the line covers start to start + units. Use it to draw a breakdown or a chart.
facts[]: Extra figures as label and value pairs, sometimes grouped.
assumptions[]: What the estimate takes for granted. Show it near the result.
tariff: Tariff name, currency and version (now brunei-1). The version changes when rates do.
summary: Everything above as ready-to-send plain text, for chat apps and emails.

Changes

Fields are only ever added. Nothing has been removed or renamed.

1.1.0Added lines[].start, so a line can be drawn in the right place on the price ladder.
1.0.0First release.

Errors

Errors always name the field at fault and say what to send instead, in words you can show a user as-is.

400
Body is not a JSON object
{ "error": { "field": "body", "message": "Send a JSON object" } }
404
Unknown calculator in the path
{ "error": { "field": "calculator", "message": "Use bill, topup or ev" } }
422
A value is out of range or the wrong type
See the example below
429
More than 30 requests a minute
{ "error": { "field": "rate", "message": "Too many requests" } }

422 · kwh=-5

{
  "error": {
    "field": "kwh",
    "message": "Enter 0 to 100,000 kWh"
  },
  "errors": [
    {
      "field": "kwh",
      "message": "Enter 0 to 100,000 kWh"
    }
  ]
}

Limits and caching

30 requests a minute per IP. Over that you get a 429 with a Retry-After header in seconds.
GET responses are cached for an hour in browsers and a day at the edge. Results only change when the tariffs do. POST is never cached.

Live

Try it

Edit the parameters and send a real request to this site's API. Blank fields use their defaults.

curl "https://usmscalculator.brunei.app/api/v1/calculate/bill?kwh=750&m3=40"

200Example response. Press Send to run it live.

{
  "calculator": "bill",
  "input": {
    "segment": "residential",
    "kwh": 750,
    "m3": 40,
    "months": 1,
    "kva": 140,
    "waterCategory": "02"
  },
  "title": "Residential bill",
  "headline": {
    "label": "Your bill",
    "value": 22.4,
    "unit": "B$",
    "caption": "per month"
  },
  "sentence": "Electricity B$18.00 for 750 kWh and water B$4.40 for 40 m³, each month.",
  "lines": [
    {
      "key": "electricity",
      "label": "Electricity",
      "amount": 18,
      "units": 750,
      "unit": "kWh",
      "start": 0,
      "blocks": [
        {
          "from": 0,
          "to": 600,
          "rate": 0.01,
          "units": 600,
          "cost": 6
        },
        {
          "from": 600,
          "to": 2000,
          "rate": 0.08,
          "units": 150,
          "cost": 12
        },
        {
          "from": 2000,
          "to": 4000,
          "rate": 0.1,
          "units": 0,
          "cost": 0
        },
        {
          "from": 4000,
          "to": null,
          "rate": 0.12,
          "units": 0,
          "cost": 0
        }
      ],
      "position": {
        "index": 1,
        "rate": 0.08,
        "toNext": 1250,
        "nextRate": 0.1
      }
    },
    {
      "key": "water",
      "label": "Water",
      "amount": 4.4,
      "units": 40,
      "unit": "m³",
      "start": 0,
      "blocks": [
        {
          "from": 0,
          "to": 54.54,
          "rate": 0.11,
          "units": 40,
          "cost": 4.4
        },
        {
          "from": 54.54,
          "to": null,
          "rate": 0.44,
          "units": 0,
          "cost": 0
        }
      ],
      "position": {
        "index": 0,
        "rate": 0.11,
        "toNext": 14.54,
        "nextRate": 0.44
      }
    }
  ],
  "facts": [],
  "assumptions": [
    "Estimate only. Meter rental, arrears and other charges are not included."
  ],
  "tariff": {
    "version": "brunei-1",
    "name": "Brunei Darussalam electricity and water tariffs",
    "currency": "BND",
    "sourceNote": "Electricity rates follow the Department of Electrical Services (DES) tariff page. For water, only the domestic rate for the first 54.54 m³ is printed in the Public Works Department (PWD) water facts; the other water rates were carried over from an earlier calculator. For education and self-estimation only. For official figures or enquiries, contact DES (electricity) or PWD (water)."
  },
  "summary": "Residential bill\nYour bill: B$22.40 per month\n\nElectricity B$18.00 for 750 kWh and water B$4.40 for 40 m³, each month.\n\nElectricity (750 kWh):\n  600 kWh × B$0.01 = B$6.00\n  150 kWh × B$0.08 = B$12.00\n  Your next kWh costs B$0.08. 1,250 kWh until B$0.10.\n\nWater (40 m³):\n  40 m³ × B$0.11 = B$4.40\n  Your next m³ costs B$0.11. 14.54 m³ until B$0.44.\n\nEstimate only. Check your bill or USMS app for exact charges. For official enquiries, contact DES (electricity) or PWD (water)."
}

Building something with it? How API requests are handled