Endpoints¶

The API gives access to dynamic data (position, status, CAN data, battery, trips) for vehicles equipped with telematics devices.

Data structures¶

`vehicle` object¶

Standard vehicle information.

Field name	Type	Description
`id`	String	Internal vehicle identifier.
`plate`	String	License plate.
`vin`	String	Vehicle identification number / VIN.
`brand`	String	Vehicle make.
`model`	String	Commercial name.

`location` object¶

Vehicle position.

Field name	Type	Description
`latitude`	Number	Latitude.
`longitude`	Number	Longitude.
`angle`	Number	Angle. 0° corresponds to north.
`altitude`	Number	Altitude (in meters).

`can` object¶

CAN data configured and reported by the telematics device. Fields may be empty (String) or 0 (Number) when information is missing.

Field name	Type	Description
`key`	String	Data identifier.
`value`	String	Data value.

`status` object¶

Additional data on the connected vehicle's real-time status: usage (engine status) and movement. Fields may be empty (String) or 0 (Number) when information is missing.

Field name	Type	Description
`ignition`	Bool	Engine status: `true` engine running, `false` engine off.
`movement`	Bool	Vehicle status: `true` moving, `false` stopped.
`mileage`	Number	Vehicle mileage.
`autonomy`	Number	Vehicle range (in km).

`electric` object¶

Data concerning the traction battery of electric vehicles.

Field name	Type	Description
`soh`	Number	Battery state of health (%).
`soc`	Number	Battery charge level (%).
`current`	Number	Current supplied by the battery (A).
`voltage`	Number	Battery voltage (V).
`energy`	Number	Energy supplied by the battery (kWh).
`maxEnergy`	Number	Maximum energy supplied by the battery (kWh).
`minCellVoltage`	Number	Minimum cell voltage (V).
`maxCellVoltage`	Number	Maximum cell voltage (V).
`temperature`	Number	Battery temperature (°C).
`minCellTemperature`	Number	Minimum cell temperature (°C).
`maxCellTemperature`	Number	Maximum cell temperature (°C).
`lifetimePowerUse`	Number	Energy consumed over the vehicle's lifetime (kWh).
`lifetimeChargePower`	Number	Energy charged over the vehicle's lifetime (kWh).

`sensors` element¶

Each external sensor (connected via Bluetooth to the device) appears as an element of the sensors array.

Field name	Type	Description
`name`	String	Sensor name.
`data`	Array	List of data reported by the sensor, in the same format as the `can` object. Currently available data: temperature (`key = temperature`) and humidity level (`key = humidity`).

`state` object¶

Vehicle state.

Field name	Type	Description
`towing`	Boolean	The vehicle is in the "towed" state.
`accident`	Boolean	The vehicle has been in an accident.
`maintenance`	Boolean	The vehicle is being serviced.
`breakdown`	Boolean	The vehicle has broken down.
`stolen`	Boolean	The vehicle is reported stolen.
`unavailable`	Boolean	The vehicle is unavailable.

This object is only present in responses concerning the current state of one or more vehicles (Usage data — all vehicles and specific vehicle), not in history (/history).

`trip` object¶

A trip made by a vehicle.

Field name	Type	Description
`trip_id`	String	Trip identifier.
`timestamp`	Timestamp	Trip start date.
`distance`	Numeric	Distance traveled during the trip.
`duration`	Numeric	Trip duration, in minutes.
`cost`	Numeric	Estimated cost of the trip.
`fuel_consumption`	Numeric	Fuel consumed, in liters, for combustion vehicles.
`fuel_consumption_100km`	Numeric	Consumption per 100 km, for combustion vehicles.
`average_speed`	Numeric	Average speed.
`electric_consumption`	Numeric	Electric consumption, for electric vehicles.
`electric_consumption_100km`	Numeric	Electric consumption per 100 km, for electric vehicles.
`first_position`	Object	Start-of-trip position (`latitude`, `longitude`).
`last_position`	Object	End-of-trip position (`latitude`, `longitude`).

`error` field¶

Only present on failure (see Errors) — absent from responses on a successful request.

List of vehicles¶

Retrieves the list of vehicles associated with the account.

GET /v1/vehicles
x-carmoove-token: <token>

Response¶

A JSON array, one element per vehicle:

Field	Type	Description
`vehicle`	Object	Data about the vehicle (`vehicle` object).
`timestamp`	Number	Timestamp of the data.
`location`	Object	Vehicle's last position (`location` object).
`status`	Object	Vehicle's last status reported by the device (`status` object).
`error`	String	Error code. Absent on a successful request.

A vehicle with no available data is simply omitted from the array (no dedicated error element).

CAN data¶

Reserved for vehicles using a proprietary CAN protocol.

Latest CAN data for all vehicles¶

GET /v1/vehicles/customcan
x-carmoove-token: <token>

Retrieves the data contained in the latest data upload for all vehicles on the account.

Response¶

A JSON array, one element per vehicle:

Field	Type	Description
`vehicle`	Object	Data about the vehicle.
`timestamp`	Number	Timestamp of the data.
`location`	Object	Vehicle's last geolocation.
`can`	Array	List of CAN data reported by the device (`can` objects).
`status`	Object	Vehicle status.
`sensors`	Array	List of external sensors and their data.
`error`	String	Error code. Absent on a successful request.

CAN data for all vehicles over a period¶

GET /v1/vehicles/customcan/from/{timestamp}
x-carmoove-token: <token>

Retrieves the data reported by all vehicles on the account from a given date onward. The number of data points returned is limited to 10,000 results; since data is sorted by timestamp, a second request can be made using the last timestamp from the previous request to retrieve the following results.

Parameters¶

Field	Type	Description
`timestamp`	Number	UNIX timestamp. Returns all data reported by the device since this date.

Response¶

A JSON array, one element per reading (potentially several per vehicle over the period):

Field	Type	Description
`vehicle`	Object	Data about the vehicle.
`timestamp`	Number	Timestamp of the data.
`location`	Object	Vehicle position.
`can`	Array	List of CAN data reported by the device.
`sensors`	Array	List of external sensors and their data.
`status`	Object	Vehicle status.
`error`	String	Error code. Absent on a successful request.

Latest CAN data for a specific vehicle¶

GET /v1/vehicle/{id}/customcan
x-carmoove-token: <token>

Retrieves the data contained in the latest data upload for a specific vehicle.

Parameters¶

Field	Type	Description
`id`	String	Vehicle identifier.

Response¶

A single JSON object:

Field	Type	Description
`vehicle`	Object	Data about the vehicle.
`timestamp`	Number	Timestamp of the data.
`location`	Object	Vehicle position.
`can`	Array	List of CAN data reported by the device.
`sensors`	Array	List of external sensors and their data.
`status`	Object	Vehicle status.
`error`	String	Error code. Absent on a successful request.

CAN data for a specific vehicle over a period¶

GET /v1/vehicle/{id}/customcan/from/{timestamp}
x-carmoove-token: <token>

Retrieves the data reported by a specific vehicle from a given date onward. Same pagination limits (10,000 results, sorted by timestamp) as above.

Parameters¶

Field	Type	Description
`id`	String	Vehicle identifier.
`timestamp`	Number	UNIX timestamp. Returns all data reported by the device since this date.

Response¶

A JSON array, one element per reading over the period:

Field	Type	Description
`vehicle`	Object	Data about the vehicle.
`timestamp`	Number	Timestamp of the data.
`location`	Object	Vehicle position.
`can`	Array	List of CAN data reported by the device.
`sensors`	Array	List of external sensors and their data.
`status`	Object	Vehicle status.
`error`	String	Error code. Absent on a successful request.

Usage data¶

Usage data for all vehicles¶

GET /v1/vehicles/status
x-carmoove-token: <token>

Retrieves the data contained in the latest data upload for all vehicles.

Response¶

A JSON array, one element per vehicle:

Field	Type	Description
`vehicle`	Object	Data about the vehicle.
`timestamp`	Number	Timestamp of the data.
`location`	Object	Vehicle position.
`status`	Object	Vehicle status.
`electric`	Object	Vehicle battery (electric vehicle).
`sensors`	Array	List of external sensors and their data.
`state`	Object	Vehicle states (towing, maintenance, accident, …).
`error`	String	Error code. Absent on a successful request.

Usage data for all vehicles over a period¶

GET /v1/vehicles/history
x-carmoove-token: <token>

Retrieves the data reported by all vehicles on the account for a given period. The number of data points returned is limited to 10,000 results (3000 by default; see limit), sorted by timestamp — use the offset field to paginate.

Parameters¶

Field	Type	Description
`from`	Number	UNIX timestamp for the start of the period.
`until`	Number	UNIX timestamp for the end of the period.
`limit`	Number	Number of data points to return. Optional (3000 by default).
`offset`	Number	Number of data points to skip. Optional.

Response¶

A JSON object containing the array of readings in status (no state object in each reading — only the current-status endpoints include it):

Field	Type	Description
`status`	Array	List of readings, each with the fields `vehicle`, `timestamp`, `location`, `status`, `electric`, `sensors`.
`error`	String	Error code. Absent on a successful request.

Usage data for a specific vehicle¶

GET /v1/vehicle/{id}/status
x-carmoove-token: <token>

Retrieves the data contained in the latest data upload for a specific vehicle.

Parameters¶

Field	Type	Description
`id`	String	Vehicle identifier.

Response¶

A single JSON object:

Field	Type	Description
`vehicle`	Object	Data about the vehicle.
`timestamp`	Number	Timestamp of the data.
`location`	Object	Vehicle position.
`status`	Object	Vehicle status.
`electric`	Object	Vehicle battery (electric vehicle).
`sensors`	Array	List of external sensors and their data.
`state`	Object	Vehicle states (towing, maintenance, accident, …).
`error`	String	Error code. Absent on a successful request.

Usage data for a specific vehicle over a period¶

GET /v1/vehicle/{id}/history
x-carmoove-token: <token>

Retrieves the data reported by a vehicle on the account for a given period. Same pagination rules (limit, offset) as for the history of all vehicles.

Parameters¶

Field	Type	Description
`id`	String	Vehicle identifier.
`from`	Number	UNIX timestamp for the start of the period.
`until`	Number	UNIX timestamp for the end of the period.
`limit`	Number	Number of data points to return. Optional (3000 by default).
`offset`	Number	Number of data points to skip. Optional.

Response¶

Same shape as the history of all vehicles — object containing the status array (without a state object):

Field	Type	Description
`status`	Array	List of readings, each with the fields `vehicle`, `timestamp`, `location`, `status`, `electric`, `sensors`.
`error`	String	Error code. Absent on a successful request.

Trips for a specific vehicle¶

GET /v1/vehicle/{id}/trips?from={from}&until={until}&offset={offset}&limit={limit}
x-carmoove-token: <token>

Retrieves the list of trips for a specific vehicle.

Parameters¶

Field	Type	Description
`id`	String	Vehicle identifier.
`from`	Timestamp	Start date. Optional. Defaults to the beginning of the current month.
`until`	Timestamp	End date. Optional. Defaults to the date of the request.
`limit`	Numeric	Number of trips to return. Optional.
`offset`	Numeric	Number of trips to skip. Optional.

Response¶

Field	Type	Description
`trips`	Object	List of trips (`trip` objects).
`error`	String	Error code. Absent on a successful request.

Error codes specific to this endpoint: see Errors.

Endpoints¶

Data structures¶

vehicle object¶

location object¶

can object¶

status object¶

electric object¶

sensors element¶

state object¶

trip object¶

error field¶

List of vehicles¶

Response¶

CAN data¶

Latest CAN data for all vehicles¶

Response¶

CAN data for all vehicles over a period¶

Parameters¶

Response¶

Latest CAN data for a specific vehicle¶

Parameters¶

Response¶

CAN data for a specific vehicle over a period¶

Parameters¶

Response¶

Usage data¶

Usage data for all vehicles¶

Response¶

Usage data for all vehicles over a period¶

Parameters¶

Response¶

Usage data for a specific vehicle¶

Parameters¶

Response¶

Usage data for a specific vehicle over a period¶

Parameters¶

Response¶

Trips for a specific vehicle¶

Parameters¶

Response¶

`vehicle` object¶

`location` object¶

`can` object¶

`status` object¶

`electric` object¶

`sensors` element¶

`state` object¶

`trip` object¶

`error` field¶