Configuring Solar-Aware Charge Planning

<aside> 🧪

Beta — Solar-Aware Charge Planning is currently in Beta. The fields and validation ranges below are stable for early-access integrators but may be extended before general availability.

</aside>

<aside> 💡

TL;DR: solar-aware charging needs accurate vehicle metadata (battery capacity, max charge power) and accurate inverter metadata (peak power, azimuth, tilt, cut-in threshold, base load). Both are set via the same device PATCH endpoint, one device at a time.

</aside>

For the feature overview and the data each side must provide, see Solar-Aware Charge Planning. This page covers the API mechanics — which fields you set on which device, what the valid ranges are, and how to verify the values you sent.

The endpoint and authentication pattern are the same as the existing device PATCH described in Gridio Connect API Endpoints and Device status and control:

curl -X PATCH <https://api.gridio.energy/api/v1/businesses/{business_id}/devices/{dev_id}> \
  -H "Authorization: Bearer <backend access token>" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

All fields below are optional — include only the ones you want to change in the request body, the rest retain their previous value.

🚗 Vehicle settings

Set these on a device of type Electric vehicle. When the underlying integration does not report the value (e.g. some OEMs don't expose battery capacity through their API), Gridio applies a default so smart charging still works; supplying the real value produces more accurate plans.

Parameter	Required for solar-aware	Description	Data type	Range	Default if omitted	Example value
`max_capacity`	Recommended	Battery capacity in watt-hours (Wh). Caps how much energy any plan can target.	int / float	1 000 – 300 000 (1 kWh – 300 kWh)	80 000 (80 kWh)	77 000
`max_charge_power`	Recommended	Maximum charge power in watts (W). Caps how much solar power per hour Gridio credits towards the vehicle.	int / float	1 000 – 350 000 (1 kW – 350 kW)	7 200 (7.2 kW)	11 000

Example — setting vehicle battery + charging characteristics

curl -X PATCH <https://api.gridio.energy/api/v1/businesses/{business_id}/devices/{dev_id}> \
  -H "Authorization: Bearer <backend access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "max_capacity": 77000,
    "max_charge_power": 11000
  }'

A 200 response and an empty body indicate success.

☀️ Inverter (PV) settings

Set these on a device of type Solar. The four geometry/sizing fields (solar_peak_power, solar_azimuth, solar_tilt, solar_start_level) describe the physical array and are what the forecast service uses to translate weather into expected PV power. The fifth (base_load) describes the rest of the household and is what the planner subtracts from forecasted PV before crediting hours to the vehicle.

Parameter	Required for solar-aware	Description	Data type	Range	Example value
`solar_peak_power`	✅	Nameplate DC peak power of the PV array in watts (W). Scales the irradiance forecast to expected output. Typical residential systems are between 3 000 (3 kWp) and 15 000 (15 kWp).	int	500 – 100 000 (0.5 kWp – 100 kWp)	8 400
`solar_azimuth`	✅	Compass direction the array faces, in degrees. 0 = North, 90 = East, 180 = South, 270 = West. In the northern hemisphere, south-facing (≈180) yields the highest annual output.	int	0 – 359	180
`solar_tilt`	✅	Tilt of the panels above horizontal, in degrees. 0 = flat (e.g. on a flat roof, lying flush), 90 = vertical (e.g. wall-mounted). For mid-latitudes (45–60° N) a typical roof pitch is 30–45.	int	0 – 90	35
`solar_start_level`	Recommended	Inverter cut-in threshold in watts (W). Forecasted production below this level is ignored when crediting solar hours — it filters out a trickle of dawn/dusk light that the inverter wouldn't actually use to power the car.	int / float	0 and up; typical 100–500	200
`base_load`	Recommended	Typical household base load in watts (W) — the average non-EV power draw at the site (fridge, standby devices, hot water, etc). Subtracted from forecasted PV before solar hours are credited to the vehicle, so the planner doesn't over-promise PV that's actually going to the house.	int	0 and up; typical 200–800	500

<aside> ⚡

Smart-meter-equipped sites: If the inverter is connected to a smart meter and reports to_grid / from_grid, the engine derives the household load directly from those readings and base_load is not used for the real-time excess-solar policy. The forecast-based next-day plan still uses base_load because real-time meter data isn't available for tomorrow.

</aside>

Example — setting up a typical 8.4 kWp south-facing array

curl -X PATCH <https://api.gridio.energy/api/v1/businesses/{business_id}/devices/{dev_id}> \
  -H "Authorization: Bearer <backend access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "solar_peak_power": 8400,
    "solar_azimuth": 180,
    "solar_tilt": 35,
    "solar_start_level": 200,
    "base_load": 500
  }'