Data Delivery

Getting Started

The CARUSO Dataplace platform provides multi-brand in-vehicle data from different vehicle manufacturers in one harmonized format. The telematics data originates from connected cars who provide access to data via embedded telematic control units or retrofit devices. Such vehicles are also called Connected Vehicles, our Developer Portal explains how to integrate in-vehicle data into your solutions. Our Data Catalog explains what kind of in-vehicle data items are available for usage in your solutions and applications. The Data Items available for one of your Connected Vehicles may vary depending on the vehicle manufacturer, the connected vehicle itself (i.e., the make, the model, drive type and any special equipment), and the settings made by the vehicle owners/drivers.

CARUSO enables Data Delivery from most major vehicle manufacturers and provides you easy access to in-vehicle data for your data-driven business. The delivery of data is based on the Vehicle Identification Number (VIN) of the Connected Vehicle. Thus, it is considered to be personal data. According to the General Data Protection Regulation (GDPR), this means a legal basis for lawful processing of personal data must be in place for data delivery (please note that depending on the vehicle manufacturer, the options for lawful processing of personal data may differ).

Check out our APIs and learn how to integrate data from Connected Cars. Data delivery may use different technical means (e.g., pull, push, or stream). Our Data Catalog provides you with a data dictionary including data item definitions, data item descriptions, and detailed technical information.

Your journey to integrate in-vehicle data into your solutions is as follows:

 
Enjoy integrating data from Connected Vehicles into your applications and solutions!

Cheers, Your CARUSO Team

PS: In case of any questions, simply get in touch with us via support@caruso-dataplace.com.
PSS: And yes, you can also start exploring the data world of Connected Vehicles with our Virtual Vehicle Manufacturer. The Virtual Vehicle Manufacturer provides you access to simulated test data of several virtual vehicles. These virtual vehicles behave like real connected vehicles featuring frequently asked data items. Also, the virtual vehicles comes along with predefined and repeating behavior, providing an ideal environment for testing and integration purposes.

Sign Up for a Marketplace Account

First step towards access to vehicle data is of course to register your company at the CARUSO Dataplace. Please note that CARUSO is a B2B marketplace, so you will only receive an account on behalf of a registered company.

Marketplace Sign Up

Upon successful registration (i.e., signing our terms and conditions), we will provide you with your credentials (username and password) to login at the marketplace. Requesting further marketplace accounts is of course possible.

In addition, your company will also be provided with a consumerId. The consumerID is a unique identifier associated with your company.

Explore the Marketplace

Using your account, you can log in and explore our marketplace. Our platform provides access to data from most major brands and vehicle manufacturers in Europe. Please have a look at the available brands and their respective connected models and makes at our website.

Now it is your choice: either pick one of the predefined data packages that CARUSO prepared for you or navigate the data items available and request those that are of interest to your use case.

Marketplace Starting Page

The data packages and data item offers state also in detail information for which models, which countries, which pricing model, and any possible limitation that may exist. Also, have a look at the data response example to make sure that the data delivered fits to your needs. We prepare a Subscription based on your input. By default, a subscription is also bound to the expiration of the marketplace account of your company.

Make a Subscription

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.

Subscription Details

Once you have subscribed, you are now eligible to request data for your subscription. Therefore, you must use your API Key and the subscriptionID. The subscription details always provide you with the IDs and your API key.

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

Also, you can see the data items that are accessible as part of your subscription. For details on the data items, please refer also to our Data Catalog. Further, you can see examples of data requests in the API Reference section.

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 platform as described in the examples shown in the section API Reference.

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 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 the 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. ​

Manage Vehicles

Contract-based subscriptions require explicit vehicle management by the customer in order to activate or deactivate data delivery. Contract-based subscriptions means all subscriptions, which have ‘contract’ as lawful means for data processing. You can manage the vehicles based on their Vehicle Identification Number (VIN) via the Marketplace or the Vehicle Management API.

Manage Vehicles

At any time, you can inform yourself about the current status of the vehicles per subscription. Further, you can execute a command to add additional vehicles to a subscription. Of course, removal of vehicles works in a similar way but uses a different command). The commands supported are as follows:

  • activate – a command to add (a set of) vehicles to a subscription using the Vehicle Identification Numbers (VINs).
  • deactivate – a command to remove (a set of) vehicles from a subscription using the Vehicle Identification Numbers (VINs).

Vehicles management at CARUSO is not an end in itself. We forward the respective status changes to the respective vehicle manufacturers and let you know once data delivery has been activated or deactivated. Please note that this may take some time (ranging from a few hours up to a few days) depending on the respective vehicle manufacturer. Hence, the lifecycle for vehicle management is as follow:

  • Pending Activation: once you add/activate a VIN for a subscription, the VIN will be in the state ‘Pending Activation’. We propagate the activation to the respective vehicle manufacturer. Once we got feedback, the status of the VIN is either changed to ‘Activated’ or ‘Incapable’.
  • Activated: All VINs in state ‘Activated’ are ready for data delivery. You may request data for those vehicles using our - In-Vehicle API and use the data in your applications and solutions.
  • Pending Deactivation: once you remove/deactivate a VIN from a subscription, the VIN will be in the state ‘Pending Deactivation’. We propagate the deactivation to the respective vehicle manufacturer. Once we got feedback, the status of the VIN is changed to ‘Deactivated’.
  • Deactivated: All VINs in state ‘Deactivated’ are no longer delivering data. Request for data will fail accordingly and you can’t use the data in your applications and solutions any longer. For your information VINs in state ‘Deactivated’ will still be listed at the subscription for some time, but will eventually be removed from vehicle management.
  • Incapable: The state ‘Incapable’ indicates an issue when trying to activate this particular vehicle. Data delivery is not (yet) possible for such vehicles. We get in touch with you directly to resolve the issue.

Consume data via our In-Vehicle API

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: 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 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" }