Guides
SUPPORTFEEDBACK

GPS asset tracking

Monitor asset locations and telematics for vehicles and trailers

Suggest Edits

Fleets depend on accurate, real-time location data to manage daily operations, plan dispatches, and provide visibility to customers. This guide shows how to integrate Samsara's APIs to track vehicles and trailers in your TMS.

Overview

  1. Vehicle tracking

    • Monitor live vehicle locations.
    • Plan dispatches based on vehicle proximity and availability.

  2. Trailer tracking

    • Track trailer locations independently of tractors.
    • Understand asset utilization and deploy trailers more effectively.

  3. Historical data

    • Reconstruct routes, investigate exceptions, or fill gaps if your real-time polling is interrupted.
    • Generate analytical insights like utilization or dwell times.

Key endpoints

Samsara offers multiple endpoints to retrieve location data. Which one you use depends on your use case: a simple point-in-time snapshot, near real-time feed, or historical queries.

1. Vehicles

  • Latest snapshot

    • GET /fleet/vehicles/stats
    • Retrieve the current (most recent) telematics data for each vehicle in your fleet.

  • Continuous feed

    • GET /fleet/vehicles/stats/feed
    • Return GPS and other telematics events since your last request. Ideal for near real-time location updates (e.g., polling every 5–30 seconds).

  • Historical backfill

    • GET /fleet/vehicles/stats/history
    • Retrieve historical events in a specified time range to fill gaps or run reports. Not recommended for continuous streaming.

2. Trailers

  • Snapshot

    • GET /beta/fleet/trailers/stats
    • Fetch a point-in-time location and telematics snapshot for trailers.

  • Streaming location updates

    • GET /assets/location-and-speed/stream
    • Continuously retrieve new locations for assets (including trailers). This endpoint supports useful query parameters such as includeReverseGeo (address lookup) and includeGeofenceLookup (geofence ID lookup).

Example request:

curl -X GET 'https://api.samsara.com/assets/location-and-speed/stream?ids=123&startTime=2025-03-01T00:00:00Z&includeReverseGeo=true&includeGeofenceLookup=true' \
  --header "Authorization: Bearer <TOKEN>"

Example response:

{
  "data": [
    {
      "happenedAtTime": "2025-03-11T10:21:19Z",
      "asset": {
        "id": "281474994182986"
      },
      "location": {
        "latitude": 42.93845637,
        "longitude": -71.53398559,
        "headingDegrees": 0,
        "accuracyMeters": 2.868,
        "address": {
          "streetNumber": "74",
          "pointOfInterest": "",
          "neighborhood": "",
          "street": "Briar Road",
          "city": "Bedford",
          "state": "NH",
          "postalCode": "03110",
          "country": "US"
        },
        "geofence": {
          "id": "232149051"
        }
      }
    }
  ],
  "pagination": {
    "endCursor": "...",
    "hasNextPage": true
  }
}

Example usage

Choose the approach that fits your needs:

  1. Occasional snapshots

    • Use GET /fleet/vehicles/stats or GET /beta/fleet/trailers/stats for simple on-demand lookups when you only need to show the current location.

  2. Near real-time tracking

    • Poll GET /fleet/vehicles/stats/feed or GET /assets/location-and-speed/stream at a fixed interval (e.g., every 5–30 seconds) to retrieve incremental updates.
    • This approach ensures that you can quickly display changes in location or heading within your TMS.

  3. Historical backfill

    • If your feed-based integration temporarily goes down, you can use GET /fleet/vehicles/stats/history (with a time range) to retrieve any missed data points.

  4. Augmenting location data with addresses or geofences

    • Pass includeReverseGeo=true to include street-level address details.
    • Pass includeGeofenceLookup=true to return any Samsara geofences that match the asset’s current position.

Sample workflow: near real-time vehicle and trailer tracking

  1. Initialize

    • Call GET /fleet/vehicles/stats?types=gps and GET /beta/fleet/trailers/stats?types=gps once at startup to populate your TMS with current locations for all vehicles and trailers.

  2. Continuous sync

    • Poll GET /fleet/vehicles/stats/feed?types=gps and/or GET /assets/location-and-speed/stream?reverseGeo=true&geofenceLookup=true every few seconds to retrieve any new GPS events.
    • Match each incoming event to the corresponding vehicle or trailer in your TMS (e.g., using externalIds).

  3. UI updates

    • As soon as new data arrives, update your TMS map view or other tracking interfaces.
    • Show relevant details such as last known address, speed, and geofence if available.

  4. Historical recovery

    • If a polling outage or network error occurs, backfill missing points using GET /fleet/vehicles/stats/history with a time range.
    • This ensures no gaps in trip history or reporting.

Example requests and responses

Get the latest vehicle snapshot

Example request:

curl 'https://api.samsara.com/fleet/vehicles/stats?types=gps' \
--header "Authorization: Bearer <TOKEN>"

Example response:

{
  "data": [
    {
      "id": "123",
      "name": "Truck",
      "externalIds": {
        "samsara.serial": "G522SBGJT9",
        "samsara.vin": "123"
      },
      "gps": {
        "time": "2025-03-25T18:23:17Z",
        "latitude": 43.34141535,
        "longitude": -74.74746674,
        "headingDegrees": 0,
        "speedMilesPerHour": 0,
        "reverseGeo": {
          "formattedLocation": "Fuller Drive, Boylston, MA, 01505"
        },
        "isEcuSpeed": false
      }
    }
  ],
  "pagination": {
    "endCursor": "",
    "hasNextPage": false
  }
}

Get incremental trailer location updates

Example request:

curl -X GET 'https://api.samsara.com/assets/location-and-speed/stream?includeReverseGeo=true&includeGeofenceLookup=true&ids=123&startTime=2025-03-10T00:00:00Z' \
--header "Authorization: Bearer <TOKEN>"

Example response:

{
  "data": [
    {
      "happenedAtTime": "2025-03-10T14:15:06Z",
      "asset": {
        "id": "123"
      },
      "location": {
        "latitude": 43.94845637,
        "longitude": -72.53393359,
        "headingDegrees": 0,
        "accuracyMeters": 2.868,
        "address": {
          "streetNumber": "1",
          "pointOfInterest": "",
          "neighborhood": "",
          "street": "Main Road",
          "city": "Somewhere",
          "state": "FL",
          "postalCode": "03330",
          "country": "US"
        },
        "geofence": {
          "id": "232149051"
        }
      }
    }
  ],
  "pagination": {
    "endCursor": "...",
    "hasNextPage": true
  }
}

Use Kafka for near real-time streaming

For large fleets or advanced analytics use cases, Samsara's Kafka Connector provides a high-throughput, near real-time stream of GPS and telematics data. Instead of periodically polling an API, the connector continuously pushes location events, speed updates, and more to your Kafka environment.

Key benefits

  • Frequent push updates: Suitable for TMS solutions that require very high-frequency location data.
  • Scalability: Easily handle large fleets and massive data volumes by leveraging Kafka’s horizontal scaling.
  • Real-time analytics: Integrate with stream-processing frameworks (e.g., Apache Spark, Flink) for advanced analytics, real-time dashboards, or machine-learning pipelines.

How it works

  1. Setup the Samsara Kafka Connector:

    • Configure the connector in the Samsara Dashboard and provide your Kafka cluster details.
    • Select the event types (e.g., GPS and Speed, Diagnostics) you want streamed.

  2. Consume events in your TMS:

    • Implement a Kafka consumer in your TMS or data pipeline to read location messages as they arrive.
    • Samsara publishes each event containing asset and location details, such as latitude, longitude, speed, and timestamps.

  3. Process and store data:

    • Parse each message to associate the event with the correct vehicle, trailer, or other asset.
    • Optionally enrich location data by reversing geocodes or matching geofences before persisting to your TMS database.

Example message format

Below is an illustrative JSON payload you might receive for a GPS and speed event via Kafka:

{
  "asset": {
    "id": "123"
  },
  "happenedAtTime": "2023-12-19T17:57:21Z",
  "location": {
    "accuracyMeters": 0,
    "geofence": {},
    "headingDegrees": 102,
    "latitude": 38.253265915,
    "longitude": -80.018465004
  },
  "speed": {
    "gpsSpeedMetersPerSecond": 43.8,
    "ecuSpeedMetersPerSecond": 51.2
  }
}

When to choose Kafka

  • High-frequency updates: You need sub-minute location data without constantly polling an HTTP endpoint.
  • Event-driven architecture: Your TMS or analytics platform is already built on Kafka, or you want to leverage Kafka’s decoupled, scalable design.
  • Complex data pipelines: You plan to enrich or correlate location events with other real-time sources (e.g., weather, traffic) before serving them to end users.

For more details, see the Samsara Kafka Connector documentation.

Updated about 1 hour ago

What’s Next