> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.hellotracks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Locate

> Get real-time location of members in your organization.

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:**

```shell theme={null}
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:**

```shell theme={null}
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@example.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: Returns no team-selected members
* If omitted: Only members explicitly listed in `accounts` are returned
* To locate all company employees, send `teams` as a non-array value such as `true`

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

```shell theme={null}
{
  "status": 0,
  "accounts": [
    {
      "uid": "a1b2c3",
      "usr": "worker@example.com",
      "name": "John Doe",
      "email": "john@example.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": "0123456789abcdef",
      "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` (integer): Speed in km/h (-1 if unknown)
* `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

```bash Locate Specific Members theme={null}
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@example.com": {}
      }
    }
  }'
```

```bash Locate Team with Ping theme={null}
curl -X POST https://api.hellotracks.com/api/locate \
  --header 'API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{
    "data": {
      "teams": [1, 2],
      "signal": "ping",
      "withDetails": true
    }
  }'
```

```bash Locate All Employees theme={null}
curl -X POST https://api.hellotracks.com/api/locate \
  --header 'API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  -d '{
    "data": {
      "teams": true,
      "withAddress": true
    }
  }'
```

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

> [!NOTE]
>
> **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.

> [!TIP]
>
> **Performance:** For frequent location polling, use this endpoint instead of `/getaccounts` as it returns a lighter payload focused on location data.

### Related Endpoints

* [Get Members](https://api-docs.hellotracks.com/api-reference/endpoint/getaccounts.md) - Full member profiles with all properties
* [Get Tracks](https://api-docs.hellotracks.com/api-reference/endpoint/gettracks.md) - Historical GPS track data
* [Member Object](https://api-docs.hellotracks.com/api-reference/member-object.md) - Complete member data structure


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.