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

Request Body Schema

Response Schema

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

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

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

{
    "version": "Version of the Message Schema",
    "forwardedAt": "Timestamp in format according to ISO 8601 format.",
    "subscriptionId": "Subscription ID",
    "transactionId": "Transaction ID",
    "correlationId": "Correlation ID optional if provided by the data supplier",
    "identifier": {
        "type": "VIN",
        "value": "12345678901234567"
    },
    "data":{
		"<dataItemTechnicalName1>": {
			"dataPoint": {
				"Key1": "Value1",
				"Key2": "Value2"
			}
		},
        "<dataItemTechnicalName2>": {
			"dataPoint": {
				"Key1": "Value1",
				"Key2": "Value2"
			}
		}
	}
}

Example

{
	"version": "1.0",
	"forwardedAt": "2023-01-01T08:01:00.123Z",
	"subscriptionId": "9a9a9a9a-9a9a-9a9a-9a9a-9a9a9a9a9a9a",
	"transactionId": "0z0z0z0z-0z0z-0z0z-0z0z-0z0z0z0z0z0z",
	"correlationId": "1234567890-1234567890",
	"identifier": {
		"type": "VIN",
		"value": "VINXXXXXXXXXXXXXX"
	},
	"data": {
		"geolocation": {
			"dataPoint": {
				"longitude": 99.999999,
				"latitude": 99.999999,
				"geoSystem": "WGS84",
				"timestamp": "2023-05-19T05:56:05.000Z"
			}
		}
	}
}