Skip to main content
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"]
    }
  }'
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"]
    }
  }'
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.