A tachograph is a special device used in the European Union for tracking driver and vehicle activity. The tachograph APIs are only available to Samsara EU customers.

Overview

Samsara provides three API endpoints for retrieving tachograph data:

Download driver tachograph files
Download vehicle tachograph files
Get parsed driver tachograph activity

Tachograph Files

The Samsara Vehicle Gateway downloads both vehicle and driver tachograph files (.ddd format) from the vehicle's tachograph device on a regular basis. As soon as the gateway has downloaded the files from the tachograph, they are immediately uploaded to the Samsara cloud where users can download them through the cloud dashboard or the API.

Driver Tachograph Files

The Samsara Vehicle Gateway gateway uploads a new driver tachograph file at the start of every trip.

You can retrieve the files with a call to the GET /fleet/drivers/tachograph-files/history endpoint:

curl --request GET 'https://api.eu.samsara.com/fleet/drivers/tachograph-files/history' \
-d startTime='2021-01-01T00:00:00Z' \
-d endTime='2021-01-07T00:00:00Z' \
-G \
--header 'Authorization: Bearer <<token>>'

The startTime and endTime parameters represent the time window for which you'd like to retrieve tachograph files.

The endpoint returns an array of tachograph file URLs for each driver who was active during that time range.

Notice that each driver in the imaginary fleet below was only active 2 out of the 7 days queried.

{
    "data": [
        {
            "driver": {
                "id": "123456",
                "name": "Sam Sara"
            },
            "files": [
                {
                    "cardNumber": "DB12345678901234",
                    "createdAtTime": "2021-01-04T23:23:51.587Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/driver_files/12345/2021/1/4/DB12345678901234/1609802631587-c92ac846-163c-4e28-b598-6b8193572b04.ddd",
                    "id": "c92ac846-163c-4e28-b598-6b8193572b04"
                },
                {
                    "cardNumber": "DB12345678901234",
                    "createdAtTime": "2021-01-06T19:43:26.845Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/driver_files/12345/2021/1/6/DB12345678901234/1609962206845-6a79f6fb-ad0e-4455-81e7-092a22252386.ddd",
                    "id": "6a79f6fb-ad0e-4455-81e7-092a22252386"
                }
            ]
        },
        {
            "driver": {
                "id": "789012",
                "name": "Driver Danielle"
            },
            "files": [
                {
                    "cardNumber": "DB56789012345678",
                    "createdAtTime": "2021-01-02T14:46:33.121Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/driver_files/12345/2021/1/2/DB56789012345678/1609598793121-52acbb42-0609-400c-b77a-38230c73f4e6.ddd",
                    "id": "52acbb42-0609-400c-b77a-38230c73f4e6"
                },
                {
                    "cardNumber": "DB56789012345678",
                    "createdAtTime": "2021-01-03T15:46:07.522Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/driver_files/12345/2021/1/3/DB56789012345678/1609688767522-39322857-2a3c-4352-ac95-d23c6c308ac4.ddd",
                    "id": "39322857-2a3c-4352-ac95-d23c6c308ac4"
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "35a46d33-d901-4195-a0ae-353615e642a3",
        "hasNextPage": false
    }
}

You may then download each tachograph file using the URL provided. The createdAtTime field indicates when the given tachograph file was downloaded from the tachograph device by the vehicle gateway.

To reduce redundant data, Samsara only provides the latest tachograph file available for each day. In other words, even though the gateway uploads a new tachograph file each time the vehicle turns on, only the latest tachograph file for a given day will be available.

If you query for a large time period and/or have many drivers in your fleet, the response may be paginated.

You may also filter the results to given drivers or tags using Filtering Parameters (see the reference docs for details).

Vehicle Tachograph Files

The Samsara Vehicle Gateway gateway uploads a new vehicle tachograph file every 7 days.

You can retrieve the files with a call to the GET /fleet/vehicles/tachograph-files/history endpoint:

curl --request GET 'https://api.eu.samsara.com/fleet/vehicles/tachograph-files/history' \
-d startTime='2020-12-01T00:00:00Z' \
-d endTime='2020-12-31T00:00:00Z' \
-G \
--header 'Authorization: Bearer <<token>>'

The startTime and endTime parameters represent the time window for which you'd like to retrieve tachograph files.

The endpoint returns an array of tachograph file URLs for each vehicle that uploaded a tachograph file during the time range.

{
    "data": [
        {
            "vehicle": {
                "id": "123456789012345",
                "name": "Samsarus"
            },
            "files": [
                {
                    "vin": "ABCDEFGHI12345678",
                    "createdAtTime": "2020-12-03T23:11:15.937Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/vehicle_files/12345/2020/12/3/ABCDEFGHI12345678/1607037075937-2ec97e9c-bdb0-4af5-8acc-e20883c23160.ddd",
                    "id": "2ec97e9c-bdb0-4af5-8acc-e20883c23160"
                },
                {
                    "vin": "ABCDEFGHI12345678",
                    "createdAtTime": "2020-12-12T13:47:50.287Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/vehicle_files/21222/2020/12/12/ABCDEFGHI12345678/1607780870287-5a89e9b0-419f-488c-8601-a56182798046.ddd",
                    "id": "5a89e9b0-419f-488c-8601-a56182798046"
                },
                {
                    "vin": "ABCDEFGHI12345678",
                    "createdAtTime": "2020-12-19T11:41:39.245Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/vehicle_files/21222/2020/12/19/ABCDEFGHI12345678/1608378099245-68aa1aed-c6ef-4ad6-92ad-2d5496d5f04d.ddd",
                    "id": "68aa1aed-c6ef-4ad6-92ad-2d5496d5f04d"
                },
                {
                    "vin": "ABCDEFGHI12345678",
                    "createdAtTime": "2020-12-27T06:43:29.502Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/vehicle_files/21222/2020/12/27/ABCDEFGHI12345678/1609051409502-109a0b4b-6c06-4de4-91e8-80ca162048bd.ddd",
                    "id": "109a0b4b-6c06-4de4-91e8-80ca162048bd"
                }
            ]
        },
        {
            "vehicle": {
                "id": "678901234567890",
                "name": "Owl-mobile"
            },
            "files": [
                {
                    "vin": "JKLMNOPQR90123456",
                    "createdAtTime": "2020-12-15T16:39:46.252Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/vehicle_files/21222/2020/12/15/JKLMNOPQR90123456/1608050386252-ea09d425-f007-4531-99c9-1569cbd2a996.ddd",
                    "id": "ea09d425-f007-4531-99c9-1569cbd2a996"
                },
                {
                    "vin": "JKLMNOPQR90123456",
                    "createdAtTime": "2020-12-22T04:08:08.477Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/vehicle_files/21222/2020/12/22/JKLMNOPQR90123456/1608610088477-b748c202-cfa5-40db-9e75-7afc336e83aa.ddd",
                    "id": "b748c202-cfa5-40db-9e75-7afc336e83aa"
                },
                {
                    "vin": "JKLMNOPQR90123456",
                    "createdAtTime": "2020-12-30T05:14:42.432Z",
                    "url": "https://samsara-tachograph-files.s3.us-west-2.amazonaws.com/vehicle_files/21222/2020/12/30/JKLMNOPQR90123456/1609305282432-9e23690c-1f35-4f5e-93d9-3fdc6c132d4c.ddd",
                    "id": "9e23690c-1f35-4f5e-93d9-3fdc6c132d4c"
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "8620af49-be14-4d1a-bbf5-eb94f07e5e6e",
        "hasNextPage": false
    }
}

You may then download each tachograph file using the URL provided. The createdAtTime field indicates when the given tachograph file was downloaded from the tachograph device by the vehicle gateway.

If you query for a large time period and/or have many vehicles in your fleet, the response may be paginated.

You may also filter the results to given vehielcs or tags using Filtering Parameters (see the reference docs for details).

Parsed Tachograph Activity

You can get parsed driver tachograph activity (such as when a driver was on break, work, or driving) using the GET /fleet/drivers/tachograph-activity/history endpoint.

Parsed driver tachograph activity is updated every time a vehicle turns ON.

curl --request GET 'https://api.eu.samsara.com/fleet/drivers/tachograph-files/history' \
-d startTime='2021-01-11T00:00:00Z' \
-d endTime='2021-01-12T00:00:00Z' \
-G \
--header 'Authorization: Bearer <<token>>'

The startTime and endTime parameters represent the time window for which you'd like to retrieve tachograph activity events.

The endpoint returns an array of tachograph activity events for each driver during the request time range.

{
    "data": [
        {
            "driver": {
                "id": "123456",
                "name": "Sam Sara"
            },
            "activity": [
                {
                    "startTime": "2021-01-11T00:00:00.000Z",
                    "endTime": "2021-01-11T04:54:00.000Z",
                    "state": "BREAK/REST",
                    "isManualEntry": true
                },
                {
                    "startTime": "2021-01-11T04:54:00.000Z",
                    "endTime": "2021-01-11T05:08:00.000Z",
                    "state": "WORK",
                    "isManualEntry": false
                },
                {
                    "startTime": "2021-01-11T05:08:00.000Z",
                    "endTime": "2021-01-11T07:48:00.000Z",
                    "state": "DRIVING",
                    "isManualEntry": false
                },
                {
                    "startTime": "2021-01-11T07:48:00.000Z",
                    "endTime": "2021-01-11T08:00:00.000Z",
                    "state": "WORK",
                    "isManualEntry": false
                },
                {
                    "startTime": "2021-01-11T08:00:00.000Z",
                    "endTime": "2021-01-12T00:00:00.000Z",
                    "state": "BREAK/REST",
                    "isManualEntry": true
                }
            ]
        }
    ],
    "pagination": {
        "endCursor": "0bb66f59-c4dd-4941-aff0-5957555f2c31",
        "hasNextPage": false
    }
}

If you query for a large time period and/or have many drivers in your fleet, the response may be paginated.

You may also filter the results to given drivers or tags using Filtering Parameters (see the reference docs for details).