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:

• Test Environment: https://na12.api.qa-stage.p-44.com/services/unified-integrations/v1/connections/4aff89b5-320c-4467-b973-11c729be7065/ingestions
• Production (Europe): https://eu12.api.project44.com/services/unified-integrations/v1/connections/0334dadf-5fc2-4a90-869e-ea31ff6ede2f/ingestions
• Production (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": "PLCOBAAA",
        "device_id": "123456789",
        "license_plate": "KK50450",
        "unit_number": "77",
        "vin": "WDBHA23E9VF590365",
        "unit_type": "tractor",
        "position": {
            "latitude": 56.34173432,
            "longitude": 11.12907489
        },
        "timestamp": 1704067200,
        "speed": 50,
        "direction": 270,
        "odometer": 12345.1,
        "moving": true,
        "ignition": true,
        "battery_voltage": 2367,
        "charging": false
    },
    {
        "owner_id": "PLCOBAAA",
        "device_id": "987654321",
        "license_plate": "KR9PT57",
        "unit_number": "53777",
        "vin": "1GKEK13TX3R169703",
        "unit_type": "trailer",
        "position": {
            "latitude": 56.34173432,
            "longitude": 11.12907489
        },
        "timestamp": 1704067200,
        "speed": 35,
        "direction": 115,
        "odometer": 2345.1,
        "moving": true,
        "ignition": true,
        "battery_voltage": 1237,
        "charging": false,
        "door_1_open": true,
        "door_3_open": false,
        "total_fuel_used": 1589.5,
        "fuel_level": 52
    }
]

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 a numerical value 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).
• 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.
• 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.
• total_fuel_used - Total fuel consumption data.
• fuel_level - The percentage of remaining fuel in the vehicle.

Requirements

Real-Time Data Only

• Do not send historical data. The integration automatically discards 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

• While the integration has no rate limitations, it is recommended to transmit data every 5 minutes for each active vehicle 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.

Response Codes