Skip to main content

Smart Charging

Endpoints for retrieving current smart charging schedule and past smart charging sessions.

GET Charging Schedule​

Retrieve current charging schedule.

GET /v2/hiven/devices/:deviceId/smart-charging/schedule
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

{
  "id": "<string>",
  "createdAt": "<string>",
  "hourlyCharges": {
    "<string>": "<number>"
  },
  "spotPriceAreaId": "<string>",
  "readyTime": "<string>",
  "timeZone": "<string>"
}
  • createdAt - schedule creation time (in UTC)
  • hourlyCharges - an object containing datetime in UTC format as a key and a fraction of the hour when charging is going to happen:
"hourlyCharges": {
  "2024-03-22T10:00:00Z": 0.1, // 6 minutes of charging
  "2024-03-22T11:00:00Z": 1, // 60 minutes of charging
  // A few hours are skipped because charging is stopped
  "2024-03-22T21:00:00Z": 0.33, // 19.8 minutes of charging
  "2024-03-22T22:00:00Z": 1, // 60 minutes of charging
},
  • spotPriceAreaId - spot price area id which is used to retrieve electricity prices
  • readyTime - time until when the charging session should be completed (UTC timestamp)
  • timeZone - user's timezone needed in order to display schedule properly

Important note: Date times when charging is not going to happen are skipped.

Read more

GET Charging Session History​

Retrieve past charging sessions.

GET /v2/hiven/devices/:deviceId/smart-charging/sessions
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

[
  {
    "id": "<string>",
    "createdAt": "<string>",
    "hourlyCharges": {
      "<string>": "<number>"
    },
    "spotPriceAreaId": "<string>",
    "readyTime": "<string>",
    "timeZone": "<string>",
    "endDateTime": "<string>" | null,
    "status": "<string>"
  }
]
  • status - session status

All possible values:

  • ACTIVE - session is currently active
  • COMPLETE - session has been successfully completed
  • INTERRUPTED - session has been interrupted

Conditions:

"endDateTime" is "null"​

status field can't contain ACTIVE.

"endDateTime" is provided (not "null")​

status field equals to ACTIVE.

Read more

POST Start Immediate Charging​

Interrupt Smart Charging session to start charging immediately regardless of electricity prices.

GET /v2/hiven/devices/:deviceId/smart-charging/start-charging
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

""

Read more

POST Stop Immediate Charging​

Interrupt Smart Charging session to stop charging immediately.

GET /v2/hiven/devices/:deviceId/smart-charging/stop-charging
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

""

Read more

GET Device status from unified status endpoint.​

Retrieve device unified status.

GET /v2/hiven/status/:deviceId
X-Api-Key: <apiKey>

Response

{
"status": "<string>"
"timestamp": "<string>"
}

  • timestamp - last update date

  • status - current device status

    • CABLE_UNPLUGGED - Device charging cable unplugged.
    • CABLE_PLUGGED - Charger charging cable plugged.
    • CHARGING_COMPLETED - Regular charging completed.
    • CALCULATING_SCHEDULE - Calculating smart charging schedule, available when target SOC and current SOC level is known.
    • WAITING_FOR_SCHEDULED_CHARGING - Device is ready to charge, available when plugged and schedule exists.
    • SMART_CHARGING - Device is smart charging.
    • SMART_CHARGING_COMPLETED - Device smart charging is completed.
    • SMART_CHARGING_DISABLED - Device smart charging is disabled.
    • IMMEDIATE_CHARGING - Device immediate charging ongoing.
    • UNKNOWN - Device unknown status, not defined.
    • ERROR - Device error status.
    • CHARGING_CANCELLED - Device charging is cancelled.
    • INITIALIZATION - Vehicle initialization, OCPP devices are not supported right now.
    • NOT_REGISTERED - Device not registered in service or OCPP device initialization.
    • WAITING_FOR_CONNECTOR_STATE - Waiting for telemetry when no connector status is present.
    • OFFLINE - OCPP device offline state.
    • UNABLE_TO_CHARGE - For any OCPP state where charger cannot charge.

Read more