> ## 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]
  }
}
```

<ParamField body="accounts" type="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": {}}`
</ParamField>

<ParamField body="teams" type="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]`
</ParamField>

<ParamField body="withAddress" type="boolean" default={false}>
  Include reverse-geocoded address for each location.

  * `true`: Adds `address` field with human-readable address
  * `false`: No address field (faster response)
</ParamField>

<ParamField body="withDetails" type="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
</ParamField>

<ParamField body="signal" type="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
</ParamField>

### RESPONSE

```shell theme={null}
{
  "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
    }
  ]
}
```

<ResponseField name="status" type="integer" required>
  Status code. `0` indicates success.
</ResponseField>

<ResponseField name="accounts" type="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
</ResponseField>

### 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

<RequestExample>
  ```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@company.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
      }
    }'
  ```
</RequestExample>

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

<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.
</Note>

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

### Related Endpoints

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