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

05. GPS Position Workflow

To begin sending GPS data to the Tracker HUB, clients must follow these essential steps, ensuring all necessary entities and relationships are properly configured.
Steps marked as (Internal) are handled by the Exati Tracker Hub team, while steps marked as (Client) are managed by the client.

1. Register the Client (Internal)#

Begin by registering your client in the system. This step creates the foundational entity required for client isolation and ensures proper access control for all subsequent operations.

2. Register the Vendor (Internal)#

Add the vendor (e.g., gpschile, traccar) to the system. The vendor represents the GPS provider or service responsible for sending data to the Tracker HUB.

3. Create a Client-Vendor Link (Internal)#

Establish a link between the registered client and vendor. This relationship is critical for associating incoming GPS data with the correct client and vendor.
Considerations:
The link identifier is used implicitly in subsequent operations based on request headers provided during authentication. Such as when creating a new Device, this information is implicitly used.
If this link is not defined, the creation of a new device will result in an Entity Not Found error, even if all of the request payload parameters are correctly set.

4. Register Trackers (Client)#

Create trackers in the system to represent the physical devices sending GPS data. Each tracker must be registered with a unique identifier (such as IMEI). This step ensures that the system can correctly associate GPS data with the corresponding tracker, and allows the correct creation of a Device, which requires a Tracker entity to link with.
Considerations:
A Tracker identifier is a mandatory field when creating a Device.
Ensure that the identifier (e.g., IMEI) is valid and corresponds to the actual physical device. This value must be unique across all trackers in the HUB, as required by its standard.

5. Define Device Types (Internal)#

Query and select from the available device types or, if necessary, request to register new ones. Device types represent the capabilities or classifications of the devices being tracked and are also required for device registration.
Considerations:
Device Types are internally managed, but any client is able to list the available types to make an informed decision on which type to use when creating a new device.
The Device Type is a mandatory field when creating a Device.

6. Register Devices (Client)#

Using the previously defined entities, register your devices with the system, associating each device with a specific device type and tracker. This will only be possible if the client-vendor link exists, as this association is implicitly required for successful device registration.
Considerations
A Device is a mandatory field when sending Position data.

7. Send GPS Positions (Client)#

Use 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.
Considerations:
If the timestamp field in the payload is not provided, the system will default to using the time the payload was received as the position's timestamp.
The timestamp can be in any timezone, and the Tracker HUB will always store and return the timestamp in UTC.
The same goes for querying time intervals, the start and end dates can be in any timezone, and the interval will always compare them in UTC
Timestamp values for both payloads and filter parameters follow the RFC 3339 standard, which is a stricter subset of the ISO 8601 standard.
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.

In such cases, replacing :vendor with the appropriate registered vendor name in the /position/vendor/:vendor endpoint ensures the payload is correctly processed and adheres to the system's requirements.

8. Configure Movement Parameter Filters (Client)#

This step is optional, as the system provides a default set of values for this configuration. Clients have the option to configure filters for movement parameters. These filters help refine and optimize the data sent to and processed by the system, such as setting thresholds for speed, distance, or idle time.
Considerations:
The values configured in this step are essential for estimating TRIPS and STOPS from the stream of datapoints sent to the HUB when generating movement reports.

9. Generate Reports (Internal)#

The Tracker HUB system then processes the GPS data and generates reports summarizing movement and device activity. These reports are accessible to clients and are useful for analyzing trends, optimizing operations, and meeting business objectives.
Previous
04. Input Operations
Next
API