Skip to main content

​
Overview

The Telemax API uses a polling model for real-time fleet visibility. There is no persistent WebSocket connection — your integration requests the current position snapshot at a regular interval.
ApproachWhen to use
GetAllLastPositionDataShow all vehicles for a company on a single map
GetLastPositionDataTrack one specific vehicle
Recommended polling interval: 30–60 seconds. Devices typically report every 30 seconds, so polling faster returns the same data and adds unnecessary load.

​
Step 1 — Authenticate

See Authentication for token details. Use the cached token pattern — request once, reuse for ~24 hours.
cURL
curl -s -X POST "https://api.telemax.com.au/api/Authentication/token/api-key" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "apiKey=YOUR_API_KEY"

​
Step 2 — Get your company ID

You need a companyId to call fleet endpoints. Retrieve it from GetCompanies: 
curl -s -X POST "https://api.telemax.com.au/api/GetCompanies" \
  -H "Authorization: Bearer YOUR_TOKEN"
The first Id in the response is your primary company ID.

​
Step 3 — Fetch all fleet positions

Call POST /api/GetAllLastPositionData/{companyId} with checkVehicleHandlerState=true to get the latest known position for every vehicle in the company.
cURL
curl -s -X POST "https://api.telemax.com.au/api/GetAllLastPositionData/85?checkVehicleHandlerState=true" \
  -H "Authorization: Bearer YOUR_TOKEN"
Key response fields per vehicle:
FieldTypeDescription
DeviceIdintegerVehicle ID (use for follow-up calls)
DeviceNamestringVehicle display name
Lat / LngdoubleWGS84 decimal degrees
SpeeddoubleUnit: km/h
IgnitionbooleanWhether ignition is on
UtcTimestringWhen this GPS fix was recorded (UTC, no Z suffix)
ConnectionStrenghstringDevice connectivity — "Excellent", "Good", "Poor"
UtcTime is when the GPS fix was recorded on the device, not when it was fetched. A vehicle parked for an hour will show a one-hour-old timestamp. Use ConnectionStrengh (intentional spelling — see Known Issues) to distinguish a parked vehicle from an offline one.

​
Step 4 — Poll on an interval

import os, time, requests

API_BASE = "https://api.telemax.com.au"
API_KEY  = os.environ["TELEMAX_API_KEY"]
COMPANY_ID = 85
POLL_INTERVAL = 30  # seconds

_token = None
_token_expires_at = 0

def get_token():
    global _token, _token_expires_at
    if _token and time.time() < _token_expires_at - 300:
        return _token
    r = requests.post(
        f"{API_BASE}/api/Authentication/token/api-key",
        data={"apiKey": API_KEY},
    )
    r.raise_for_status()
    d = r.json()
    _token = d["access_token"]
    _token_expires_at = time.time() + d["expires_in"]
    return _token

def fetch_fleet():
    headers = {"Authorization": f"Bearer {get_token()}"}
    r = requests.post(
        f"{API_BASE}/api/GetAllLastPositionData/{COMPANY_ID}",
        params={"checkVehicleHandlerState": "true"},
        headers=headers,
    )
    r.raise_for_status()
    return r.json()

while True:
    try:
        vehicles = fetch_fleet()
        print(f"\n{'Name':<25} {'Lat':>10} {'Lng':>11} {'km/h':>6} {'Ign'}")
        for v in vehicles:
            print(f"{v['DeviceName']:<25} {v['Lat']:>10.5f} {v['Lng']:>11.5f} "
                  f"{v['Speed']:>6.1f} {'ON' if v['Ignition'] else 'off'}")
    except Exception as e:
        print(f"Error: {e}")
    time.sleep(POLL_INTERVAL)

​
Data freshness

  • UtcTime — timestamp of the last GPS fix recorded by the device. A vehicle parked for hours will have a stale timestamp.
  • ConnectionStrengh — reflects the device’s last-known signal quality. A poor signal may mean the vehicle is in a low-coverage area, not necessarily stationary.
  • If UtcTime is more than a few minutes old and Ignition is true, the device may be temporarily offline.

​
Polling guidance

  • 30–60 seconds is the recommended interval. Most Telemax devices report every 30 seconds.
  • Polling faster than the device reporting rate returns identical data and wastes quota.
  • If a vehicle’s position hasn’t changed between polls, suppress the map update to avoid unnecessary re-renders.

​
Migrating to webhooks

Telemax supports webhook push for position events (see webhooks.yaml). When webhooks are fully deployed, your integration can receive position updates in real time instead of polling. Until then, polling GetAllLastPositionData is the supported approach.