Get an asset’s GPS history

Request#

GET /api/v1/gps/assets/{asset}/history

Requires assets:read and assets:tracking. See token permissions. Every listed permission is required for this endpoint.

Send Authorization: Bearer YOUR_API_TOKEN and Accept: application/json.

asset is the numeric asset ID in your token’s organization. The asset must have a GPS tracker.

Query parameters#

period string Required

today, yesterday, this_week, previous_week, this_month, previous_month, or custom. Periods are calendar days in UTC, and weeks start on Monday.

from_date string Optional

Required when period is custom. First day, YYYY-MM-DD, from the start of that day in UTC. Cannot be in the future.

to_date string Optional

Required when period is custom. Last day, YYYY-MM-DD, through the end of that day in UTC. On or after from_date. The range can cover at most 31 days, counting both, such as 2026-09-01 to 2026-10-01.

Example#

Set ASSETCENTER_API_TOKEN as described in the quick start. Replace example record and option IDs with values from your organization.

curl --request GET "https://my.assetcenter.app/api/v1/gps/assets/123/history?period=custom&from_date=2026-09-01&to_date=2026-09-07" \
  --header "Authorization: Bearer $ASSETCENTER_API_TOKEN" \
  --header "Accept: application/json"

Response#

200 OK. range is the UTC window that was searched; it ends at the current time when the period includes today.

{
  "data": [
    {
      "id": 42402201,
      "lat": 47.6051,
      "lng": -122.3344,
      "fix_at": "2026-10-02T15:57:00Z",
      "speed_mph": 5.8,
      "course": 45,
      "address": "300 Pike St, Seattle, WA",
      "segment_id": "current-18-1790697600"
    },
    {
      "id": 42402202,
      "lat": 47.6062,
      "lng": -122.3321,
      "fix_at": "2026-10-02T16:00:00Z",
      "speed_mph": 0,
      "course": 90,
      "address": "400 Pine St, Seattle, WA",
      "segment_id": "current-18-1790697600"
    }
  ],
  "count": 2,
  "range": {
    "from": "2026-10-02T00:00:00.000000Z",
    "to": "2026-10-02T16:00:00.000000Z"
  }
}

Behavior and constraints#

Positions are ordered oldest first. Each has the tracker’s position id, coordinates, fix_at, speed_mph, course, and address when known. History follows the asset rather than a device: when trackers were swapped during the range, each tracker’s positions carry their own segment_id, so draw a separate line for each segment. Only positions recorded while a tracker was attached to this asset are returned.

A range can return up to 5,000 positions; a busier range returns 422 on period asking for a shorter one. The request also returns 422 on period when no tracker was attached during the range or tracking is not set up yet. If the GPS provider cannot be reached, the response is 503; retry later. GPS tracking must be enabled for the organization; otherwise the request returns 403. See GPS tracking in the user manual.

Errors#

401 means the token is missing, expired, revoked, or not a customer API token. 403 means a required permission or administrator access is missing. 404 means the asset is unavailable or has no tracker. 422 identifies invalid or unsupported input; inspect the errors object when present. 429 means a rate limit was reached. See error handling and rate limits. 503 means GPS history could not be loaded; retry later.