TrackerHub
  1. Docs
TrackerHub
  • Docs
    • 01. Project Overview
    • 02. Authentication
    • 03. Error Handling
    • 04. Input Operations
    • 05. GPS Position Workflow
  • API
    • Device Type
      • Device Type
    • Tracker
      • Tracker
      • Tracker
      • Tracker
      • Tracker
    • Device
      • Create Device
      • List Device
      • Device
      • Device
      • Device
    • Position
      • Position
      • Position
      • Position
      • Create Position
      • Position :vendor
      • latest-position
      • latest-positions
      • latest-positions :deviceId
    • Configuration
      • Config
      • Config
      • Config
      • Config
    • Healthcheck
      GET
  1. Docs

04. Input Operations

Tracker#

This method is responsible for managing a tracker for the linked client. To add trackers, the name, status, and IMEI of the device must be specified. To remove trackers from the hub, an identifier must be provided.
For the operation to succeed, the Client entity requesting the operation must be previously registered. Endpoints for registering these entities are described in detail their respective API sections.

Request Response#

Example: Tracker List
[
    {
        "id_tracker": 2,
        "id_client": 1,
        "tracker_name": "tracker tests",
        "tracker_desc": "tracker description",
        "tracker_imei": "12345abc-7de5-4b8b-98c8-16f2e9158ca7",
        "status": "active"
    }
]
Example request in Postman:
CreateTracker.png

Device Type#

This method lists the of exinting device types options. Each type is available to all clients using the Tracker HUB.
This method allows clients to query the available device types in the Tracker HUB. These device types are accessible to all clients, enabling them to select the appropriate type when creating new devices.

Request Response#

Example 1: New Type
{
    "name": " VEHICLE TEST 1",
    "code": "VEHICLE 1"
}
Example 2: Type list
[
    {
        "id_device_type": 5,
        "name": "Vehicle TEST 1",
        "code": "VEHICLE"
    },
    {
        "id_device_type": 6,
        "name": " VEICULO TEST 1",
        "code": "VEHICLE 1"
    }
]
Example request in Postman:
GetDeviceType.png

Device#

This method is responsible for managing a tracked device, which can represent various types of devices (typically a Vehicle). A device is defined based on a device type category. Therefore, the type of the device must be specified before creating it.
For the operation to succeed, other entities must be previously registered, such as Tracker and Device Type. Endpoints for registering these entities are described in their respective sections.

Request Response#

Example 1:
Here, a query was made for the available device types, and the new device is linked to one of them.
[
    {
        "id_device_type": 5,
        "name": "Vehicle TESTES 1",
        "code": "VEHICLE"
    }
]
Example 2:
Here are the final request data for creating a valid device. Note that the deviceCode and deviceUuid fields are used to fill in the license plate and chassis if the device type is a vehicle.
{
    "idTracker": 4,
    "idWorksite": 123,
    "idTeam": 123,
    "deviceName": "VEHICLLE TESTS 2029",
    "idType": 5,
    "deviceCode": "ABC-1234",
    "deviceUuid": "CHASSIS-VEHICLE-TESTS-1234",
    "status": "active"
}
Example of successful creation response body:
{
    "status": "ok",
    "message": "Device created successfully"
}
Example request in Postman:
CreateDevice.png

Position#

This method allows sending location information inside the HUB using, preferably, the endpoint /position/create to send GPS data. This is the standard format that the Tracker HUB expects data to come in. The Tracker HUB will then store the data for analysis and reporting.
If the client cannot adapt the payload to the Tracker HUB format, they may request a specific vendor adapter endpoint. This adapter will internally parse the incoming payload into a format suitable for the HUB.
It also allows sending location information inside the HUB in different formats by specifying the provider's format in the URL path — e.g. position/vendor/traccar or position/vendor/gpschile — or by sending the expected default format on position/create.
For the operation to succeed, a Device entity must be previously registered, which in turn requires both a device type and a tracker to exist. Endpoints for registering these entities are described in their respective documentation.

Request Response#

A JSON object with the status of the request: success or error, and the data families in a collection (array). In case of an error, a descriptive error message is returned.
Example 1: Success (200 OK)
{
    "status": "ok",
    "message": "Position created successfully"
}
Example create request in Postman:
CreatePositionDefault.png
Example vendor request in Postman:
In this example, the vendor endpoint is used with the testing vendor to parse a specific payload format at the endpoint /position/vendor/:vendor. In practice, clients should replace testing with their own vendor format.
CreatePosition.png

Latest Positions#

This method is designed to efficiently retrieve the latest positions of registered devices. Unlike querying the /position endpoints, which involves searching through all stored data, this method leverages a fast-access cache that stores the most recent position based on the latest creation date. It is typically used to display a device's current location on a map.

Request Response#

Example:
[
    {
        "instanceUuid": "123",
        "deviceId": 4,
        "longitude": -97.155281,
        "latitude": 25.997053,
        "timestamp": "2025-01-06T17:12:46.717Z"
    }
]
Example request in Postman:
GetLatestPosition.png

Movement Configurations#

This method allows editing the parameters considered for displaying calculated routes in the system. The parameters are:
minStopMinutes: Minimum time required to consider a segment as STOPPED (e.g., "3").
maxStopSpeedKmh: Minimum speed required to consider a segment as STOPPED (e.g., "1.0").
maxStopDistanceMeters: Minimum distance traveled to consider a segment as STOPPED (e.g., "50").
maxSpeedKmh: Speed limit to consider a position as above the speed limit (e.g., "50").
minMovementSpeedKmh: Minimum speed required to consider a segment as MOVING (e.g., "2.0").
minMovementDistanceMeters: Minimum distance required to consider a segment as MOVING (e.g., "100").
gapThresholdSeconds: Minimum time between data submissions to consider a segment as a GAP (e.g., "3600").
No client identifier is needed because it is implicitly defined internaly by the API key used for authenticating this request.

Request Response#

A JSON object with the status of the request. In case of an error, a descriptive error message is returned.
Example:
{
    "maxSpeedKmh": 70,
    "minStopMinutes": 3,
    "maxStopSpeedKmh": 1.0,
    "maxStopDistanceMeters": 50,
    "maxSpeedKmh": 50,
    "minMovementSpeedKmh": 2.0,
    "minMovementDistanceMeters": 100,
    "gapThresholdSeconds": 300
}
Example success response:
{
    "status": "ok",
    "message": "Config created successfully"
}
Example in Postman:
CreateConfig.png
Previous
03. Error Handling
Next
05. GPS Position Workflow