Skip to main content

Vehicles

Endpoints for managing vehicles.

Vehicle Integration​

Hiven integrates with an external partner called SmartCar in order to connect to vehicle.

In order to register a vehicle, you need to:

  1. Retrieve authorization URL.
  2. Redirect user to retrieved authorization URL and let the user provide credentials.
  3. Register a listener on a callback URL to receive authorization code.
  4. Send authorization code to Hiven.

Prerequisites​

Before starting registering vehicle, you need to send Hiven the redirectUri (URL you want SmartCar to redirect back after successful authentication) to be added to the whitelist.

Step 1: Retrieve Authorization URL​

GET /v1/hiven/devices/smartcar/authorization-url
X-Api-Key: <apiKey>
X-User-Id: <userId>

Query parameters

{
  "manufacturer": "<string>",
  "redirectUri": "<string>",
  "countryCode": "<string>",
  "mode": "<string>"
}
  • manufacturer - vehicle manufacturer

The list of supported vehicle manufacturers:

enum VehicleManufacturer {
  BMW = 'BMW',
  CITROEN = 'CITROEN',
  CUPRA = 'CUPRA',
  DS = 'DS',
  FORD = 'FORD',
  HYUNDAI = 'HYUNDAI',
  JAGUAR = 'JAGUAR',
  KIA = 'KIA',
  LAND_ROVER = 'LANDROVER',
  MINI = 'MINI',
  SKODA = 'SKODA',
  TESLA = 'TESLA',
  VOLKSWAGEN = 'VOLKSWAGEN',
}
  • redirectUri - URL you want SmartCar to redirect back after successful authentication. Once redirected, there will be a code property in query parameters which will be needed for the next step
  • countryCode - country code of the user (In ISO 3166-1 alpha-2 format, default value: FI)
  • mode - SmartCar mode (default value: live)

The list of supported SmartCar modes:

type VehicleAuthorizationMode = 'live' | 'test' | 'simulated';
  • live - production mode, requires users to use production credentials to add real vehicle
  • test - test mode, allows users to provide dummy credentials to add a test vehicle
  • simulated - simulated mode, requires users to use simulated credentials to add simulated vehicle

Response

{
  "authorizationUrl": "<string>"
}

Step 2: Redirect User to Authorization URL​

Example authorization URL:

https://connect.smartcar.com/oauth/authorize
      ?make=<make>&redirect_uri=<redirectUri>&response_type=code
      &flags=country:<countryCode>&mode=<mode>
      &scope=required:read_battery+required:read_charge+required:control_charge+required:read_vehicle_info+required:read_vin+read_location
      &single_select=true&client_id=<clientId>
  • make - vehicle manufacturer (providing this argument allows users to bypass the "Brand Selector" screen and lets the SmartCar know that we're targeting specific brand)
  • redirect_uri - redirect URI that will receive authorization code
  • response_type - defaults to: code to support "Authorization Code Flow"
  • flags - defaults to: country:<countryCode> to indicate that the vehicle belongs to specific country

If no flag is passed or set as default on Dashboard, SmartCar will use the devices IP to set an appropriate country. This flag determines what brands are listed on the "Brand Selector" screen.

  • mode - SmartCar mode, defaults to: live to indicate that the application is being used in production mode
  • scope - a space-separated list of permissions that Hiven is requesting access to

Permissions are optional by default (like: read_location), however it is possible to make them required by adding required:<permission> prefix (like: required:read_battery).

  • single_select - when true, prevents users from selecting multiple vehicles at the same time
  • client_id - application's unique identifier managed by Hiven

Redirect user to it and let the user provide credentials.

Step 3: Receive Authorization Code​

In the first step, you provided redirectUri parameter SmartCar should redirect to with the authorization code.

Make sure you have this route defined in your system, so as soon as it's hit, you can trigger the call to send authorization code to Hiven.

An additional query parameters will be attached to the defined redirectUri:

  • code - authorization code that should be exchanged to access token
  • virtual_key_url - optional parameter that is present only for Tesla due to its specific API (default value: https://www.tesla.com/_ak/smartcar.com)

Step 3.1: Tesla-Specific Virtual Keys​

Tesla requires Virtual Keys for 3rd-party applications in order to issue commands for the following models:

  • Model 3
  • Model Y
  • Model S (2021+)
  • Model X (2021+)

If you receive virtual_key_url in query parameters, you have to redirect users to its value, which will open Tesla mobile application on mobile or Tesla webpage on desktop.

Users would have to follow provided instructions.

Mobile:

  • Tesla application opens automatically and prompts users to add a Virtual Key

If Tesla app is not installed, user will be requested to install it first.

Desktop:

  • Tesla webpage opens automatically and users have to scan QR code which opens up Tesla application, which prompts users to add a Virtual Key

Step 4: Send Authorization Code To Hiven​

Read authorization code (code) from query parameters and send it to Hiven.

Hiven will take care of exchanging code to tokens and keeping the tokens up to date.

POST /v1/hiven/devices/smartcar/connect
X-Api-Key: <apiKey>
X-User-Id: <userId>

Payload

{
  "authCode": "<authCode>",
  "redirectUrl": "<redirectUrl>"
}
  • authCode - authorization code that should be exchanged to access token
  • redirectUrl - redirect url (should match the one passed to retrieve authorization URL)

Response

{
  "deviceId": "<string>",
  "message": "<string>"
}
  • deviceId - id of the newly added vehicle
  • message - information about registration state of the vehicle - whether it was already added to the system or not

Response Status Code

  • 200 - vehicle is already added to your account
  • 201 - vehicle has been successfully added
  • 409 - vehicle is already added to another user's account
  • 500 - internal server error

step 5: Validate start/stop capability - optional.​

Validation is useful to verify if vehicle is smart-charge capable without pairing a charger or when Tesla Virtual Key for 3rd-party was not granted.

Read more

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

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

DELETE Vehicle​

Remove vehicle from Hiven.

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

Response

""

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

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

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

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

GET Supported vehicle brands​

Retrieve supported vehicle brands list.

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

Response

["<string>"]

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