API reference

Location history

The locations a device reported over time, newest first.

Import the whole API:OpenAPI 3.1 Postman collection

WeGuard records history only while the device’s policy has location tracking turned on. History is kept for about 65 days on Android and 60 days on Apple devices. Windows history does not expire automatically. On Windows, you get only the points recorded since the device’s current enrollment, not points from an earlier enrollment, even one in your own account. On Android, history follows the physical device within your account, so it can include points from an earlier enrollment of the same device, within the retention period.

If you only need the most recent position, use Retrieve a device’s location.

The location point object

One reported position, in WGS 84 decimal degrees. Optional measurements are null when the device did not report them or reported an invalid value. Points without valid coordinates are never returned.

AttributeDescription

id string: Unique id of the location point.
object string: Always location_point.
latitude number: Latitude in decimal degrees.
longitude number: Longitude in decimal degrees.
accuracyMeters numbernullable: Horizontal accuracy radius in meters.
altitudeMeters numbernullable: Altitude in meters, as reported by the device. Android and Windows devices report 0 when the altitude is unknown.
speedMetersPerSecond numbernullable: Ground speed in meters per second. Android and Windows devices report 0 when the speed is unknown.
headingDegrees numbernullable: Direction of travel in degrees (0 to 360), clockwise from true north. Reported by Apple devices only. Always null on Android and Windows.
recordedAt timestamp: When the device captured the location.

Example

{
  "id": "6701c2e5f1a2b3c4d5e6f789",
  "object": "location_point",
  "latitude": 17.4474,
  "longitude": 78.3762,
  "accuracyMeters": 12.4,
  "altitudeMeters": 512.3,
  "speedMetersPerSecond": 0.3,
  "headingDegrees": null,
  "recordedAt": "2026-10-07T09:20:00Z"
}

List a device’s location history

GET/v1/devices/{deviceId}/locations

Requireslocations:read

Returns the locations the device reported between since and until, newest first, as a paginated list. If you omit both since and until, you get the last 24 hours. See Time ranges.

Location history is personal data about the people who use your devices. Grant locations:read only to integrations that need it, request only the window you need, and handle the data according to your privacy obligations.

Path parameters

ParameterDescription

deviceId stringrequired: Id of the device. Case-insensitive.

Query parameters

ParameterDescription

since timestampoptionaldefault 24 hours before until: Start of the time range (inclusive), as an ISO-8601 timestamp with a UTC offset, for example 2026-10-01T00:00:00Z. Must be earlier than until. The range can span at most 31 days. See Time ranges.
until timestampoptionaldefault now: End of the time range (exclusive), as an ISO-8601 timestamp with a UTC offset. If you omit it, the first page fixes “now” and every nextCursor carries that value, so all pages cover the same window. In that case the maximum span of 31 days allows 5 minutes of clock tolerance.
limit integeroptionaldefault 100: Maximum number of items to return, from 1 to 1000.
cursor stringoptional: The nextCursor from the previous page. Send it unchanged, together with the same filters. See Pagination.
includeTotal booleanoptionaldefault false: Set to true to also return totalCount. It runs an extra count, so request it only when you need it.

Example request

curl "https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d40012345678/locations?since=2026-10-07T00:00:00Z&until=2026-10-08T00:00:00Z&limit=2" \
  -H "Authorization: Bearer $WEGUARD_API_KEY"

const response = await fetch("https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d40012345678/locations?since=2026-10-07T00:00:00Z&until=2026-10-08T00:00:00Z&limit=2", {
  headers: { Authorization: `Bearer ${process.env.WEGUARD_API_KEY}` },
});

const body = await response.json();
if (!response.ok) {
  throw new Error(`${body.code}: ${body.detail} (requestId ${body.requestId})`);
}
console.log(body);

import os
import requests

response = requests.get(
    "https://api-gw.weguard.ai/core/v1/devices/6523f1c2a7b9d40012345678/locations",
    params={
        "since": "2026-10-07T00:00:00Z",
        "until": "2026-10-08T00:00:00Z",
        "limit": 2,
    },
    headers={"Authorization": f"Bearer {os.environ['WEGUARD_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
print(response.json())

Response

A list object whose data holds location point objects, newest first. An empty list with hasMore: false means there is no history in the window. The API skips points without valid coordinates. As a result, a page can hold fewer than limit points while hasMore is true, and totalCount (with includeTotal=true) can be higher than the number of points you receive across all pages.

200 OK

{
  "object": "list",
  "data": [
    {
      "id": "6701c2e5f1a2b3c4d5e6f789",
      "object": "location_point",
      "latitude": 17.4474,
      "longitude": 78.3762,
      "accuracyMeters": 12.4,
      "altitudeMeters": 512.3,
      "speedMetersPerSecond": 0.3,
      "headingDegrees": null,
      "recordedAt": "2026-10-07T09:20:00Z"
    },
    {
      "id": "6701c2b1f1a2b3c4d5e6f701",
      "object": "location_point",
      "latitude": 17.4452,
      "longitude": 78.3791,
      "accuracyMeters": 18.5,
      "altitudeMeters": 498.7,
      "speedMetersPerSecond": 1.4,
      "headingDegrees": null,
      "recordedAt": "2026-10-07T09:05:00Z"
    }
  ],
  "hasMore": true,
  "nextCursor": "dDE6MTc5MTQxNDAwMDAwMDo2NzAxYzJlNWYxYTJiM2M0ZDVlNmY3ODk"
}

Errors

404resource_not_found
No device with this id exists in your account.
400invalid_parameter
since or until is not an ISO-8601 timestamp with an offset, or is outside the range 1970-01-01T00:00:00Z to 9999-12-31T23:59:59.999Z; since is not earlier than until; the range is longer than 31 days; limit or includeTotal is invalid; or a parameter was sent twice.
400unknown_parameter
The request includes a query parameter this endpoint does not accept.
400invalid_cursor
The cursor is malformed, or was issued for a different listing: another path, other filters, or another since / until.
403insufficient_scope
The key lacks locations:read.

Common errors

Besides the errors listed for each endpoint, any request can fail authentication, exceed the rate limit, ask for a format other than JSON, or fail with a server error. See Errors for the response format and retry guidance.

401missing_credentials
The request has no Authorization header.
401invalid_authorization_header
The Authorization header does not use the Bearer scheme, or has no key after it. The WWW-Authenticate header carries error="invalid_request".
401invalid_api_key
The key is malformed, does not exist, or its secret does not match. The WWW-Authenticate header carries error="invalid_token".
401api_key_expired
The key is past its expiresAt.
401api_key_revoked
An account admin revoked the key. Revocation takes effect immediately and cannot be undone.
403account_inactive
The WeGuard account that owns the key has been deleted or disabled.
406not_acceptable
The Accept header excludes JSON.
429rate_limit_exceeded
The key has used up its request budget. See Rate limits.
500internal_error
An unexpected error occurred on our side.
503service_unavailable
A service WeGuard depends on is temporarily unavailable, or reading the data took longer than the time WeGuard allows for it. This can also happen while your key is being checked, so it can be returned before authentication completes. The response carries Retry-After.