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:

• Sign up for an account at our Marketplace.
• Explore the Marketplace and request one or several of our Data Offers.
• Provide Billing Information at our Marketplace as a prerequisite for making subscriptions.
• Make a Subscription and check out the subscription details with all the information you need to start making requests to our APIs.
• Check how our mechanisms for Authentication and Authorization work.
• Have a proper lawful means for processing in-vehicle data in place.
• Manage the Vehicles in your Subscriptions via the marketplace or our Vehicle Management API.
• Consume data via our In-Vehicle API and use it in your applications and solutions.
• Please also refer to our API Reference for examples of data requests, vehicle management, and consent handing.
• Get in contact with us if you need any support.

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

Cheers, Your CARUSO Team

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.

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.

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.

Provide Billing Information

As a prerequisite for making subscriptions, you will need to provide billing information for your account. After logging in the marketplace, you can navigate to your company information via your initials in the top right, click “Company” and scroll down to the Billing section. Now you can enter your billing information.

As a customer of CARUSO note that we require billing information for generating invoice for data delivery. Please take some time to read through our billing procedures.

• You will need to provide billing information prior to making any subscription. Providing billing information is simple and straightforward, just navigate to your Company information and scroll down to the Billing section and fill in all required fields.
• Invoice are created automatically based on the pricing model, price, and the usage as described in your subscription. The charges will be calculated on a monthly basis, The billing cycle starts on first day of the month and ends at the last day of each month.
• The calculation of the charges happens usually on the first working day of the new month. After we issued a new invoice, you can download it at the “My Invoices” section at the marketplace. There you can also find your history of past invoices. In addition, you will also be notified by email to your billing email address for every new invoice.
• Your active subscriptions are billed monthly based on the selected pricing model. Terms of payment and payment method are stated on your invoice. Please quote the invoice number for all payments.
• You can update your billing information at any time online by logging into the marketplace and go to the “Billing” section.

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.

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.

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

Subscriptions require explicit vehicle management by you in order to activate or deactivate vehicles for data delivery. You can either manage the vehicles based on their Vehicle Identification Number (VIN) via the Marketplace or use the Vehicle Management API. Please note that vehicle activation is a mandatory prerequisite for data delivery.

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

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

Ask for Support

Our experienced support team is always happy to help you out in case there are any questions and/or any need for further explanations.

Straight from the marketplace, you can drop us messages and/or questions by clicking on the questions mark on the top right corner. Select the topic, input your message to us, and send. And we will get back to you as soon as possible.

Or simply get in touch with us via support@caruso-dataplace.com.