Requests
GET /api/token
Return a list of registered API tokens.
POST /api/token
Create an API token.
DELETE /api/token/<TOKEN>
Delete the specified API token.
GET /api/vehicles
Return a list of registered vehicles:
id
: Vehicle IDv_net_connected
: Number of vehicles currently connectedv_apps_connected
: Number of apps currently connectedv_btcs_connected
: Number of batch clients currently connected
GET /api/vehicle/<VEHICLEID>
Connect to the vehicle and return vehicle information:
m_msgage_s
: age (seconds) of last status (S) message received if availablem_msgtime_s
: time stamp (UTC) of last status (S) message received if availablev_apps_connected
: number of apps currently connected (including the API connection)v_btcs_connected
: number of batch clients currently connectedv_first_peer
: 0/1, 1 = the API connection is the first peer connecting to the carv_net_connected
: 0/1, 1 = the car is currently connected to the server
While no application is connected to the vehicle, the module will send status updates using the configured “idle” interval to reduce data volume and energy consumption.
Connecting to the car tells the module (if connected) to send status updates in the normally shorter “connected” intervals (as configured). If you’re the first peer and the car is online, the module will send a full status update within the next second after receiving the new peer count. Depending on the connection speed you should give the car module some seconds to transmit the first update before proceeding to other status queries.
You can also check m_msgage_s
and m_msgtime_s
to see if the status record is up to date
(yet). These fields are also included in the other status responses e.g. /api/charge/<VEHICLEID>
.
DELETE /api/vehicle/<VEHICLEID>
Disconnect from the vehicle.
This is optional, on session logout or expiry, all vehicles will be disconnected automatically.
GET /api/protocol/<VEHICLEID>
Return raw protocol records (no vehicle connection):
m_msgtime
: Date/time message receivedm_paranoid
: Paranoid mode flagm_ptoken
: Paranoid mode tokenm_code
: Message codem_msg
: Message body
GET /api/status/<VEHICLEID>
Return vehicle status:
soc
units
idealrange
idealrange_max
estimatedrange
mode
chargestate
cac100
soh
cooldown_active
fl_dooropen
fr_dooropen
cp_dooropen
pilotpresent
charging
caron
carlocked
valetmode
bt_open
tr_open
temperature_pem
temperature_motor
temperature_battery
temperature_charger
temperature_cabin
tripmeter
odometer
speed
parkingtimer
temperature_ambient
carawake
staletemps
staleambient
charging_12v
vehicle12v
vehicle12v_ref
vehicle12v_current
alarmsounding
m_msgage_s
: age (seconds) of last status (S) message received if availablem_msgtime_s
: time stamp (UTC) of last status (S) message received if availablem_msgage_d
: age (seconds) of last doors/env (D) message received if availablem_msgtime_d
: time stamp (UTC) of last doors/env (D) message received if available
GET /api/tpms/<VEHICLEID>
Return tpms status: the data available depends on the vehicle and module type.
V2 modules / old firmware versions
On V2 modules, the wheel layout is fixed to two front & two rear wheels, and sensor data is fixed to pressure and temperature:
fr_pressure
: front right pressure (PSI)fr_temperature
: front right temperature (Celcius)rr_pressure
: rear rightrr_temperature
fl_pressure
: front leftfl_temperature
rl_pressure
: rear leftrl_temperature
staletpms
: overall value staleness, -1=undefined, 0=stale, 1=validm_msgage_w
: age (seconds) of last TPMS (W) message received if availablem_msgtime_w
: time stamp (UTC) of last TPMS (W) message received if available
V3 modules
V3 modules support any kind of wheel/nonwheel layout as well as two new sensor types (health & alert level). The actual wheel naming and value availability depends on the vehicle type. Default wheel layout/naming is the same as with V2, i.e. “fl”, “fr”, “rl” & “rr”. For the wheel layout of other vehicles, see the respective vehicle manual pages.
For each wheel, sensor values pressure, temperature, health and alert status may be available, i.e. all wheel fields are optional:
<wheelname>_pressure_kpa
: wheel pressure in kPa<wheelname>_pressure
: wheel pressure in PSI<wheelname>_temperature
: wheel temperature in Celcius<wheelname>_health
: wheel health in percent<wheelname>_alert
: wheel alert level, 0=none, 1=warning, 2=alert
Staleness is available per sensor type & overall, with -1=undefined, 0=stale, 1=valid:
stale_pressure
stale_temperature
stale_health
stale_alert
staletpms
(maximum value of the above)
Metadata:
m_msgage_y
: age (seconds) of last TPMS (Y) message received if availablem_msgtime_y
: time stamp (UTC) of last TPMS (Y) message received if availablem_msgage_w
: compatibility copy ofm_msgage_y
m_msgtime_w
: compatibility copy ofm_msgtime_y
GET /api/location/<VEHICLEID>
Return vehicle location:
latitude
longitude
direction
altitude
gpslock
stalegps
speed
tripmeter
drivemode
power
energyused
energyrecd
m_msgage_l
: age (seconds) of last location (L) message received if availablem_msgtime_l
: time stamp (UTC) of last location (L) message received if available
GET /api/charge/<VEHICLEID>
Return vehicle charge status:
linevoltage
battvoltage
chargecurrent
chargepower
chargetype
chargestate
soc
units
idealrange
estimatedrange
mode
chargelimit
chargeduration
chargeb4
chargekwh
chargesubstate
chargetimermode
chargestarttime
chargetimerstale
cac100
soh
charge_etr_full
charge_etr_limit
charge_limit_range
charge_limit_soc
cooldown_active
cooldown_tbattery
cooldown_timelimit
charge_estimate
charge_etr_range
charge_etr_soc
idealrange_max
cp_dooropen
pilotpresent
charging
caron
temperature_pem
temperature_motor
temperature_battery
temperature_charger
temperature_ambient
temperature_cabin
carawake
staletemps
staleambient
charging_12v
vehicle12v
vehicle12v_ref
vehicle12v_current
m_msgage_s
: age (seconds) of last status (S) message received if availablem_msgtime_s
: time stamp (UTC) of last status (S) message received if availablem_msgage_d
: age (seconds) of last doors/env (D) message received if availablem_msgtime_d
: time stamp (UTC) of last doors/env (D) message received if available
GET /api/historical/<VEHICLEID>
Request historical data summary (as array of):
h_recordtype
: record type, e.g.*-LOG-Notification
distinctrecs
: number of distinct record numbers (h_recordnumber
) storedtotalrecs
: total number of records storedtotalsize
: total transfer data volume (bytes) of all recordsfirst
: ISO timestamp of earliest recordlast
: ISO timestamp of latest record
URL parameters:
since
: (optional) limit output to records after the date/time specified (ISO format)
GET /api/historical/<VEHICLEID>/<RECORDTYPE>
Request historical data records (as array of):
h_timestamp
: ISO date/time of the recordh_recordnumber
: record type/application specific “record number” (arbitrary identifier)h_data
: record type/application specific payload
The records are ordered by h_timestamp
(primary) and h_recordnumber
(secondary), both in ascending order.
h_data
may contain any kind of data. OVMS standard record types normally use a size
optimized CSV (comma separated values) format, with fields as specified/documented
for the record type. Another option can be JSON, with the advantage of field names being
included, at the expense of additional data volume overhead.
URL parameters:
since
: (optional) limit output to records after the date/time specified (ISO format)
Not Yet Implemented
PUT /api/charge/<VEHICLEID> Set vehicle charge status
DELETE /api/charge/<VEHICLEID> Abort a vehicle charge
GET /api/lock/<VEHICLEID> Return vehicle lock status
PUT /api/lock/<VEHICLEID> Lock a vehicle
DELETE /api/lock/<VEHICLEID> Unlock a vehicle
GET /api/valet/<VEHICLEID> Return valet status
PUT /api/valet/<VEHICLEID> Enable valet mode
DELETE /api/valet/<VEHICLEID> Disable valet mode
GET /api/features/<VEHICLEID> Return vehicle features
PUT /api/feature/<VEHICLEID> Set a vehicle feature
GET /api/parameters/<VEHICLEID> Return vehicle parameters
PUT /api/parameter/<VEHICLEID> Set a vehicle parameter
PUT /api/reset/<VEHICLEID> Reset the module in a particular vehicle
PUT /api/homelink/<VEHICLEID> Activate home link