Consume Data
The CARUSO platform supports different ways of consuming data from connected vehicles.
- Pull Requests: Data from connected vehicles can be consumed on demand by a pull request on our REST API. Requested Data Items provide telematics information about the vehicle (e.g., mileage, states, position, or diagnostics trouble codes). This information can also be requested in scheduled jobs or batch processes in your application running at a regular interval.
- Push Notifications: Notification are triggered by events or data item updates happening in the vehicle. Such notifcations can be forwarded directly to your push endpoint. Hence, notifications allow you to act when something is happening within the car (e.g., starting of movement, accident information, updates of data items). Upon arrival of a push notification your application can decide how to react based on the data received.
- Kafka Streams: Kafka is a technology for handling real-time data feeds, see also the Kafka website for more details. Events and produced in the connected cars are forwarded as they are received from the respective data supplier. To consume the data, you need to configure a Kafka consumer with a specific topic name matching your subscription.
The Data Catalog shows what kind of Vehicle Data Items are available. Please note that some Data Items are only available for Push Notification (indicated Delivery Method push
in the Data Catalog).
Consuming Data via Pull Requests
To consume Vehicle Data, you have to request Data Items via our REST API. The data items provide information about the vehicle (e.g., its states, position, or fault codes) and are requested using the Vehicle Identification Number (VIN) of that particular vehicle. The API is designed to allow the consumer to specify the set of vehicles and the set of data items they want to consume in one single HTTP request.
Request Header Parameters
X-Subscription-Id |
The subscription Id for which the data is requested |
X-API-Key |
The API-Key, a unique code required to authorize your call to our API |
Request Body Schema
dataItems |
The requested data (refer to the Data Catalog for available data items) |
requestParameters |
Additional request parameters, reserved for future use |
Vehicles |
The list of requested vehicles identified by VIN (Vehicle Identification Number) |
Response Schema
inVehicleData |
Array of objects with the requested vehicle data, with identifier response pairs. |
identifier |
Vehicles identified by VIN (Vehicle Identification Number) |
response |
The response of the requested service, defined as a map of requested "Data Item" to "Data Point" Or "Error" pairs |
deliveredAt |
Date and time of data delivery |
Example
Please refer to details and the examples shown in the section API Reference.
Consuming Data via Push Notifications
In order to receive push notification, you have to configure a webhook and optionally may set a secret. We only support HTTPS and arbitrary secret (which we strongly recommend you providing). The secret is embedded into the header when the CARUSO platform triggers your webhook with an HTTP POST. You can configure both, when editing your Subscription on the Marketplace.
- Push URL: You may provide (and change) at any time the URL of your webhook endpoint to which CARUSO platform should send data. The URL must be publicly accessible.
- Push Secret: To increase security, we recommend you provide a secret for your webhook. This secret will be sent in the HTTP “Authorization”-header of every push request.
The number of retries is set to 3. We consider a Push Notification to be successful once the CARUSO platform has triggered the HTTP POST. It is up to the consumer to ensure that the events will be received.
Example
Following is the construct of the POST request send from CARUSO Dataplace to your service.
Header Parameters
X-Subscription-Id |
your subscription id to your desired data plan |
Content-Type |
application/json charset=UTF-8 |
Authorization |
secret provided by you during webhook configuration |
X-Caruso-Delivery-Transaction-Id |
A unique delivery identifier |
Payload
Following is an example payload for telematicpositionupdate
event.
{
"forwardedAt": "2022-07-05T13:57:20.680Z",
"inVehicleResponse": {
"deliveredAt": "2020-10-16T08:35:04.1Z",
"inVehicleData": [
{
"identifier": {
"type": "VIN",
"value": "12345678901234567"
},
"response": {
"telematicpositionupdate": {
"dataPoint": {
"receivedAt": "2020-10-16T08:35:04.072044175Z",
"timestamp": "2020-10-16T08:33:35Z"
}
}
}
}
],
"version": "1.0"
},
"subscriptionId": "9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
"transactionId": "9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a"
}
Following is an example payload for the data items mileage
and geolocation
update event.
{
"forwardedAt": "2022-07-05T13:57:20.680Z",
"inVehicleResponse": {
"deliveredAt": "2022-07-05T13:57:20.680430648Z",
"inVehicleData": [
{
"identifier": {
"type": "VIN",
"value": "VINXXXXXXXXXXXXXX"
},
"response": {
"geolocation": {
"dataPoint": {
"geoSystem": "WGS84",
"latitude": 99.999999,
"longitude":99.999999,
"timestamp": "2022-07-05T13:56:53.000Z"
}
},
"mileage": {
"dataPoint": {
"timestamp": "2022-07-05T13:56:53.000Z",
"unit": "km",
"value": 9999
}
}
}
}
],
"version": "1.0"
},
"subscriptionId": "9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
"transactionId": "9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a"
}
Response
You are supposed to respond with HTTP 200 with response body:
{ "status": "OK" }
Consuming Data via Kafka Stream
To consume Vehicle Data from a Kafka Stream, you need to subscribe to Kafka Topic(s). Each Topic reflects a Subscription on the CARUSO Dataplace. Every Message in the Topic contains one distinct Data Item of a vehicle, which is identified by its VIN.
Kafka Security Configuration
First the URL to the Kafka Server of CARUSO, the consumer group and the topic needs to be configured. Kafka Streams are protected by different security mechanisms.
- IP Whitelisting: The public IPv4 address (behind which a streaming consumer client is running) must be whitelisted on the CARUSO Portal in order to be able to connect and subscribe to a topic.
- SASL authentication: An SASL authentication with a username and password is necessary. The credentials are listed in your Subscriptions on the CARUSO Portal.
Configuration Parameters
Parameter | Description | Example | CARUSO Parameter Name |
---|---|---|---|
bootstrap.servers | A list of host/port pairs to use for establishing the initial connection to the Kafka cluster. | api.streaming.caruso-dataplace.com:9196 |
Kafka Connect URL |
group.id | A unique string that identifies the consumer group this consumer belongs to. | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
Kafka Consumer Group |
topic | Virtual Groups or Logs that hold messages and events in a logical order. | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
Kafka Topic Name / Subscription ID |
security.protocol | Protocol used to communicate with brokers. | SASL_SSL |
|
sasl.mechanisms | The types of SASL mechanisms that are used. | SCRAM-SHA-512 |
|
sasl.username | The username for SASL authentication. | xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx |
User Name |
sasl.password | The password for SASL authentication. | xxxxxxxxxxxxxx |
User Secret |
Kafka Message Schema
The value of a CARUSO Kafka Message is in JSON format. It contains the SubscriptionId
to determine from which Subscription it comes from and the VIN and Data Item technical name to identify the vehicle and the Data Item, that the message is about. The Body contains all parameters of the specific Data Item.
The Data Catalog describing all the different Data Items can be found here.
General
{
"rev": "Revision of the Message Schema",
("deliveryFlowId": "Delivery Flow ID, coming soon",)
"subId": "Subscription ID",
"traceId": "Trace ID",
"containerIds": ["Container ID 1", "Container ID 2", "..."],
"correlationId": "Correlation ID, if provided by the data supplier",
"vehicleIdentifier": "Vehicle's VIN",
"dataItem": "Data Item technical name",
"body": {
"Key1": "Value1",
"Key2": "Value2",
...
},
"timestamp": "{Timestamp in Format according to ISO 8601 format.}"
}
Example
{
"rev": "r1",
("deliveryFlowId": "0z0z0z0z-0z0z-0z0z-0z0z-0z0z0z0z0z0z",)
"subId": "9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
"traceId": "",
"containerIds": null,
"correlationId": "1234567890-1234567890",
"vehicleIdentifier": "VINXXXXXXXXXXXXXX",
"dataItem": "geolocation",
"body": {
"longitude": 99.999999,
"latitude": 99.999999,
"geoSystem": "WGS84",
"timestamp": "2023-01-01T08:00:00.123Z"
},
"timestamp": "2023-01-01T08:01:00.123Z"
}