Skip to main content

Positions and Trip Services

This page explains how to retrieve vehicle positions and trip history with the Fleet API for both business and technical audiences.

Also known as

The dense sequence of GPS points recorded along a trip is also commonly called a waypoint list, GPS trail, or breadcrumb trail. This page uses "breadcrumb" and "waypoint"/"trail" interchangeably to refer to the same data.

Acronyms and Terms​

  • API: Application Programming Interface.
  • GPS: Global Positioning System.

Which Endpoint Should I Use?​

Use this mapping based on the location-related data you need:

1) All GPS Positions​

What It Means​

Retrieve historical position events over a period to reconstruct where a vehicle has been.

Best Endpoints​

Business Interpretation​

  • Use for investigations, trip replay, proof of presence, and operational audits.
  • Best source when users ask for "all points" across a time window.

Developer Interpretation​

  • Treat events as historical telemetry points.
  • Query by time windows and paginate as needed.
  • For long periods, fetch in chunks to avoid very large responses.

Recipe: Retrieving a GPS Breadcrumb Trail (Waypoints) for a Trip​

Use this recipe to get the dense GPS trail (waypoints) for a single trip, rather than every event type mixed together.

  1. Get the trip's time window. Call Get trips by registration (or Get all trips) for the date range you care about, and read start_timestamp/end_timestamp off the trip you want:

    GET /trips/{registration}?start_timestamp=2022-01-01 08:00:00&end_timestamp=2022-01-01 20:00:00
    {
      "data": [
        {
          "trip_id": 123456,
          "registration": "ABX123",
          "start_timestamp": "2022-01-01 08:12:00",
          "end_timestamp": "2022-01-01 08:49:00"
        }
      ]
    }

  2. Fetch the periodic GPS pings for that window. Call Get events for one vehicle using the trip's start_timestamp/end_timestamp, filtered to terminal_event_type_id=2 (PERIODIC_EVENT). This excludes discrete events like ignition, geofence, or harsh braking, and returns just the dense position pings that make up the breadcrumb trail:

    GET /vehicles/{registration}/events?start_timestamp=2022-01-01 08:12:00&end_timestamp=2022-01-01 08:49:00&terminal_event_type_id=2
    {
      "data": [
        {
          "event_id": 123456,
          "registration": "ABX123",
          "terminal_event_type_id": 2,
          "event_description": "PERIODIC_EVENT",
          "latitude": 1.320227,
          "longitude": 103.889653,
          "event_ts": "2022-01-01 08:12:02+00:00"
        },
        {
          "event_id": 123457,
          "registration": "ABX123",
          "terminal_event_type_id": 2,
          "event_description": "PERIODIC_EVENT",
          "latitude": 1.320318,
          "longitude": 103.889801,
          "event_ts": "2022-01-01 08:12:34+00:00"
        }
      ]
    }

    Each result is one waypoint on the trail. Points are typically spaced a few seconds to about a minute apart, depending on vehicle speed and hardware configuration.

2) Continuous Tracking (Near Real-Time)​

What It Means​

Show the latest known vehicle positions continuously, similar to a live fleet map.

Best Endpoint​

Business Interpretation​

  • Use for day-to-day live operations and dispatcher monitoring.
  • Best for "where is the vehicle now?" use cases.

Developer Interpretation​

  • Implement polling (for example every 10 to 30 seconds) to refresh latest states.
  • This is near real-time status polling, not a websocket streaming feed.
  • Combine with events endpoints when historical breadcrumb detail is required.

3) Full Trip History​

What It Means​

Depending on your use case, "trip history" can mean either:

  • Full breadcrumb points of a journey (also called waypoints or a GPS trail), or
  • Trip summaries with start and end locations.

Endpoint Selection​

Business Interpretation​

  • Use trips for reporting and KPI-level trip analysis.
  • Use events when analysts need path-level detail.

Developer Interpretation​

  • Trips are summary records and should not be treated as complete trip-point datasets.
  • Build full trip replay from events data for the selected time interval.

For most fleet applications:

  1. Poll the vehicle status endpoint for current map state.
  2. Query events endpoints for historical trip playback.
  3. Query trips endpoints for trip reporting (start/end and trip context).