Get Vehicle State Of Health

curl --request GET \
  --url https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "vehicleId": "<string>",
  "calculationDate": "2023-12-25",
  "stateOfHealth": "<string>",
  "batteryCapacity": {
    "nominal": "<string>",
    "real": "<string>"
  },
  "measuredDate": "2023-12-25"
}

Vehicle State of Health

Get Vehicle State Of Health

Retrieves state of health related information for the specified vehicle.

Nominal battery pack capacity refers to the total amount of energy in kWh that the battery pack of the vehicle can store, as per its specifications.
Real battery pack capacity refers to the total amount of energy in kWh that the battery pack of the vehicle can currently store, it’s reflective of the actual state of the battery rather than a specification.
State of health is defined as real battery pack capacity over nominal battery pack capacity, as percentage.

Where the figure comes from:

For most vehicles it is our own estimate, calculated from the vehicle’s charging data.
For Tesla, and for the newer Kia electric models, the manufacturer’s own reading of the battery’s state of health is preferred and served while it is current. If no manufacturer reading is available (for example Tesla’s could not be fetched and its validity period has passed) the response falls back to our estimate; the response does not state which source it is, though a present measured_date indicates a manufacturer reading.
For a manufacturer reading the percentage is the manufacturer’s figure and the two capacities are kept on the same basis, so real / nominal equals the percentage. Kia reports its rated pack capacity, used as nominal. Tesla reports its current usable capacity, used as real; nominal is the as-new usable capacity that implies (real divided by the percentage), which is lower than the pack’s published gross capacity.

Dates:

calculation_date is when we recorded the figure.
measured_date is when the manufacturer measured the battery, for a manufacturer-reported figure whose measurement time is known (Kia today). It is absent for our own estimates, which are measured when calculated, and for manufacturer-reported figures whose measurement time is not supplied. Manufacturers refresh their reading infrequently, so measured_date can be well before calculation_date.

Parameters:

vehicle_id: A unique identifier for the vehicle, which must correspond to a vehicle registered in our system.

Returns:

A vehicle state of health instance encapsulating detailed battery pack information for the vehicle. The data includes both the nominal battery pack capacity and the real (observed) maximum battery pack capacity based on data retrieved directly from the vehicle and the specifications published by the OEMs.

Errors:

A 404 Not Found response is returned when the system cannot locate the vehicle’s state of health details, due to an invalid vehicle_id or absence of battery data.

Note (our own estimate):

Endpoint is first available after observing a charging session that added at least 15% of state of charge and was started above 20% state of charge.
We recommend charging the vehicle overnight should the endpoint not be available immediately.
The estimate is reliant on the availability of the trim of the vehicle and is not available for every OEM. Please see state of health for a list of supported OEMs
Identifying the trim requires the registration country of the vehicle to be known and to be one we hold specification data for, currently Canada, France, Germany, Ireland, Italy, Spain, the United Kingdom, and the United States. Vehicles registered elsewhere may not have state of health available.
Manufacturer-reported figures do not depend on a charging session or on the trim being identified.

Possible Codes in Error Response (see Errors for error response schema and meaning of codes):

AUTHENTICATION_ERROR
REQUEST_VALIDATION_ERROR
RESOURCE_NOT_FOUND
SERVER_ERROR

GET

vehicles

{vehicle_id}

state-of-health

Get Vehicle State Of Health

curl --request GET \
  --url https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.volteras.com/v1/vehicles/{vehicle_id}/state-of-health")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "vehicleId": "<string>",
  "calculationDate": "2023-12-25",
  "stateOfHealth": "<string>",
  "batteryCapacity": {
    "nominal": "<string>",
    "real": "<string>"
  },
  "measuredDate": "2023-12-25"
}

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

Path Parameters

vehicle_id

string

required

Unique internal identifier for the vehicle.

Response

200 - application/json

Successful Response

vehicleId

string

required

calculationDate

string<date>

required

The date we recorded the figure.

stateOfHealth

string | null

required

Real capacity over nominal capacity, as a percentage. For Tesla and the newer Kia electric models the manufacturer's own reading is served while it is current; otherwise, and for all other makes, this is our estimate from the vehicle's charging data. The response does not state which; a present measured_date indicates a manufacturer reading.

Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$

batteryCapacity

BatteryCapacity · object

required

Show child attributes

measuredDate

string<date> | null

The date the manufacturer measured the battery, for a manufacturer-reported figure whose measurement time is known. Absent for our own estimates (measured when calculated) and for manufacturer-reported figures without a supplied measurement time. Manufacturers refresh their reading infrequently, so this can be well before calculation_date.

Authentication

Accounts

Vehicles

Vehicle Telemetry

Vehicle Charging History

Vehicle Range

Vehicle State of Health

Vehicle Command Executions

Vehicle Alerts

Vehicle Connection

Vehicle Services

Vehicle Tires

Vehicle Manufacturer Alerts

Vehicle Eligibility

Rate Limit

Vehicle Charging Schedule

Vehicle Listening

Vehicle Journeys

Tags

Errors

Get Vehicle State Of Health

Authorizations

Path Parameters

Response