Get Tracks

Retrieve GPS track entries (recorded location history) for members over a specified time period. Each track entry represents a continuous movement segment with detailed statistics about distance, speed, altitude, and encoded path data.

REQUEST

POST https://api.hellotracks.com/api/gettracks

{
  "data": {
    "from": 1634567890000,
    "until": 1634654290000,
    "uids": [
      "<member-uid-1>",
      "<member-uid-2>"
    ],
    "withCourse": false
  }
}

Legacy format (deprecated but still supported):

POST https://api.hellotracks.com/api/gettracks

{
  "data": {
    "from": 1634567890000,
    "until": 1634654290000,
    "accounts": [
      "<uid-or-username>",
      "<uid-or-username>"
    ]
  }
}

from

long

required

Start timestamp in milliseconds (Unix epoch). Required.Defines the beginning of the time range for track retrieval.Example: 1634567890000 (October 18, 2021)

until

long

required

End timestamp in milliseconds (Unix epoch). Required.Defines the end of the time range for track retrieval.Example: 1634654290000 (October 19, 2021)

uids

array

Array of member UIDs to retrieve tracks for. Recommended format.

If provided: Returns tracks for specified members only
If omitted: Uses legacy accounts parameter

Example: ["abc123", "def456"]

accounts

array

Legacy parameter. Array of UIDs or usernames. Use uids instead for new integrations.Example: ["worker1@company.com", "worker2uid"]

withCourse

boolean

default:false

Include detailed course/heading information in encoded format.

true: Adds course_encoded field with directional data
false: No course data (smaller response)

Permissions

Must have view permissions for the requested members
Can only retrieve tracks for members in your organization or network
Company members can view employee tracks based on their role

RESPONSE

Modern format (when using uids):

{
  "status": 0,
  "tracks": [
    {
      "id": 13787157,
      "owner_uid": "je7oc8",
      "kind": "track_entry",
      "start_ts": 1447018045000,
      "end_ts": 1447021091000,
      "start_lat": 37.80146,
      "start_lng": -122.43145,
      "end_lat": 37.80122,
      "end_lng": -122.43148,
      "distance": 3503.1265,
      "waypoint_count": 275,
      "speed_avg": 4.140268,
      "speed_max": 12,
      "altitude_min": -44,
      "altitude_max": 0,
      "altitude_gain": 166,
      "altitude_loss": 159,
      "short_encoded": "cbveFpkgjVc...",
      "course_encoded": "cbveFpkgj...",
      "share_url": "https://hellotracks.com/!/@t/13787157",
      "labels": 0,
      "lat_min": 0,
      "lat_max": 0,
      "lng_min": 0,
      "lng_max": 0
    }
  ]
}

Legacy format (when using accounts):

{
  "status": 0,
  "accounts": {
    "worker@company.com": [
      {
        // ... same track entry structure as above
      }
    ],
    "abc123": [
      {
        // ... track entries for this member
      }
    ]
  }
}

status

integer

required

Status code. 0 indicates success.

tracks

array

(Modern format) Flat array of all track entries from all requested members.

accounts

object

(Legacy format) Object with keys as UIDs/usernames, values as arrays of track entries for that member.

Track Entry Structure

Each track entry contains: Identity & Type:

id (long): Unique track entry identifier
owner_uid (string): UID of the member who recorded this track
kind (string): Entry type, typically “track_entry”
labels (integer): Label flags/categories

Time Range:

start_ts (long): Track start timestamp in milliseconds
end_ts (long): Track end timestamp in milliseconds

Location:

start_lat (double): Starting latitude
start_lng (double): Starting longitude
end_lat (double): Ending latitude
end_lng (double): Ending longitude

Distance & Movement:

distance (double): Total distance traveled in meters
waypoint_count (integer): Number of GPS waypoints recorded

Speed:

speed_avg (double): Average speed in meters per second
speed_max (double): Maximum speed in meters per second

Altitude:

altitude_min (integer): Minimum altitude/elevation
altitude_max (integer): Maximum altitude/elevation
altitude_gain (integer): Total elevation gain in meters
altitude_loss (integer): Total elevation loss in meters

Encoded Path Data:

short_encoded (string): Polyline-encoded GPS path (Google Polyline format)
course_encoded (string): Encoded heading/direction data (if withCourse: true)

Bounds:

lat_min, lat_max (double): Latitude bounding box
lng_min, lng_max (double): Longitude bounding box

Sharing:

share_url (string): Public shareable URL for this track

Use Cases

Mileage Reporting: Sum distance values across tracks for reimbursement or tax reporting. Route Analysis: Decode short_encoded polyline to visualize actual paths taken. Performance Monitoring: Analyze speed_avg and distance to evaluate worker efficiency. GPS Breadcrumbs: Use waypoint_count and encoded paths to replay historical movements.

Examples

curl -X POST https://api.hellotracks.com/api/gettracks \
  --header 'API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{
    "data": {
      "from": 1634567890000,
      "until": 1634654290000,
      "uids": ["worker1uid", "worker2uid"]
    }
  }'

curl -X POST https://api.hellotracks.com/api/gettracks \
  --header 'API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{
    "data": {
      "from": 1634567890000,
      "until": 1634654290000,
      "uids": ["abc123"],
      "withCourse": true
    }
  }'

Timestamps: All timestamps are in milliseconds since Unix epoch (January 1, 1970 UTC). This is the standard Java/JavaScript timestamp format.

Polyline Encoding: The short_encoded field uses Google’s Polyline Encoding Algorithm. You can decode this using standard libraries to get the full GPS path with all waypoints.

Distance Units: All distances are in meters. Divide by 1000 to get kilometers, or multiply by 0.000621371 to get miles.

Speed Units: All speeds are in meters per second. Multiply by 3.6 for km/h or by 2.23694 for mph.

Locate - Get current real-time locations
Create Report - Generate mileage and activity reports
Get Members - Retrieve member information

API Documentation

Job Management

Dispatch and Routing

Location

Account Management

Place Management

Reports

No-Code Integrations

REQUEST

Permissions

RESPONSE

Track Entry Structure

Use Cases

Examples

​REQUEST

​Permissions

​RESPONSE

​Track Entry Structure

​Use Cases

​Examples

​Related Endpoints

REQUEST

Permissions

RESPONSE

Track Entry Structure

Use Cases

Examples

Related Endpoints