# Bill Detective

> Spot spikes, price changes and calculation errors across your utility bills. Enter several billing periods of an electricity, gas, water or data bill. Bill Detective normalises consumption per day, flags unusual periods (outliers), unit-price and standing-charge changes, and totals that do not add up, each with a plain-English explanation.

Part of usefulweb.site (https://usefulweb.site/). Results are deterministic calculations from the inputs and the listed assumptions; the API returns exactly what the web page shows.

## Use it
- Human interface: https://billdetective.usefulweb.site/ (interactive tool at https://billdetective.usefulweb.site/tool)
- JSON API: POST https://billdetective.usefulweb.site/api/v1/calculate with a JSON object of inputs (schema: https://billdetective.usefulweb.site/api/v1/tool)
- OpenAPI: https://billdetective.usefulweb.site/openapi.json
- MCP (Streamable HTTP): https://billdetective.usefulweb.site/mcp - tool `bill_detective`

## Inputs
- unit (select): Consumption unit
- currency (text): Currency
- changeThresholdPercent (number): Flag per-day change vs. previous period above
- outlierPercent (number): Flag periods above median by more than
- tolerancePercent (number): Arithmetic tolerance - Billed total may differ from consumption × unit price + charges by this much (rounding, taxes included in prices) before it is flagged.
- periods (table, required): Billing periods - Start and end dates are both counted as billing days. Fixed charge = total standing/base charge for the period. Leave Total billed empty to skip the arithmetic check for a row.

## Method
- Days = end date − start date + 1 (both dates count). Consumption per day = consumption ÷ days. Periods are sorted by start date.
- Computed total = consumption × unit price + fixed charge + other charges. A mismatch is flagged when |total billed − computed| > tolerance % × computed (minimum 0.01).
- Consumption change: per-day consumption vs. the previous period; flagged when the absolute change exceeds the threshold (default 25%).
- Above average: per-day consumption more than the threshold above the average of all periods.
- Outliers (IQR rule, only with ≥ 4 periods): per-day value above Q3 + 1.5 × IQR or below Q1 − 1.5 × IQR, quartiles by linear interpolation.
- Outliers (median rule): per-day value more than X% (default 30%) above the median per-day value.
- Unit price change: any change vs. the previous period. Fixed charge change: both the fixed charge per period and the fixed charge per day differ from the previous period by more than 1% (so a flat monthly fee over months of different length, or a fixed daily rate, is not flagged).
- Gaps and overlaps between consecutive periods are reported as information.