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 theowner_id
in order to initiate data PUSH. - Anowner_id
will be allocated by project44 for each carrier. - Data is required to be transmitted in the UTC+0 timezone.
note
- 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.
note
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. |
note
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."}