> For the complete documentation index, see [llms.txt](https://docs.sonoransoftware.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonoransoftware.com/cad/api-integration/websocket-api/unit-locations.md).

# Unit Locations

## Rate Limits

* Maximum of one request every 250ms
* Maximum of 25 unit update objects per request

> Use this websocket method for high-frequency live map streaming when possible. The HTTP v2 alternative is [`PATCH /v2/emergency/servers/{serverId}/unit-locations`](/cad/api-integration/api-endpoints-v2/emergency/units/update-unit-locations.md), but that route is limited to 12 requests per minute.

## Websocket API

### Authentication Method

#### **Method:**

```
unitLocation
```

#### **Parameters:**

<table><thead><tr><th>Parameter</th><th>Type</th></tr></thead><tbody><tr><td><pre><code>data
</code></pre></td><td>Array of <code>unitLocationObject</code></td></tr></tbody></table>

#### Structure unitLocationObject

```js
  {
    communityUserId: "player-1234", // Optional alternative to apiId or identId
    roblox: 123456789, // Optional alternative to communityUserId, apiId, or identId
    apiId: "SOME_API_ID", // Optional
    identId: 42, // Optional
    location: "US-101 / Exit 15",
    coordinates: { x: 123.45, y: 678.9, z: 21.0, w: 180.0 },
    peerId: "bodycam-1-123", // Used only for P2P bodycam streams
    vehicle: {
      model: 'https://example.com/model.obj', // S3 URL to a 3D map object
      zOffset: 0, // Offset model Z (height) on map
      lightZOffset: 0, // Offset light effect Z (height) on map
      sizeOffset: 0, // Increase/Decrease Size
      headingOffset: 0, // Offset heading direction for 3D model
      lights: false // Show emergency lights flashing on model
    }
  }
```

Each update must include `location` plus one target identifier: `communityUserId`, `roblox`, `apiId`, or `identId`. Authenticate the SignalR connection first with [`authenticatev2`](/cad/api-integration/websocket-api/authentication.md).

### Response

#### Success

```
{ success: boolean, error: string, count: number }
```

#### Error

```
- Unauthenticated: "Unauthenticated. Call authenticate first."
- Missing/empty array: "Missing unit location updates."
- Batch too large: "Too many unit updates in one call. Max is 25."
- Too fast: "UNIT_LOCATION updates are limited to every 200ms."
- Invalid target: "Each unit update requires identId, apiId, communityUserId, or roblox, and location."
```

### Unit Location JS example (Node.js):

```js
setInterval(async () => {
  const updates = [
    {
      communityUserId: "player-1234",
      location: "Interstate 4 / Mile 228",
      position: { x: 8.5, y: 2.1, z: 0.0, w: 90.0 },
    },
  ];

  try {
    await connection.invoke("unitLocation", updates);
  } catch (err) {
    console.error("send failed:", err.message);
  }
}, 250);
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.sonoransoftware.com/cad/api-integration/websocket-api/unit-locations.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.