How to Get Vehicle Telemetry

This article demonstrates how to leverage Autonomic's robust APIs to access vehicle data.

Introduction

In this guide, you learn how to get current and historical telemetry from a vehicle or group of vehicles using the Vehicle Service and the Group Service. Developers creating applications for a small number of vehicles, such as owner applications, should use the Vehicle Service. If you're creating an application for a fleet of vehicles, use the Group Service.

Before You Begin

Before you begin, you need to meet several prerequisites to access the platform and exercise the APIs in this guide. Those prerequisites are explained below as well as how to acquire the credentials and permissions. If you don't have credentials, a workspace, or permissions, contact your Customer Success representative.

Credentials

Before you can interact with theplatform, you need to have your credentials available. Your credentials, client ID and client secret, were supplied to you when you onboarded to the platform.

Workspaces

The requests in the Vehicle and Group Services require a workspace. If you do not have a workspace or you do not know the workspace name, contact your Customer Success representative.

Vehicle Permissions

Using the Vehicle Service requires that you have either the vehicle-driver or vehicle-owner role on a minimum of one vehicle. You can verify your vehicle roles using the IAM Service permissions endpoint.

Request

GET /system/iam/permissions

Response


						{
							"items": [
								{
								  "id": 101,
								  "createTime": "2019-01-02T23:26:18.130Z",
								  "subjectId": "system:iam:user/johnDoe",
								  "objectId": "system:asset:vehicle/",
								  "roleId": "system:iam:role/vehicle-driver"
								},
								{
								  "id": 890837,
								  "createTime": "2019-05-16T18:13:09.074Z",
								  "subjectId": "system:iam:user/johnDoe",
								  "objectAId": "system:group:group/",
								  "roleId": "system:iam:role/group-reader"
								}
							],
							"nextPageToken": ""
						}

If you do not have the requisite role(s), contact the individual with vehicle-owner permissions or your Customer Success representative.

GroupID

The Group Service requires a valid GroupID. If you don't have a GroupID, please contact the group administrator or your Customer Success representative.

If you don't know your GroupID, you can see what group(s) of which you are a part using the Group API groups endpoint.

Request

GET /system/groups

Response


						{
						  "items": [
							{
							  "groupId": "",
							  "role": "group-reader"
							}
						  ],
						  "nextPageToken": ""
						}

Group Permissions

Getting telemetry using the Group Service requires the group-reader or group-admin role. If you don't have permissions, please contact your Customer Success representative.

Steps for Getting Vehicle Telemetry

Using the Vehicle Service

Getting telemetry using the Vehicle Service is a three-step process, as follows:

Authenticate.
Get a list of vehicles using the Resources Service.
Make an HTTP (cURL) request using the workspace name and vehicle identification number (VIN).

Using the Group Service

Getting Current Vehicle Telemetry

Getting telemetry using the Group Service is a four step process, as follows:

Authenticate.
Get a list of vehicles using the Group Service vehicles endpoint.
Make an HTTP (cURL) request using the workspace name and GroupID for group information.
Make an HTTP (cURL) request using the workspace name, GroupID, and VIN for individual vehicle telemetry.

Getting Historical Vehicle Telemetry

Note: Historical Telemetry is only available using the Group Service.

Authenticate
Get a list of vehicles using the Group Service vehicles endpoint.
Make an HTTP (cURL) request using the workspace name and GroupID for group information.
Make an HTTP (cURL) request using the workspace name, GroupID, and VIN for individual vehicle historical telemetry.

RESTful vs Web Sockets: Use RESTful requests for periodic telemetry requests and web sockets for real-time streaming telemetry from vehicles.

Consuming Telemetry

Note: Although web-socket request examples are shown, the scope of this document is primarily obtaining telemetry using REST endpoints.

Using the Vehicle Service

Developers creating applications for small numbers or a single vehicle, such as owner applications, should consider using the Vehicle Service to get telemetry. The Vehicle Service is the interface for application developers to interact with the platform to get telemetry from and send commands to an individual vehicle. Actions taken with the Vehicle Service use the VIN to identify the individual vehicle.

For more information about using the Vehicle Service, see the Vehicle Service Reference.

Prerequisites

The client is successfully authorized.
The client has the appropriate permissions for the vehicle.
A workspace is configured for the vehicle or vehicles from which telemetry is received.

Query for a List of Vehicles

Note: Use the VINs from this response in the HTTP and web-socket requests for vehicle telemetry.

Use the following request to get a list of vehicles from the inventory database:


						curl -X GET \
						  https://api.system.ai/v2/resources/vehicles?pageSize=20 \
						  -H 'Authorization: Bearer ' \
						  -H 'Content-Type: application/json'

You get a response similar to the following, consisting of an unfiltered list of vehicles, with a page size of `20`:


						{
						  "items": [
							{
							  "id": "",
							  "createTime": "2018-07-31T15:36:19.644Z",
							  "updateTime": "2019-02-15T08:42:48.463Z",
							  "name": "Ford F Series Pickup",
							  "vin": "",
							  "properties": {
								"make": "Ford",
								"model": "F-150",
								"year": "2012",
								"transmissionType": "UNKNOWN"
							  },
							  "tags": {
								"intended_env": "dev",
								"group": "cv-mon"
							  },
							  "bindingsLink": "https://api.system.ai/v2/resources/vehicles//bindings"
							}
						  ],
						  "nextPageToken": ""
						}

In the query response, you are retrieving a list of vehicles, unfiltered, with up to 20 vehicles per page. You also receive a nextPageToken (if more than 20 vehicles are returned) reference that you can pass in to paginate to the next page in the data set, by adding &nextPageToken= to the same query request.

HTTP Request - Vehicle Telemetry

GET /v1beta/workspaces//vehicles//telemetry

Web-socket Request - Vehicle Telemetry

wscat -c wss://api.system.ai/v1beta/workspaces/<WORKSPACE_NAME>/vehicles/<VIN>/telemetry/ws --header "Authorization: Bearer <TOKEN>"

Response Format


						{
						  "vin": "",
						  "aui": "system:asset:vehicle/",
						  "metrics": {
							  "": {
								  "metricKind": ["GAUGE", "DELTA", "CUMULATIVE"],
								  "startTime": "dateTime",
								  "value": "value",
								  "tags": {
									  "": ""
								  }
							  },
						  },
						  "events": {
							  "": {
								  "timestamp": "dateTime",
								  "conditions": {
									  "": {
										  "metric": {
											  "" : ""
										  }
									  }
								  },
								  "metrics": {
									  "" : ""
								  }
							  }
						  },
						  "stateTransitions": {
							  "": {
								  "correlationId": "",
								  "source": "string",
								  "timestamp": "dateTime",
								  "fromState": "string",
								  "toState": "string",
								  "trigger": "string",
								  "message": "string",
								  "data": "string",
								  "tags": {
									  "": ""
								  },
								  "nonWellKnown": {
									  "": {
										  "correlationId": "",
										  "source": "string",
										  "timestamp": "dateTime",
										  "fromState": "string",
										  "toState": "string",
										  "trigger": "string",
										  "message": "string",
										  "data": "string",
										  "tags": {
											  "": ""
										  }
									  }
								  }
							  }
						  }
						}

Sample Response Snippet


						{
						  "vin": "",
						  "aui": "system:asset:vehicle/",
						  "metrics": {
							"absStatus": {
							  "metricKind": "GAUGE",
							  "startTime": "2019-07-11T20:32:14.382412195Z",
							  "endTime": "2019-07-11T20:32:14.382414340Z",
							  "value": "ON"
							},
							"acceleration": {
							  "metricKind": "GAUGE",
							  "startTime": "2019-07-11T20:32:14.382245779Z",
							  "endTime": "2019-07-11T20:32:14.382247924Z",
							  "sensorType": "ACCELEROMETER_DATA",
							  "x": 0.32008992072660547,
							  "y": 0,
							  "z": 0
							},
							  "transmissionOilTemperature": {
							  "metricKind": "GAUGE",
							  "startTime": "2019-07-11T20:32:14.382376194Z",
							  "endTime": "2019-07-11T20:32:14.382378339Z",
							  "value": 20
							}
						  },
						  "events": {},
						  "stateTransitions": {}
						}

Using the Group Service

The Group Service is the interface for application developers to interact with the TMC to get telemetry and telemetry history from groups of vehicles or individual vehicles that are explicitly part of a group. This service is most applicable to commercial vehicle fleets. The Group Service requires permission granted for the vehicle’s group, not the individual vehicle.

For more information about using the Group Service, see the Group Service Reference.

Prerequisites

The client is successfully authorized.
The client has the appropriate permissions for the group.
A valid GroupID.

Existing or new group

Vehicles exist in the group.
A configured workspace for the vehicle or vehicles from which telemetry is received. If you do not have a workspace or you do not know the workspace name, contact your Customer Success representative.

The group must be in a workspace to be able to access telemetry. A workspace represents a collection of pipelined data transformation services that consume telemetry from an input flow and result in an output flow from which consumption services can serve data.

HTTP Request - Group Telemetry

GET /v1beta/workspaces//groups//telemetry

Web-socket Request - Group Telemetry

wscat -c wss://api.system.ai/v1beta/workspaces//groups//telemetry/ws --header "Authorization: Bearer "

Response Format


						[
						  {
							"vin": "",
							"metrics": {
								"": {
									"metricKind": ["GAUGE", "DELTA", "CUMULATIVE"],
									"startTime": "dateTime",
									"value": "value",
									"tags": {
										"": ""
									}
								}
							},
							"events": {
								"": {
									"timestamp": "dateTime",
									"conditions": {
										"": {
											"metric": {
												"" : ""
											}
										}
									},
									"metrics": {
										"" : ""
									}
								}
							}
						  }
						]

Sample Response Snippet


						[
						  {
							"vin": "",
							"aui": "system:asset:vehicle/",
							"metrics": {
							  "absStatus": {
								"metricKind": "GAUGE",
								"startTime": "2019-07-15T18:49:32.133311986Z",
								"endTime": "2019-07-15T18:49:32.133313179Z",
								"value": "ON"
							  },
							  "acceleration": {
								"metricKind": "GAUGE",
								"startTime": "2019-07-15T18:49:32.133216142Z",
								"endTime": "2019-07-15T18:49:32.133217573Z",
								"sensorType": "ACCELEROMETER_DATA",
								"x": 2.168064692267219,
								"y": 0,
								"z": 0
							  },
							},
							"vin": "",
							"aui": "system:asset:vehicle/",
							"metrics": {
							  "absStatus": {
								"metricKind": "GAUGE",
								"startTime": "2019-07-15T18:49:32.078783035Z",
								"endTime": "2019-07-15T18:49:32.078784465Z",
								"value": "ON"
							  },
							  "transmissionOilTemperature": {
								"metricKind": "GAUGE",
								"startTime": "2019-07-15T18:49:32.078756570Z",
								"endTime": "2019-07-15T18:49:32.078758001Z",
								"value": 20
							  }
							},
							"events": {},
							"stateTransitions": {}
						  }
						]

HTTP Request - Vehicle Telemetry


						GET /v1beta/workspaces//groups//vehicles//telemetry

Web-socket Request - Vehicle Telemetry


						wscat -c httpswss://api.system.ai/v1beta/workspaces//groups//vehicles//telemetry/ws --header "Authorization: Bearer {bearer_token}"

Response Format


						[
						  {
							"vin": "",
							"metrics": {
								"": {
									"metricKind": ["GAUGE", "DELTA", "CUMULATIVE"],
									"startTime": "dateTime",
									"value": "value",
									"tags": {
										"": ""
									}
								}
							},
							"events": {
								"": {
									"timestamp": "dateTime",
									"conditions": {
										"": {
											"metric": {
												"" : ""
										}
									},
									"metrics": {
										"" : ""
									}
								}
							  }
							}
						  }
						]

Sample Response Snippet


						[
						  {
							"vin": "",
							"aui": "system:asset:vehicle/",
							"metrics": {
							  "absStatus": {
								"metricKind": "GAUGE",
								"startTime": "2019-07-15T20:00:50.137890577Z",
								"endTime": "2019-07-15T20:00:50.137893199Z",
								"value": "ON"
							  },
							  "acceleration": {
								"metricKind": "GAUGE",
								"startTime": "2019-07-15T20:00:50.137794256Z",
								"endTime": "2019-07-15T20:00:50.137795925Z",
								"sensorType": "ACCELEROMETER_DATA",
								"x": 2.28327462959569,
								"y": 0,
								"z": 0
							  },
							},
							"events": {},
							"stateTransitions": {}
						  }
						]

HTTP Request - Historical Telemetry


						POST /v1beta/workspaces//groups//fields

Request Format


						{
							"fields": [
								"string",
								"string",
								"string"
							],
							"events": [
								"string",
								"string",
								"string"
							],
							"startTime": "",
							"endTime": ""
						}

Response Format


						  "items":
							[
							  "string",
							  "string",
							  "string"
							]
						}

Sample Request


						{
						  "endTime": "2019-08-23T15:02:33.051Z",
						  "fields": [
							"longitude",
							"latitude",
							"odometer"
						  ],
						  "format": "string",
						  "startTime": "2019-08-23T15:02:23.051Z"
						}

Sample Response Snippet


						[
						  {
							"vin": "",
							"time": "2019-08-23T15:02:25.000Z",
							"longitude": -122.15966166754448,
							"latitude": 37.44784932797301,
							"odometer": 72424.92665316888
						  },
						  {
							"vin": "",
							"time": "2019-08-23T15:02:27.000Z",
							"longitude": -122.15949294605106,
							"latitude": 37.44801911333737,
							"odometer": 72424.95068426117
						  },
						  {
							"vin": "",
							"time": "2019-08-23T15:02:28.000Z",
							"longitude": -122.15941016310042,
							"latitude": 37.448102417899804,
							"odometer": 72424.96247504113
						  },
						  {
							"vin": "",
							"time": "2019-08-23T15:02:30.000Z",
							"longitude": -122.15929721869321,
							"latitude": 37.44821607356669,
							"odometer": 72424.97856167657
						  },
						  {
							"vin": "",
							"time": "2019-08-23T15:02:31.000Z",
							"longitude": -122.15928078996942,
							"latitude": 37.44823260571098,
							"odometer": 72424.98090161032
						  },
						  {
							"vin": "",
							"time": "2019-08-23T15:02:32.000Z",
							"longitude": -122.15927656901,
							"latitude": 37.448236853240196,
							"odometer": 72424.981502799
						  }
						]