Telematics PUSH Server

Overview

This guide details the process for integrating with the project44 system via the Telematics PUSH Server interface. It provides comprehensive instructions to configure the integration and enable seamless data transmission to project44 for your customers.

Authentication

Authentication Type: Basic Authorization

project44 employs Basic Authorization for securing API access. Credentials (username and password) are provided at the telematics provider level, enabling a single set of credentials to authenticate and transmit data for all associated customers.

Ensure the header is formatted as follows:

Authorization: Basic <base64_encoded_username:password>

To obtain your API credentials and link your product to the project44 portal, please contact carrierservices@project44.com

Endpoint

Base URLs:

Europe, APAC, LatAm: https://eu12.api.project44.com/services/unified-integrations/v1/connections/0334dadf-5fc2-4a90-869e-ea31ff6ede2f/ingestions
North America: https://na12.api.project44.com/services/unified-integrations/v1/connections/0433b147-c474-49f3-9c9e-5997500651ab/ingestions

Method: POST
Content-Type: application/json

Request Body

[
    {
        "owner_id": "AYCOBAAA",                  // String (example)
        "device_id": "123456789",                // String
        "license_plate": "KK50450",              // String
        "unit_number": "77",                     // String
        "vin": "WDBHA23E9VF590365",              // String
        "unit_type": "tractor",                  // String
        "position": {                            
            "latitude": 56.34173432,             // Float
            "longitude": 11.12907489             // Float
        },
        "timestamp": 1704067200,                 // Integer (Unix timestamp. Accepts both seconds and milliseconds formats)       
        "speed": 50,                             // Integer (km/h)
        "direction": 270,                        // Integer (degrees)
        "odometer": 12345,                       // Integer (mileage)
        "moving": true,                          // Boolean
        "ignition": true,                        // Boolean
        "altitude": 150,                         // Integer (meters)
        "battery_voltage": 2367,                 // Integer (millivolts)
        "charging": false,                       // Boolean
        "door_1_open": false,                    // Boolean
        "door_2_open": false,                    // Boolean
        "door_3_open": false,                    // Boolean
        "door_4_open": false,                    // Boolean
        "fuel_level_percentage": 60.8,            // Float (percentage)
        "reefer_temp1": 10.5,                    // Float (Celsius degrees)
        "reefer_temp2": 14.4,                    // Float (Celsius degrees)
        "reefer_temp3": 0.0,                     // Float (Celsius degrees)
        "reefer_temp4": -5.2                     // Float (Celsius degrees)
    },
    {
        "owner_id": "MKCOBAAA",                  // String (example)
        "device_id": "987654321",                // String
        "license_plate": "KR9PT57",              // String
        "unit_number": "53777",                  // String
        "vin": "1GKEK13TX3R169703",              // String
        "unit_type": "trailer",                  // String
        "position": {                            
            "latitude": 56.34173432,             // Float
            "longitude": 11.12907489             // Float
        },
        "timestamp": 1739444955989,              // Integer (Unix timestamp. Accepts both seconds and milliseconds formats)
        "datetime_utc": "2024-01-01T00:00:00Z",  // String (ISO 8601)
        "speed": 35,                             // Integer (km/h)
        "direction": 115,                        // Integer (degrees)
        "odometer": 234,                         // Integer (mileage)
        "moving": true,                          // Boolean
        "ignition": true,                        // Boolean
        "altitude": 145,                         // Integer (meters)   
        "battery_voltage": 1237,                 // Integer (millivolts)
        "charging": false,                       // Boolean
        "door_1_open": true,                     // Boolean
        "door_2_open": false,                    // Boolean
        "door_3_open": false,                    // Boolean
        "door_4_open": false,                    // Boolean
        "fuel_level_percentage": 52.5,           // Float (percentage)
        "reefer_temp1": 4.5,                     // Float (Celsius degrees)
        "reefer_temp2": 3.8,                     // Float (Celsius degrees)
        "reefer_temp3": 5.2,                     // Float (Celsius degrees)
        "reefer_temp4": 2.7                      // Float (Celsius degrees)
    }
]

Payload Details

Mandatory Fields

owner_id – A unique value representing the transportation company. Provided by either the carrier or project44.
device_id – Unique identifier for the asset, expressed as string of numerical values with a maximum length of 15 digits.
position - Geographical position specified in degrees, comprising both latitude and longitude (GPS coordinates).
timestamp - Date/time in EPOCH format corresponding to when the position was recorded. Accepts both seconds and milliseconds.
license_plate (mandatory in Europe) - The vehicle's license plate information.
unit_number (mandatory in North America) - The vehicle's truck or trailer number.

Optional Fields

unit_type - Specifies the type of unit. Accepts either tractor or trailer (case-sensitive, use lowercase). If not provided, the default value is tractor.
vin - Vehicle Identification Number, also known as the chassis number.
datetime_utc - Date/time in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.
speed - Current velocity of the vehicle in kilometers per hour (km/h).
direction - Indicates the vehicle's travel direction.
odometer - The current distance driven by the vehicle, expressed in kilometers (km).
moving - Specifies whether the vehicle is in motion. Accepts true or false.
ignition - Indicates whether the engine is on or off. Accepts true or false.
altitude - Indicates the current altitude of the vehicle in meters.
battery_voltage - Provides battery voltage information.
charging - Indicates whether the vehicle is actively charging. Accepts true or false.
door_#_open - Indicates whether the trailer doors are open. Accepts true or false. # represents a numeric value from 1 to 4.
fuel_level_percentage - The percentage of remaining fuel in the vehicle.
reefer_temp# - Indicates the temperature from reefer sensor, expressed in degrees Celsius. # represents a numeric value from 1 to 4.

Requirements

Real-Time Data Only

Do not send historical data. The integration might not process any data older than 10 minutes from the current time.

Data Format

The HTTP request body must contain a JSON-encoded string with data for the specified devices.

owner_id

The owner_id is required to initiate data PUSH.
owner_id is typically an 8-character alphabetic string in uppercase format.
owner_id is automatically generated for each project44 account owner.
Telematics providers must obtain the owner_id before starting the integration.

Recommendations

Batch Data Transmission

Send no more than 50 data samples per request for optimal performance.
Include data for multiple vehicles in a single payload to streamline communication.

Data Frequency

We expect to receive the latest position update for the unique asset every 5 minutes to ensure real-time updates.

Multi-Carrier Support

A single payload can include data from multiple carriers (owner_id).
The system will automatically distribute the data to the respective carriers' accounts.

JSON Schema

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "owner_id": {
                "type": "string",
                "description": "Unique identifier for the owner",
                "minLength": 1
            },
            "device_id": {
                "type": "string",
                "description": "Unique identifier for the device",
                "minLength": 1
            },
            "license_plate": {
                "type": "string",
                "description": "Vehicle's license plate number (either license_plate or unit_number is required)"
            },
            "unit_number": {
                "type": "string",
                "description": "Unit number assigned to the vehicle (either license_plate or unit_number is required)"
            },
            "vin": {
                "type": "string",
                "description": "Vehicle Identification Number"
            },
            "unit_type": {
                "type": "string",
                "enum": ["tractor", "trailer"],
                "description": "Type of unit (must be either 'tractor' or 'trailer')"
            },
            "position": {
                "type": "object",
                "properties": {
                    "latitude": {
                        "type": "number",
                        "description": "Latitude of the vehicle's position",
                        "minimum": -90,
                        "maximum": 90
                    },
                    "longitude": {
                        "type": "number",
                        "description": "Longitude of the vehicle's position",
                        "minimum": -180,
                        "maximum": 180
                    }
                },
                "required": ["latitude", "longitude"]
            },
            "timestamp": {
                "type": "integer",
                "description": "Unix timestamp. Accepts both seconds and milliseconds formats"
            },
            "datetime_utc": {
                "type": "string",
                "format": "date-time",
                "description": "ISO 8601 formatted timestamp (optional)"
            },
            "speed": {
                "type": "integer",
                "description": "Speed of the vehicle in km/h"
            },
            "direction": {
                "type": "integer",
                "description": "Direction of movement in degrees"
            },
            "odometer": {
                "type": "integer",
                "description": "Odometer reading in kilometers"
            },
            "moving": {
                "type": "boolean",
                "description": "Indicates if the vehicle is moving"
            },
            "ignition": {
                "type": "boolean",
                "description": "Indicates if the vehicle's ignition is on"
            },
            "altitude": {
                "type": "integer",
                "description": "Altitude of the vehicle in meters"
            },
            "battery_voltage": {
                "type": "integer",
                "description": "Battery voltage in millivolts"
            },
            "charging": {
                "type": "boolean",
                "description": "Indicates if the vehicle is charging"
            },
            "door_1_open": {
                "type": "boolean",
                "description": "Indicates if door 1 is open"
            },
            "door_2_open": {
                "type": "boolean",
                "description": "Indicates if door 2 is open"
            },
            "door_3_open": {
                "type": "boolean",
                "description": "Indicates if door 3 is open"
            },
            "door_4_open": {
                "type": "boolean",
                "description": "Indicates if door 4 is open"
            },
            "fuel_level_percentage": {
                "type": "number",
                "description": "Fuel level as a percentage"
            },
            "reefer_temp1": {
                "type": "number",
                "description": "Temperature from reefer sensor 1 in degrees Celsius"
            },
            "reefer_temp2": {
                "type": "number",
                "description": "Temperature from reefer sensor 2 in degrees Celsius"
            },
            "reefer_temp3": {
                "type": "number",
                "description": "Temperature from reefer sensor 3 in degrees Celsius"
            },
            "reefer_temp4": {
                "type": "number",
                "description": "Temperature from reefer sensor 4 in degrees Celsius"
            }
        },
        "required": [
            "owner_id",
            "device_id",
            "position",
            "timestamp"
        ],
        "anyOf": [
            { "required": ["license_plate"] },
            { "required": ["unit_number"] }
        ]
    }
}

Response Codes

Code	Message	Description
202	`Accepted`	The request was successfully received
400	`Bad request`	The request contains syntax errors in the JSON payload or unsupported parameters
401	`Unauthorized`	Authentication failed. Verify the username and password provided in the request
403	`Forbidden`	The user does not have the required permissions to access the requested resource
405	`Method Not Allowed`	The HTTP method used is not supported by the endpoint
408	`Request timeout`	The server timed out waiting for the request. Reduce the number of device data objects per request or retry at a later time
413	`Request entity too large`	The request payload exceeds the server's allowed size. Split the data into smaller batches and resend using multiple requests
415	`Unsupported media type`	The Content-Type header must be set to application/json
503	`Service unavailable`	The service handling device data is temporarily down. Retry the request later