Trip Replay

Overview

V2 consolidates trip replay into a single paginated endpoint. Each TripDto covers one completed movement segment:

Field	Description
`distance`	Trip distance in km between the trip’s first and last point inside the requested window; `null` when either odometer reading is missing
`duration`	Time between the trip’s first and last point inside the requested window, as a .NET TimeSpan string, `[d.]hh:mm:ss[.fffffff]` (e.g. `"00:28:14"`)
`startAddress` / `endAddress`	Reverse-geocoded start and end addresses
`startTimeUser` / `endTimeUser`	Time of the trip’s first/last point inside the requested window, in the API key’s time zone, formatted `MM/dd/yyyy HH:mm:ss` (not ISO 8601)
`encoded`	Google Polyline Algorithm–encoded path of the first 400 entries of `points`
`url`	Ready-to-use Google Static Maps URL for a thumbnail
`points`	Every waypoint inside the requested window, with speed, direction, ignition, fuel, and odometer

V2 uses a single GET /v2/api/replay/{id} endpoint, where {id} is the public vehicle ID (deviceId). Each point carries both a UTC and an API-key-time-zone timestamp, so there is no separate user-time variant.

Step 1 — Request a date range

Fetch trips for vehicle 1000 over one week. Pass from and to as ISO 8601 UTC strings:

curl -s \
  "https://api.telemax.com.au/v2/api/replay/1000?from=2025-05-01T00:00:00Z&to=2025-05-08T00:00:00Z&page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

import os
import time

import requests

API_BASE = os.environ.get("TELEMAX_API_BASE", "https://api.telemax.com.au")
API_KEY = os.environ["TELEMAX_API_KEY"]
VEHICLE_ID = int(os.environ.get("TELEMAX_VEHICLE_ID", "1000"))      # public vehicle ID (deviceId)
FROM = os.environ.get("REPLAY_FROM", "2025-05-01T00:00:00Z")
TO = os.environ.get("REPLAY_TO", "2025-05-08T00:00:00Z")

session = requests.Session()


def get_token():
    r = session.post(f"{API_BASE}/v2/api/authentication/token/api-key", data={"apiKey": API_KEY}, timeout=30)
    r.raise_for_status()
    return r.json()["access_token"]


TOKEN = get_token()


def request(path, params=None, headers=None):
    """One GET. Waits out a short 429; stops when an hourly or daily budget is exhausted."""
    while True:
        r = session.get(f"{API_BASE}{path}", params=params, timeout=30,
                        headers={**(headers or {}), "Authorization": f"Bearer {TOKEN}"})
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", "1"))
            if wait >= 3600:
                raise RuntimeError(f"Rate-limit budget exhausted (Retry-After: {wait} s); try again later")
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r


data = request(f"/v2/api/replay/{VEHICLE_ID}", {"from": FROM, "to": TO, "page": 1, "pageSize": 20}).json()
trips = data["items"] or []
print(f"{len(trips)} trip(s) on page {data['currentPage']} of {data['numberOfPages']}")

Step 2 — Inspect the response

The response is a paginated envelope. Each element in items is a TripDto (abridged below: one trip and one point shown):

{
  "items": [
    {
      "distance": 14,
      "duration": "00:20:22",
      "startAddress": "31, Diamantina Cir, Karalee, Brisbane, Qld, AUS",
      "endAddress": "5, Gordon St, Ipswich, Brisbane, Qld, AUS",
      "startTimeUser": "05/12/2026 11:09:09",
      "endTimeUser": "05/12/2026 11:29:31",
      "encoded": "zdagDkuzc\\??z@wB~C_DRR...",
      "url": "https://maps.googleapis.com/maps/api/staticmap?...",
      "points": [
        {
          "lat": -27.536263, "lng": 152.840733,
          "timeUtc": "2026-05-12T01:09:09",
          "timeUser": "2026-05-12T11:09:09",
          "speed": 0, "direction": 260,
          "ignition": true, "odo": 47465,
          "fuelLevel": 92, "fuelVolume": null
        }
      ]
    }
  ],
  "currentPage": 1,
  "numberOfPages": 2,
  "totalResults": 31,
  "lastResultIndex": 20
}

Point fields:

Field	Type	Description
`lat` / `lng`	number	GPS coordinates
`timeUtc`	string	Waypoint timestamp (UTC, no `Z` suffix)
`timeUser`	string	Waypoint timestamp in the API key’s time zone
`speed`	number	Speed at this point (km/h)
`direction`	number	Heading in degrees (0–359)
`ignition`	boolean	Ignition state at this point
`odo`	number \| null	Odometer reading (km)
`fuelLevel`	integer \| null	Fuel level (%)
`fuelVolume`	number \| null	Fuel volume (litres)

Step 3 — Decode the `encoded` polyline

The encoded field uses the Google Polyline Algorithm format, supported by all major mapping SDKs. It covers only the first 400 entries of points; draw from points when a trip has more.

# pip install polyline
import polyline


def decode_trip(trip):
    coords = polyline.decode(trip["encoded"])  # list of (lat, lng) tuples — at most the first 400 entries of points
    print(f"{trip['startAddress']} → {trip['endAddress']}: {len(coords)} decoded points "
          f"of {len(trip['points'])}, {trip['distance']} km, {trip['duration']}")
    return coords


for trip in trips:
    coords = decode_trip(trip)

// `trips` is the `items` array of the replay response (Step 2). Save as a .mjs file (an ES module).
// npm install @mapbox/polyline
import polyline from "@mapbox/polyline";

for (const trip of trips) {
  const coords = polyline.decode(trip.encoded); // [[lat, lng], ...] — at most the first 400 entries of points
  console.log(
    `${trip.startAddress} → ${trip.endAddress}: ${coords.length} decoded points of ${trip.points.length}, ` +
    `${trip.distance} km, ${trip.duration}`
  );
}

Step 4 — Render on a map

// Assumes a Leaflet map initialised as `map`, and `trips` as above. Draw from `points`, which holds every point in the requested
// window; `encoded` covers only the first 400 of them.
for (const trip of trips) {
  const coords = trip.points.map((p) => [p.lat, p.lng]);
  if (!coords.length) continue;

  L.polyline(coords, { color: "#0075FF", weight: 3 }).addTo(map);
  L.marker(coords[0]).bindPopup(`<b>Start</b><br>${trip.startAddress}<br>${trip.startTimeUser}`).addTo(map);
  L.marker(coords[coords.length - 1]).bindPopup(`<b>End</b><br>${trip.endAddress}<br>${trip.endTimeUser}`).addTo(map);
}

const allCoords = trips.flatMap((t) => t.points.map((p) => [p.lat, p.lng]));
if (allCoords.length) map.fitBounds(allCoords);

Fetching all pages

For long date ranges, iterate through all pages:

Python

def fetch_all_trips(vehicle_id, from_dt, to_dt):
    """Every page. Follow-up pages reuse the pagination session, so they do not count against the rate limit."""
    all_trips, page, session_token = [], 1, None
    while True:
        r = request(f"/v2/api/replay/{vehicle_id}", {"from": from_dt, "to": to_dt, "page": page, "pageSize": 20},
                    {"X-Session-Token": session_token} if session_token else None)
        body = r.json()
        all_trips.extend(body.get("items") or [])
        session_token = r.headers.get("X-Session-Token", session_token)
        if page >= body.get("numberOfPages", 1):
            return all_trips
        page += 1


all_trips = fetch_all_trips(VEHICLE_ID, FROM, TO)

Google Static Maps thumbnail

The url field is a complete Google Static Maps URL. Use it server-side to generate a trip thumbnail without decoding the polyline. Use it exactly as returned — do not add parameters:

Python

# The url is complete. Use it exactly as returned; do not add parameters.
for i, trip in enumerate(all_trips):
    img = session.get(trip["url"], timeout=30)
    img.raise_for_status()
    with open(f"trip_{i}.png", "wb") as f:
        f.write(img.content)

Gotchas

Distance unit: distance is in kilometres, measured inside the requested window, and can be null.
Duration format: duration is a .NET TimeSpan string ([d.]hh:mm:ss[.fffffff]), not ISO 8601 PT... format.
Single endpoint: V2 has one replay endpoint. Both UTC and API-key-time-zone fields are returned on each point.
encoded is partial: it covers the first 400 entries of points. Draw from points for the full path.

Getting Started

Guides

Authentication

Companies & fleet

Vehicles

Vehicle commands

Alerts

Telemetry & replay

Insights & diagnostics

Webhooks

Reference

Overview

Step 1 — Request a date range

Step 2 — Inspect the response

Step 3 — Decode the `encoded` polyline

Step 4 — Render on a map

Fetching all pages

Google Static Maps thumbnail

Gotchas

​Overview

​Step 1 — Request a date range

​Step 2 — Inspect the response

​Step 3 — Decode the encoded polyline

​Step 4 — Render on a map

​Fetching all pages

​Google Static Maps thumbnail

​Gotchas

Overview

Step 1 — Request a date range

Step 2 — Inspect the response

Step 3 — Decode the `encoded` polyline

Step 4 — Render on a map

Fetching all pages

Google Static Maps thumbnail

Gotchas