GPS Tracking

Fleet's GPS module provides real-time vehicle location, trip history, geofence alerting, and event detection. GPS data is sent from hardware tracking devices installed in your vehicles to the Fleet API.

How GPS Tracking Works

1. A GPS device is installed in a vehicle and configured to send position data to the Fleet API
2. The device sends position updates to POST /api/gps using your Fleet API credentials
3. Fleet stores each position with timestamp, speed, heading, and event type
4. Positions are retained for 90 days, then automatically purged
5. The GPS map page shows the latest position for each vehicle across your fleet
6. Clicking a vehicle shows its position history

GPS Position Fields

Each position record includes:

Field	Description
Vehicle ID	Links the position to a vehicle record
Device ID	Hardware identifier of the GPS device (optional)
Latitude / Longitude	WGS-84 decimal degrees
Speed	Speed in mph or km/h as reported by the device
Heading	Direction in degrees (0–360, where 0/360 = North)
Altitude	Altitude in meters (optional)
Accuracy	Position accuracy radius in meters (optional)
Event Type	What triggered this position report (see below)
Recorded At	Timestamp from the GPS device (not server receipt time)

GPS Event Types

Fleet distinguishes the following event types:

Event Type	When It's Sent
periodic	Regular interval ping (e.g., every 30–60 seconds)
ignition_on	Engine started
ignition_off	Engine turned off
geofence_enter	Vehicle entered a defined geofence area
geofence_exit	Vehicle exited a defined geofence area
speeding	Speed exceeded the configured threshold
idle	Vehicle has been idling for defined duration
harsh_braking	Sudden hard brake detected by accelerometer
harsh_acceleration	Rapid acceleration detected by accelerometer

ℹ️Event types like speeding, idle, harsh_braking, and harsh_acceleration are detected and tagged by the GPS hardware device — Fleet stores whatever the device reports. Configure thresholds on your GPS device, not in Fleet.

Setting Up a GPS Device

Step 1: Obtain the Device ID

Your GPS hardware provider will give you a unique device identifier. This is typically printed on the device or available in your GPS hardware portal.

Step 2: Link the Device to a Vehicle

1. Open the vehicle you want to track
2. Click Edit
3. Enter the GPS Device ID in the GPS Device ID field
4. Click Save

Step 3: Configure the Device

Program your GPS device to send position data to:

POST https://api.theonefleet.app/api/gps

Authentication: Use a tenant API key (created in Admin → API Keys) passed as a header:

Authorization: Bearer YOUR_API_KEY

Step 4: Test the Connection

1. Power on the device in the vehicle
2. Navigate to GPS Tracking in the Fleet sidebar
3. Confirm the vehicle appears on the map with a recent position timestamp

The Fleet Map

Navigate to GPS Tracking in the left sidebar to see the fleet map:

• Each active vehicle with GPS data appears as a pin on the map
• The map shows the latest position for each vehicle (not live streaming)
• Click a vehicle pin to see its details: speed, heading, last update time, assigned driver
• The map refreshes based on your browser session (manual refresh or polling)

Viewing Trip History

To replay a vehicle's route for a specific time period:

1. Open the vehicle detail page
2. Click the GPS tab
3. Use the date/time filter to select a time range
4. The list shows up to 200 positions ordered by time
5. Speed and heading are shown for each position

💡GPS history is stored for 90 days. For IRS mileage reporting or long-term trip records, export data regularly or use the Reports module to extract historical summaries before positions are purged.

Geofences

A geofence is a circular boundary on the map. When a vehicle exits a geofence, Fleet emits a gps.geofence_breach event and creates a geofence_breach alert.

Creating a Geofence

Geofences are created via the Fleet API (no UI builder available in this release):

POST /api/gps
{
  "type": "geofence",
  "name": "Main Office",
  "center_lat": 40.7128,
  "center_lng": -74.0060,
  "radius_meters": 500,
  "alert_on_exit": true,
  "alert_on_enter": false,
  "vehicle_ids": ["vehicle-id-1", "vehicle-id-2"]
}

Field	Description
name	Display name for the geofence
center_lat / center_lng	Center point of the circle
radius_meters	Radius of the geofence in meters
alert_on_exit	If true, generates an alert when a vehicle leaves this zone
alert_on_enter	If true, generates an alert when a vehicle enters this zone
vehicle_ids	Optional list of specific vehicle IDs to monitor. If empty, applies to all vehicles

Geofence Breach Detection

Fleet uses the Haversine formula to calculate the great-circle distance between the vehicle's current position and each geofence center. If the distance exceeds the geofence radius, a breach is recorded.

Geofence checking is triggered whenever GPS devices send position updates that include a check_geofences action.

GPS Data Retention

GPS positions are automatically deleted after 90 days using Cosmos DB TTL. This is enforced at the database level — there is no manual purge needed.

If you need longer-term GPS records:

• Export position data via the API before the 90-day window closes
• Use the trip history on the vehicle detail page for recent history

Batch Position Uploads

GPS devices can send multiple positions in a single API call:

POST /api/gps
[
  { "vehicle_id": "...", "latitude": 40.71, "longitude": -74.00, "event_type": "periodic", ... },
  { "vehicle_id": "...", "latitude": 40.72, "longitude": -74.01, "event_type": "ignition_off", ... }
]

The API accepts either a single position object or an array. Batching reduces API call overhead for devices that buffer positions.

Troubleshooting GPS

Vehicle not appearing on map

• Verify the GPS Device ID on the vehicle record matches what the hardware device is sending
• Confirm the device is successfully authenticating (check for 401 errors in device logs)
• GPS positions are retained for 90 days — if the vehicle hasn't moved recently, no current position will show

Position data stale

• Check your GPS device's transmission interval setting
• Verify the device has cellular signal in the vehicle's location
• Review the vehicle's GPS tab for the timestamp of the most recent position

Geofence alerts not firing

• Confirm alert_on_exit: true is set on the geofence
• Ensure the geofence vehicle_ids array includes the relevant vehicle (or is empty to apply to all)
• Verify the GPS device is sending positions frequently enough to detect the exit event