JouloDocs
Api referenceEnergy

Find the cheapest time to charge

When to charge kwh most cheaply between now and ready_by, on the dynamic price of your supplier (the dynamic_eur_per_kwh of /prices, per 15 minutes). Three plans: flexible takes the cheapest slots wherever they fall (smart charging), block the cheapest stretch without a pause, now starts right away. kw is the power you give, else the 90th percentile of your sessions over 90 days (kw_source: own_sessions), else 11 kW (default). When the kWh do not fit, feasible is false and kwh_possible says what fits. Tomorrow's prices exist after the daily publication; until then prices_cover_deadline is false and the plans cover the known hours only. On a fixed contract the moment does not change what you pay. Requires the profile:read scope. The solar object is a fourth plan for users with solar panels. kWp comes from your household profile or solar_kwp. The place comes from place, or from your first postcode when the token holds locations:read. The forecast comes from Open-Meteo. Own solar counts at what feeding it in would pay. Until 1 January 2027 salderen makes that the price you pay, so the sun saves nothing yet (salderen_applies). From 2027 it saves energy tax, VAT and the markup. The house uses home_use_kw first (default 0.4 kW). available: false comes with a reason.

GET
/prices/cheapest-window
AuthorizationBearer <token>

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

In: header

Query Parameters

kwhnumber

kWh the car needs, 0.5 to 200.

ready_bystring

A clock time (07:00, its next occurrence in Amsterdam) or an ISO date-time, at most 7 days ahead. Past the published prices the plan uses the price forecast (uses_forecast).

max_kw?number

Charging power in kW, 1 to 50.

place?string

Postcode or place for the solar forecast. Default: your first postcode, with locations:read.

solar_kwp?number

Solar system size in kWp. Default: your household profile.

Range0.1 <= value <= 100
tilt?number

Panel tilt in degrees.

Default35
Range0 <= value <= 90
azimuth?number

Panel direction: 0 south, -90 east, 90 west.

Default0
Range-180 <= value <= 180
home_use_kw?number

What the house uses during the day, in kW.

Default0.4
Range0 <= value <= 10

Response Body

curl -X GET "https://api.joulo.nl/functions/v1/api/prices/cheapest-window?kwh=30&ready_by=07%3A00&max_kw=11&place=string&solar_kwp=0.1&tilt=35&azimuth=0&home_use_kw=0.4"
{
  "kwh": 30,
  "kw": 11,
  "kw_source": "own_sessions",
  "from": "2026-10-12T18:00:00.000Z",
  "ready_by": "2026-10-13T05:00:00.000Z",
  "prices_known_until": "2026-10-13T22:00:00+00:00",
  "prices_cover_deadline": true,
  "contract_type": "dynamic",
  "price_basis": "dynamic_eur_per_kwh",
  "feasible": true,
  "kwh_possible": 30,
  "flexible": {
    "windows": [
      {
        "start": "2026-10-13T01:00:00.000Z",
        "end": "2026-10-13T02:00:00.000Z",
        "kwh": 11,
        "avg_eur_per_kwh": 0.2214
      },
      {
        "start": "2026-10-13T02:30:00.000Z",
        "end": "2026-10-13T04:13:38.182Z",
        "kwh": 19,
        "avg_eur_per_kwh": 0.2187
      }
    ],
    "kwh": 30,
    "cost_eur": 6.59,
    "avg_eur_per_kwh": 0.2197
  },
  "block": {
    "windows": [
      {
        "start": "2026-10-13T01:00:00.000Z",
        "end": "2026-10-13T03:43:38.182Z",
        "kwh": 30,
        "avg_eur_per_kwh": 0.2231
      }
    ],
    "kwh": 30,
    "cost_eur": 6.69,
    "avg_eur_per_kwh": 0.2231
  },
  "now": {
    "windows": [
      {
        "start": "2026-10-12T18:00:00.000Z",
        "end": "2026-10-12T20:43:38.182Z",
        "kwh": 30,
        "avg_eur_per_kwh": 0.4122
      }
    ],
    "kwh": 30,
    "cost_eur": 12.37,
    "avg_eur_per_kwh": 0.4122
  },
  "saving_vs_now_eur": 5.78,
  "ere": {
    "net_eur_per_kwh": 0.1093,
    "value_eur": 3.28,
    "indicative": true
  }
}
{
  "error": "connection_type is required and must be \"ocpp\""
}
{
  "error": "Missing or invalid API token"
}
{
  "error": "Insufficient scope",
  "required_scope": "chargers:read"
}