Data Delivery

Getting Started

The Caruso platform provides multi-brand in-vehicle data from different vehicle manufacturers in one harmonized format. The telematics data originates from vehicles via embedded telematic control units or retrofit devices. Such vehicles are called Connected Vehicles. Our Data Catalog explains what kind of in-vehicle data is available for use. The quantity of Data Items may vary depending on the vehicle manufacturer, the connected vehicle itself and its make, model, drive type, and any special equipment.

We make sure that in-vehicle data is easily accessible and support you in your journey to data-driven business. Data Delivery is based on the Vehicle Identification Number (VIN) of the car. It may use different technical means (e.g., pull, push, or stream) and may be done for Individual Vehicles or Fleet Vehicles.

Our part in the Data Delivery is to enable you to consume data originating from connected vehicles. The basic steps to get started are as follows:

  • You see and explore our Offers on Data Packages and Data Items on our Marketplace.
  • You can decide about
    • the Data Items you would like to consume (please refer also to our Data Catalog for the data dictionary).
    • the legal basis for Lawful Processing of Personal Data (please note that depending on the data supplier, options for lawful processing of personal data may differ).
  • We prepare a Subscription based on your decisions.
  • You subscribe – then you are authorized to request data for your subscription (please refer to our API Reference for data request examples).
  • You are responsible of making sure, that you are only processing Personal Data for each vehicle on proper lawful means.
  • You start consuming data for the consented vehicles.

Marketplace Subscription

The first and foremost prerequisite to consume data is to register your company in Caruso Dataplace. Upon successful registration, we will provide you with a consumerId. Using your preferred access credentials, you can log in and explore our marketplace. Our platform provides access to data from major brands and vehicle manufacturers in Europe and you can find respective offers for data items or data packages on our marketplace.

In order to be able to consume data through the Caruso Marketplace, it is required that you make a subscription. A subscription determines the selected data items, the selected pricing option, the selected means for lawful processing of personal data, etc., and last but not least, the terms & conditions applicable for data delivery. Once you subscribe, a Data Delivery Agreement has been made and you are now authorized to request data for your subscription using your API Key. You will also receive a subscriptionId, which you need to provide when requesting data.

  • consumerId: A unique identifier for a data consumer.
  • subscriptionId: A unique id for your selected data plan.
  • API Key: A unique code required to call our API.

You can see examples of data requests in the API Reference section.

Data Consumption

The Caruso platform supports different kinds of information about the connected vehicles.

  • Vehicle Data: Vehicle Data are information about the connected vehicle that can be consumed on demand by an API request. The 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.
  • Vehicle Events: Vehicle Events are information from the connected vehicle, which we actively send to you. Their general purpose is to serve as notifications. Upon arrival of an event your application can decide how to react. For example, it can collect further Vehicle Data based on the Vehicle Event.

The Data Catalog shows what kind of Vehicle Data and Vehicle Events are available.

Consuming Vehicle Data via Pull

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 Vehicle Events via Push

To consume Vehicle Events, you have to configure a webhook and optionally may set a secret. We only support HTTPS and arbitrary secret (which we strongly recommend 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: In order to increase security, we recommend you to 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 1. We consider a Push Event 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 Telematic position update event.

{
  "version": "1.0",
  "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"
          }
        }
      }
    }
  ]
}

Response

You are supposed to respond with HTTP 200 with response body:

{ "status": "OK" }

Lawful Processing of Data

In-Vehicle Data is considered personal data in Caruso. This means a legal basis for lawful processing of personal data must be in place for data consumption. Depending on the kind of vehicle and also depending on the data supplier, more or less options for lawful processing of personal data are possible. And depending on the agreed lawful processing basis, consumers need to integrate their system with Caruso accordingly.

  • Individual Vehicle: Any vehicle owned, leased, or used by one or more individuals or a family.
  • Fleet Vehicle: Any vehicle owned or leased by a business, government agency, or other organization rather than by one or more individuals or family. In some jurisdictions and countries, fleet vehicle may also mean a vehicle that is privately owned by employees, or on novated leases, but is being mainly used for work or commercial purposes.

Lawful Processing of Data for Individual Vehicles

The following options for lawful processing of data for individual vehicles are supported by Caruso:

  • Consent (Synchronous, OAuth based): In this case, the provider supports the consent provisioning as it is described in the the Extended Vehicle standard (ISO 20078). It means the end user (registered keeper) needs to provide consent in an OAuth flow. The detailed integration steps are described here: User Consent.
  • Consent (Asynchronous): In this case, the end user needs to provide consent directly to the data provider. To initiate the consent process, the consumer first needs to make a data request using the API. Afterwards consumers inform the end users to provide consent to the data provider directly. Once the end user does it, the consumer can retrieve data.
  • Contract: In this case, the end user is already involved in the contracting process with the data provider, data consumer, and Caruso. The consumer does not need to do technical integration here.
  • Legitimate Interest: In this case, the consumer does not need any technical integration. If the provider and Caruso agree that the consumer is allowed to get data based on legitimate interest, consumers can get it without any technical integration for lawful means.
  • Not Applicable: If the data items are no personal data or for some exceptional cases, users do not need to approve the data delivery, the consumer does not need to do any technical integration. This case is preferably used for testing purposes only with cars owned by the data consumer.

Implementing a technical integration for lawful processing is a prerequisite for data delivery. Once the lawful processing has been integrated into your solution, you can start asking your end users (registered keepers of the vehicles) to provide consent and then, and only then start collecting in-vehicle data from the connected vehicles.

Please note, for synchronous, Oauth-based consent, you as consumer can always check whether or not a consent has been given for a particular VIN using the Consent Check API.

Lawful Processing of Data for Fleet Vehicles

The following options for lawful processing of data for fleet vehicles are supported by Caruso:

  • Contract: In this case, Caruso and the consumer sign a Data Delivery Agreement for fleet vehicles. Vehicles joining the fleet are allocated to a Subscription for fleet vehicles. The vehicles joining and leaving the fleet must be provided truthfully by the consumer. The consumer is obligated to keep the documentation of the vehicles in Data Delivery up-to-date at all times. The consumer must particularly ensure that they are authorized to do so. At Caruso’s request, the consumer must provide documentary evidence to this effect. A process will be defined jointly between Consumer and Caruso to handle this.
  • Legitimate Interest: If the Data Supplier and Caruso agree that the consumer is allowed to get data based on legitimate interest, consumers can get it without any technical integration for lawful means.

For fleet vehicles, the consumer does not need to do any technical integration. ​

Authentication and Authorization

Caruso Dataplace uses API keys to authenticate client requests. The API key is a secret key for the data consumer and should be handled with care. Since Caruso is a B2B marketplace an API key is only issued once for your company (i.e., we do not provide API keys to individual users). You will learn about your API Key once you have made your first subscription on the marketplace. The API key is used to make requests on behalf of your organization. In other words, it’s a shared key for all associated users of your company. The API Key constitutes sensitive information and it is highly recommended that best practices for storage of sensitive information are applied.

Name Description Example
X-Subscription-Id The subscription id. Consumer receives this id upon subscribing for a plan offered by a provider. 42dea87e-1b56-4faa-b2ad-e47d6a1c71dd
X-API-Key The API-Key provided by Caruso Dataplace to your company. 4safllqhtmbo1c6ndq91obslogcmimob[…]

Authorization of your requests to our API are done by our platform by checking the validity of the API Key and the subscription made by you. In case an invalid subscriptionId is given in the request header, or the subscriptionId is missing, it will cause your request to fail. Please have a look in our error handling for different authentication and authorization failure cases.

These required parameters are sent as HTTP-headers to the Caruso delivery engine as described in the examples shown in the section API Reference.