CommonRest - project44 PUSH Service

Introduction

The CommonRest - project44 PUSH Service is an https REST webservice used to deliver device information to a project44-based system.

Interface

Device data is transmitted to the project44 system through an HTTPS POST request.

Test Environment URL: https://telemetry.dev.ghtrack.me:8391/tracking_data/v1/devices
Production URL: https://telemetry.europe.ghtrack.com:[PortID]/data/tracking_data/v1/devices
- The production PortID is provided by project44 to each respective provider.

Use Basic Authorization to authenticate before initiating the data PUSH process.

The Username and Password will be provided by project44 for each respective provider.

The HTTPS header field Content-Type must be configured to application/json.

The HTTPS body data must be a JSON-encoded string containing information for a specified number of devices.
Timestamps, specifically 'date-time' fields, must adhere to the ISO 8601 standard.
If the device_id is of integer/number type, it is required to have a maximum length of 15 digits.
Each carrier is assigned its respective owner_id within the project44. Providers must obtain the owner_id in order to initiate data PUSH. - An owner_id will be allocated by project44 for each carrier.
Data is required to be transmitted in the UTC+0 timezone.

project44 recommends transmitting data for multiple devices in batches with a recommended frequency of once per two minutes.
If a batch includes data for multiple devices, data can be transmitted through multiple requests.
If there is no new data available for a specific device, the data can be excluded from the batch.
Do not transmit data that exceeds a ten minute age limit.

Example HTTPS Request

POST /tracking_data/v1/devices
Test Host: https://telemetry.dev.ghtrack.me:8391/
Production Host: https://telemetry.europe.ghtrack.com:[PortID]/data/
Authorization: Basic Authorization
Accept-Encoding: gzip, deflate
Content-Type: application/json
Content-Length: 640
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.1.1 (java 1.5)

[
    {
        "owner_id": "string",
        "device_id": 1,
        "position": {
            "latitude": 0,
            "longitude": 0
        },
        "datetime_utc": "2024-01-01T12:00:00Z",
        "speed": 90,
        "direction": 270,
        "odometer": 12345.1,
        "license_plate": "string",
        "moving": true,
        "ignition": true,
        "battery_voltage": 2367,
        "charging": false,
    },
    {
        "owner_id": "string",
        "device_id": 2,
        "position": {
            "latitude": 57.34868086,
            "longitude": 13.22058247
        },
        "datetime_utc": "2024-01-01T12:00:00Z",
        "speed": 80,
        "direction": 134,
        "odometer": 54321.22,
        "license_plate": "string",
        "moving": true,
        "ignition": true,
        "battery_voltage": 1867,
        "charging": true,
        "door_1_open": true,
        "door_3_open": false,
        "vehicle_type": "tractor",
        "total_fuel_used": 1589.5,
        "fuel_level": 52
    }
]

Requirements

The essential data that must be transmitted includes:

owner_id – Identification provided by project44 to uniquely identify the carrier.
device_id – A distinct identifier for a device, unique within the scope of its owner_id.
position - The geographical position, specified in degrees, comprising latitude and longitude for GPS coordinates.
datetime_utc - The UTC timestamp associated with GPS data.
license_plate – The vehicle's license plate information.

The three shipment-related attributes are presently exclusive to legacy systems. Kindly avoid transmitting any of these attributes to the cloud-based platform, as such actions will result in data being discarded.

JSON Schema

{
    "$schema": "http://json-schema.org/draft-04/schema#",
    "title": "Device data",
    "description": "Data of multiple devices",
    "type": "array",
    "items": [
        {
            "type": "object",
            "properties": {
                "owner_id": {
                    "description": "identifier for owner of a device, e.g. the name of a haulier",
                    "type": "string"
                },
                "device_id": {
                    "description": "an identifier for a device, unique per owner_id",
                    "type": [
                        "integer",
                        "string"
                    ]
                },
                "position": {
                    "type": "object",
                    "description": "GPS position, latitude and longitude in degrees",
                    "properties": {
                        "latitude": {
                            "type": "number"
                            },
                        "longitude": {
                            "type": "number"
                        }
                    },
                    "required": [
                        "latitude",
                        "longitude"
                    ]
                },
                "datetime_utc": {
                    "description": "GPS UTC date",
                    "type": "string",
                    "format": "date-time"
                },
                "speed": {
                    "description": "speed in km/h",
                    "type": "number"
                },
                "direction": {
                    "description": "direction in degrees",
                    "type": "number"
                },
                "odometer": {
                    "description": "odometer counter in km",
                    "type": "number"
                },
                "asset_id": {
                    "description": "Optional field containing a unique asset identifier. If left out the value is set to the license plate.",
                    "type": "string"
                },
                "license_plate": {
                    "description": "license plate of vehicle",
                    "type": "string"
                },
                "shipment_id": {
                    "description": "optional id of a shipment being tracked",
                    "type": "string"
                },
                "shipment_eta": {
                    "description": "optional ETA of the shipment delivery time",
                    "type": "string",
                    "format": "date-time"
                },
                "shipment_subscriber_id": {
                    "description": "id of the shipment subscriber, e.g. a customer",
                    "type": "string"
                },
                "moving": {
                    "description": "moving state: true=moving, false=not moving",
                    "type": "boolean"
                },
                "ignition": {
                    "description": "ignition state: true=on, false=off",
                    "type": "boolean"
                },
                "battery_voltage": {
                    "description": "current battery voltage level of the device in mV",
                    "type": "number"
                },
                "charging": {
                    "description": "charging state: true=charging, false=not charging",
                    "type": "boolean"
                },
                "door_1_open": {
                    "description": "door 1 state. Trailers only: true=open, false=closed",
                    "type": "boolean"
                },
                "door_2_open": {
                    "description": "door 2 state. Trailers only: true=open, false=closed",
                    "type": "boolean"
                },
                "door_3_open": {
                    "description": "door 3 state. Trailers only: true=open, false=closed",
                    "type": "boolean"
                },
                "door_4_open": {
                    "description": "door 4 state. Trailers only: true=open, false=closed",
                    "type": "boolean"
                },
                "vehicle_type": {
                    "description": "Type of vehicle associated with the device",
                    "type": "string",
                    "default": "tractor",
                    "enum": [
                        "tractor",
                        "trailer"
                    ]
                },
                "total_fuel_used": {
                    "description": "The total amount of fuel used by the vehicle in litres",
                    "type": "number"
                },
                "fuel_level": {
                    "description": "Tank fuel level in percent (%)",
                    "type": "number"
                },
                "device_type": {
                    "description": "Type of the device from where the data was generated",
                    "type": "string",
                    "enum": [
                        "app",
                        "tracking_device",
                        null
                    ]
                }
            },
            "required": [
                "owner_id",
                "position",
                "datetime_utc"
            ],
            "oneOf": [
                {
                    "required": [
                        "device_id"
                    ]
                },
                {
                    "required": [
                        "shipment_id"
                    ],
                    "not": {
                        "required": [
                             "asset_id"
                        ]
                    }
                }
            ]
        }
    ]
}

HTTPS Response Codes

Code	Message	Description
`200`	`OK`	Your request has been accepted and successfully processed.
`400`	`Bad request`	This may include syntax errors in the JSON-encoded string received from the user, or it could be due to an unsupported request.
`403`	`Forbidden`	The user lacks the necessary access rights for the requested resource.
`408`	`Request timeout`	The server experienced a timeout while awaiting the request. The client has the option to resubmit the request without alterations at a later time. Alternatively, the client may reduce the number of device data objects delivered in a request to expedite the request delivery time.
`413`	`Request entity too large`	The length of the request exceeds the server's allowable limit. To address this, the device data object within the request must be transmitted using multiple requests.
`415`	`Unsupported media type`	The Content-Type field within the HTTPS header must be set to 'application/json'.
`503`	`Service unavailable`	The service responsible for handling device data is currently not operational on the server. The client is advised to resubmit the request at a later time.

In the event of a failure code being returned (excluding 503), the HTTPS body will include the reason within a JSON-encoded string.

Example ‘Code 200’: { "message" : "Successful delivery of 34 device data objects" }

Example ‘Code 403’: { "message" : "Unknown user or incorrect password."}