JouloDocs
Api referenceEnergy

Compare your charging with other customers

Where you stand next to Joulo's other private customers. Your yearly home use is the kWh since your first charging session, scaled to a year with the seasonal pattern of all customers. It exists from 60 days of charging. It sits on the spread of customers with as many cars as your household profile says (compared_with is 1 or 2+), or of all private customers if you did not say (all). band places you on that spread. brand compares your median kWh per charging session over the last 28 days with customers of the same brand. summary says the same in one Dutch text. Fleet figures are medians from a weekly snapshot, never counts. A business account gets no comparison: compared_with is null. Requires the profile:read scope.

GET
/comparison
AuthorizationBearer <token>

API token from the Joulo dashboard, or an OAuth2 access token.

In: header

Response Body

curl -X GET "https://api.joulo.nl/functions/v1/api/comparison"
{
  "summary": "Jij: 7.006,3 kWh geladen sinds 2 januari 2026. Herrekend naar een jaar met het seizoenspatroon van alle klanten is dat ongeveer 8.800 kWh per jaar.\nJe gaf in je profiel twee auto's op. Daarom vergelijken we je met klanten met twee of meer auto's: de helft laadt tussen 3.800 kWh en 7.400 kWh per jaar, mediaan 5.600 kWh. Een op de tien laadt meer dan 9.500 kWh.\nJe hoort bij het kwart van de klanten met twee of meer auto's dat het meest laadt.",
  "first_session_date": "2026-01-02",
  "kwh_since_start": 7006.3,
  "kwh_per_year": 8800,
  "compared_with": "2+",
  "spread": {
    "p25": 3800,
    "p50": 5600,
    "p75": 7400,
    "p90": 9500
  },
  "band": "p75_p90",
  "median_all_customers": 4200,
  "kwh_per_session_median_28d": 5.1,
  "brand": {
    "name": "Tesla",
    "kwh_per_session_median": 16,
    "kwh_per_year_median": 4000
  },
  "charges_elsewhere": true
}
{
  "error": "Missing or invalid API token"
}
{
  "error": "Insufficient scope",
  "required_scope": "chargers:read"
}