Skip to main content

Vehicles

Endpoints for managing vehicles.

Vehicle Integration​

In order to connect to the vehicle, Hiven integrates with 2 external partners:

GET Vehicles​

After the user has successfully added a vehicle to Hiven, you can retrieve a list of user's vehicles.

GET /v2/hiven/devices?userId=:userId
X-Api-Key: <apiKey>
X-User-Id: <userId>

Read more

client.getDevicesList(userId: string, options?: Options);

Read more

Response

[
  {
    "id": "<string>",
    "type": "<string>",
    "integration": "<string>",
    "associatedToCharger": "<boolean>",
    "associatedChargerIds": ["<string>"],
    "createdAt": "<string>",
    "attributes": {
      "partnerId": "<string>",
      "partnerName": "<string>",
      "externalId": "<string>",
      "userId": "<string>",
      "vin": "<string>",
      "manufacturer": "<string>",
      "year": "<number>",
      "model": "<string>",
      "name": "<string>",
      "deviceType": "<string>",
      "engineType": "<string>"
    },
    "settings": {
      "locationSupported": "<boolean>",
      "chargingPreferences": {
        "chargingBehavior": "<string>",
        "chargingLocationIds": ["<string>"], // Optional
        "chargingLocations": [
          {
            "coordinates": { "latitude": "<number>", "longitude": "<number>" },
            "countryCode": "<string>",
            "id": "<string>",
            "locationId": "<string>",
            "postalCode": "<string>",
            "spotPriceAreaId": "<string>"
          }
        ], // Optional
        "readyTime": "<string>", // Optional
        "weekDaySpecificReadyTimes": "<Record<Day, string>>", // Optional
        "targetSoC": {
          "value": "<number>",
          "unit": "<string>"
        }, // Optional
        "minimalSoC": {
          "value": "<number>",
          "unit": "<string>"
        }, // Optional
        "batteryCapacity": "<number>", // Optional
        "defaultSpotPriceAreaId": "<string>" // Optional
      }
    }
  }
]

Important note: This call returns also other device types (E.g. chargers) if they are added to Hiven, but they are documented separately.

  • type - device type, in case of vehicle always equals to EV
  • integration - device integration, in case of vehicle always equals to SMARTCAR
  • createdAt - device creation time (in UTC)

GET Vehicle Details​

Retrieve vehicle details.

GET /v2/hiven/devices/:vehicleId
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

{
  "id": "<string>",
  "type": "<string>",
  "integration": "<string>",
  "associatedToCharger": "<boolean>",
  "associatedChargerIds": ["<string>"],
  "createdAt": "<string>",
  "attributes": {
    "partnerId": "<string>",
    "partnerName": "<string>",
    "externalId": "<string>",
    "userId": "<string>",
    "vin": "<string>",
    "manufacturer": "<string>",
    "year": "<number>",
    "model": "<string>",
    "name": "<string>",
    "deviceType": "<string>",
    "engineType": "<string>"
  },
  "settings": {
    "locationSupported": "<boolean>",
    "chargingPreferences": {
      "chargingBehavior": "<string>",
      "chargingLocationIds": ["<string>"], // Optional
      "chargingLocations": [
        {
          "coordinates": { "latitude": "<number>", "longitude": "<number>" },
          "countryCode": "<string>",
          "id": "<string>",
          "locationId": "<string>",
          "postalCode": "<string>",
          "spotPriceAreaId": "<string>"
        }
      ], // Optional
      "readyTime": "<string>", // Optional
      "weekDaySpecificReadyTimes": "<Record<Day, string>>", // Optional
      "targetSoC": {
        "value": "<number>",
        "unit": "<string>"
      }, // Optional
      "minimalSoC": {
        "value": "<number>",
        "unit": "<string>"
      }, // Optional
      "batteryCapacity": "<number>", // Optional
      "defaultSpotPriceAreaId": "<string>" // Optional
    }
  }
}

Read more

client.getDeviceDetails(vehicleId: string, options?: Options);

Read more

DELETE Vehicle​

Remove vehicle from Hiven.

DELETE /v2/hiven/devices/:vehicleId
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

""

Read more

client.deleteDevice(vehicleId: string, options?: Options);

Read more

PUT Charging Preferences​

Set charging preferences to be used when creating smart charging session.

Important note: Even though it is PUT, it acts as a PATCH allowing partial updates.

PUT /v2/hiven/devices/:vehicleId/smart-charging/ev-preferences
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "chargingBehavior": "<string>",
  "chargingLocationIds": ["<string>"], // Optional
  "minimalSoC": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "targetSoC": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional if "chargingBehavior" is "SMART_CHARGE_OFF"
  "readyTime": "<string>", // Optional if "chargingBehavior" is "SMART_CHARGE_OFF"
  "weekDaySpecificReadyTimes": "<Record<Day, string>>", // Optional
  "batteryCapacity": "<number>", // Optional
  "defaultSpotPriceAreaId": "<string>" // Optional
}

  • chargingBehavior - charging session behavior

    • SMART_CHARGE_OFF - Smart Charging is disabled, the car will start charging immediately
    • SMART_CHARGE_AT_LOCATION - Smart Charging is enabled only in the location, earlier provided by user
    • SMART_CHARGE_ANYWHERE - Smart Charging is enabled in any location

  • chargingLocationIds - charging location ids configured for a given vehicle

Important note: To retrieve an id of a charging location, it must be created in Hiven. Follow the instructions here.

  • minimalSoC - minumum state of charge user wants the vehicle to have regardless of the electricity prices
    • value - numeric value for given unit
    • unit - state of charge unit (available values PERCENT or KM)
  • targetSoC - target state of charge user wants the vehicle to have after smart charging session is completed
    • value - numeric value for given unit
    • unit - state of charge unit (available values PERCENT or KM)
  • readyTime - time until when the charging session should be completed (in HH:mm local time format)
  • weekDaySpecificReadyTimes - time until when the charging session should be completed defined per each day of the week (in HH:mm local time format)

Important note: Either readyTime or weekDaySpecificReadyTimes should be set in order to properly calculate charging schedule. Both of them can be configured at the same time but when weekDaySpecificReadyTimes is specified, it will take precedence over the readyTime.

An example of readyTime:

{
  "readyTime": "08:00"
}

An example of weekDaySpecificReadyTimes:

{
  "weekDaySpecificReadyTimes": {
    "MONDAY": "08:00",
    "TUESDAY": "08:00",
    "WEDNESDAY": "08:00",
    "THURSDAY": "08:00",
    "FRIDAY": "08:00",
    "SATURDAY": "12:00",
    "SUNDAY": "18:00"
  }
}

Not all days of the week are required, you can skip some of them if needed.

In case if a day is skipped, Hiven will use readyTime value as a fallback.

  • batteryCapacity - battery capacity of a vehicle. It should be set when it's not returned on the telemetry

  • defaultSpotPriceAreaId - default spot price area system should use prices from to calculate smart charging schedule

Important note: This value is retrieved from a response of a call to create location in Hiven. Read more

Response

""

Read more

client.setVehiclePreferences(deviceId: string, preferences: VehiclePreferences, options?: Options);

Read more

GET Charging Preferences​

Retrieve charging preferences.

GET /v2/hiven/devices/:vehicleId/smart-charging/ev-preferences
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

{
  "chargingBehavior": "<string>",
  "chargingLocationIds": ["<string>"], // Optional
  "readyTime": "<string>", // Optional
  "weekDaySpecificReadyTimes": "<Record<Day, string>>", // Optional
  "targetSoC": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "minimalSoC": {
    "value": "<number>",
    "unit": "<string>"
  }, // Optional
  "batteryCapacity": "<number>", // Optional
  "defaultSpotPriceAreaId": "<string>" // Optional
}

Read more

client.getVehiclePreferences(deviceId: string, options?: Options);

Read more

GET Vehicle Status​

Retrieve vehicle telemetry.

GET /v1/hiven/devices/:vehicleId/status
X-Api-Key: <apiKey>
X-User-Id: <userId>

Response

{
  "id": "<string>",
  "timestamp": "<string>",
  "soc": "<number>",
  "range": "<number>",
  "chargingStatus": "<string>",
  "batteryCapacity": "<string>" | null
}

  • soc - vehicle's state of charge (always returned in %s)

  • chargingStatus - current charging status

    • CHARGING - vehicle is charging
    • NOT_CHARGING - vehicle is not charging
    • COMPLETE - charging is completed
    • DISCONNECTED - vehicle is disconnected
    • PLUGGED - vehicle is connected
    • CHARGING_COMPLETED - charging is completed

  • batteryCapacity - battery capacity of a vehicle. If it's not returned (has null value) - it should be provided to the system as vehicle preference

Read more

client.getVehicleStatus(vehicleId: string, options?: Options);

Read more

GET Vehicles With Capabilities​

Retrieve Vehicles with capabilities with option to filter vehicles that support and does not supported specific capabilities.

  • Capability - defined capabilities
    • READ_LOCATION - Read location capability
    • EXECUTE_START_AND_STOP - Execute start and stop operation capability
    • READ_BATTERY_CAPACITY - Read battery capacity
GET /v2/hiven/vehicles/smartcar/capabilities?supporting=:capability&not_supporting=:capability
X-Api-Key: <apiKey>

Response

[
  {
    "make": "<string>",
    "model": "<string>",
    "yearRange": {
      "start": "<number>",
      "end": "<number>"
    },
    "type": "<string>",
    "capabilities": ["<string>"]
  }
]
  • make - Vehicle manufacturer
  • model - Vehicle model
  • yearRange - Year range for model production
  • type - vehicle type - BEV, PHEV
  • capabilities - an array with Capability

Read more

client.getVehiclesWithCapabilities(supporting?: VehicleCapabilityType[], notSupporting?: VehicleCapabilityType[], options?: Options);

Read more

GET Supported vehicle brands​

Retrieve supported vehicle brands list.

GET /v2/hiven/vehicles/smartcar/makes
X-Api-Key: <apiKey>

Response

["<string>"]

Read more

client.getSupportedVehicleBrands(options?: Options);

Read more

GET Vehicle capabilities​

Retrieve current vehicle capabilities.

  • forceRefresh - Immediate refresh vehicle capabilities.
GET /v1/hiven/devices/smartcar/:vehicleId/capabilities?forceRefresh=:forceRefresh
X-Api-Key: <apiKey>

Response

["<string>"]

Read more

client.getVehicleCapabilities(deviceId: string, forceRefresh: boolean, options?: Options);

Read more