# FleetPass Fleet API

> Real-time GPS, fuel, odometer and ignition data from any connected commercial vehicle fleet — served through a single, consistent REST interface. Built in South Africa, hosted in AWS Cape Town (af-south-1).

## What this API does

FleetPass Fleet API aggregates telematics data from commercial vehicle manufacturer connect platforms (starting with Volvo Trucks) and re-serves it through a clean, manufacturer-agnostic REST API. Fleet operators supply their own manufacturer credentials; FleetPass polls on their behalf and exposes the data under a consistent URL pattern.

## Base URL

https://api.fleetpass.co.za

## Authentication

All endpoints (except / and /health) require an API key. Pass it as:
- HTTP header: Authorization: Bearer YOUR_API_KEY
- Query parameter: ?key=YOUR_API_KEY

API keys are issued per tenant. Contact api@fleetpass.co.za to request access.

## URL Structure

GET /volvo/{vehicle}/{service}

{vehicle} = registration number (e.g. JFW841FS) or chassis/VIN number
{service}  = gps | fuel | odo | status | history

## Endpoints

### GET /{manufacturer}/{vehicle}/status
Returns all data in one call: GPS position, fuel level, odometer, engine hours, ignition state.

### GET /{manufacturer}/{vehicle}/gps
Current GPS position. Returns: lat, lon, speed_kmh, heading, as_of timestamp.
Data freshness: updated every 60 seconds while vehicle is moving.

### GET /{manufacturer}/{vehicle}/fuel
Current fuel data. Returns: fuel_pct (0-100), fuel_litres, tank_litres.
Data freshness: updated on ignition ON/OFF events (not every 60s).

### GET /{manufacturer}/{vehicle}/odo
Lifetime odometer. Returns: odometer_km, engine_hours.
Data freshness: updated on ignition events.

### GET /{manufacturer}/{vehicle}/history
GPS ping history. Optional query param: ?hours=24 (default 24, max 720 = 30 days).
Returns array of pings with: trigger, at, lat, lon, speed_kmh, heading, fuel_pct, odo_km.

### GET /health
No authentication required. Returns service status and current UTC time.

## Supported Manufacturers

- volvo — Volvo Trucks (Volvo Connect / rFMS API). Live.
- mercedes — Mercedes-Benz Trucks. Coming soon.
- man — MAN Truck & Bus. Coming soon.
- daf — DAF Trucks. Coming soon.

## Example Response — /volvo/JFW841FS/status

{
  "ok": true,
  "vehicle": "JFW841FS",
  "manufacturer": "volvo",
  "gps": {"lat": -29.8587, "lon": 31.0218, "speed_kmh": 74, "heading": 174},
  "fuel": {"pct": 62, "litres": 555, "tank_litres": 895},
  "odometer_km": 197267,
  "engine_hours": 3893.2,
  "ignition": "On",
  "as_of": "2026-10-10T15:09:43Z",
  "received_at": "2026-10-10T15:09:44Z"
}

## Error Codes

- 401 Unauthorized — missing or invalid API key
- 403 Forbidden — vehicle not in your allowed list, or account suspended
- 404 Not Found — vehicle not found for your account
- 429 Too Many Requests — rate limit exceeded (limit shown in response)

## Data Freshness Notes

GPS positions update every 60 seconds while moving, every 10 minutes while parked.
Fuel level and odometer update on ignition ON/OFF events only (not on 60s pings).
History retained for 30 days.

## Interactive Documentation

Full OpenAPI/Swagger docs: https://api.fleetpass.co.za/docs
ReDoc format: https://api.fleetpass.co.za/redoc

## Contact

Request API access: api@fleetpass.co.za
FleetPass (Pty) Ltd — https://fleetpass.co.za