Skip to main content
curl -X POST https://api.hellotracks.com/api/locate \
  --header 'API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{
    "data": {
      "withAddress": true,
      "accounts": {
        "worker1uid": {},
        "worker2@company.com": {}
      }
    }
  }'
Retrieve the current real-time location and status of members. This endpoint provides a lightweight response focused on location data, unlike /getaccounts which returns complete member profiles.

​
REQUEST

Locate specific members by UID or username: 
POST https://api.hellotracks.com/api/locate

{
  "data": {
    "withAddress": true,
    "withDetails": false,
    "accounts": {
      "<uid-or-username>": {},
      "<uid-or-username>": {}
    }
  }
}
Or locate all members in specific teams: 
POST https://api.hellotracks.com/api/locate

{
  "data": {
    "withAddress": false,
    "withDetails": true,
    "teams": [1, 2, 3]
  }
}
​
accounts
object
Object with member UIDs or usernames as keys. Each key maps to an empty object {}.Use this to locate specific members.Example: {"worker1uid": {}, "worker2@company.com": {}}
​
teams
array
Array of team numbers (integers) to locate all members in those teams.Alternative to accounts for team-based location retrieval.
  • If array is provided with team numbers: Returns members from those specific teams
  • If array is empty or not provided: Returns all company employees (if you have a company)
Example: [1, 2, 5]
​
withAddress
boolean
default:false
Include reverse-geocoded address for each location.
  • true: Adds address field with human-readable address
  • false: No address field (faster response)
​
withDetails
boolean
default:false
Include detailed device and connection information.
  • true: Adds device fields like connection_type, android_id, loc_gps_on, tracking_status
  • false: Basic location data only
​
signal
string
Optional signal command to send to devices.
  • "ping": Sends a ping signal to all devices, requesting them to update their location immediately
  • Devices that are online with internet connection will respond with fresh location data
  • signal_ts in response shows when device last received a ping

​
RESPONSE

{
  "status": 0,
  "accounts": [
    {
      "uid": "cubt5w",
      "usr": "worker@company.com",
      "name": "John Doe",
      "email": "john@company.com",
      "phone": "+14155551234",
      "lat": 37.801205,
      "lng": -122.43143,
      "ts": 1396985826428,
      "acc": 4,
      "dir": 10,
      "spd": 0,
      "elv": 20,
      "bat": 78,
      "teams": [{"name": "Zone G", "number": 4}],
      
      // If withAddress: true
      "address": "Chestnut Street, San Francisco, CA",
      
      // If withDetails: true
      "connection_type": 1,
      "android_id": "aa819713c067792e",
      "loc_gps_on": true,
      "loc_net_on": true,
      "tracking_status": true,
      "signal_ts": 1454894511000
    }
  ]
}
​
status
integer
required
Status code. 0 indicates success.
​
accounts
array
required
Array of location objects, one per member. Each contains:Core Identity:
  • uid (string): Member unique identifier
  • usr (string): Username/email
  • name (string): Full name
  • email (string): Email address
  • phone (string): Phone number
  • teams (array): Array of team objects with name and number
Location Data:
  • lat (double): Latitude
  • lng (double): Longitude
  • ts (long): Location timestamp in milliseconds (Unix epoch)
  • acc (integer): GPS accuracy in meters
  • dir (integer): Direction heading (0-360 degrees)
  • spd (double): Speed (meters per second)
  • elv (integer): Elevation/altitude
  • bat (integer): Battery level percentage (0-100)
Optional Fields (withAddress: true):
  • address (string): Reverse-geocoded street address
Optional Fields (withDetails: true):
  • connection_type (integer): Device internet connection type
  • android_id (string): Android device identifier
  • loc_gps_on (boolean): GPS enabled on device
  • loc_net_on (boolean): Network location enabled
  • tracking_status (boolean): HelloTracks tracking enabled
  • signal_ts (long): Timestamp of last ping signal received

​
Use Cases

Fleet Tracking: Monitor real-time positions of all field workers to optimize dispatching and provide customer ETAs. Team Location: View locations of specific team members working in a particular zone or on specific projects. Live Map Display: Build a live map dashboard showing current positions of all active workers. Ping for Updates: Request immediate location updates from devices by adding "signal": "ping" parameter.

​
Examples

curl -X POST https://api.hellotracks.com/api/locate \
  --header 'API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{
    "data": {
      "withAddress": true,
      "accounts": {
        "worker1uid": {},
        "worker2@company.com": {}
      }
    }
  }'
Timestamps: All timestamps are in milliseconds since Unix epoch (January 1, 1970 UTC). This is the standard Java/JavaScript timestamp format.
Ping Signal: When using "signal": "ping", only devices that are currently online with internet connectivity will respond with updated location. Offline devices will not update.
Performance: For frequent location polling, use this endpoint instead of /getaccounts as it returns a lighter payload focused on location data.