Vehicles API

The Vehicles API provides endpoints for managing vehicles and tracking devices.

Endpoints Overview

Method	Endpoint	Description
GET	/api/vehicles	List vehicles
POST	/api/vehicle	Create vehicle
PUT	/api/vehicle	Update vehicle
DELETE	/api/vehicle/{guid}	Delete vehicle
GET	/api/vehicle/location/{guid}	Get vehicle location
GET	/api/vehicle/travel-history/{id}	Get travel history
GET	/api/tracking/devices	List tracking devices
POST	/api/tracking/add-device	Add tracking device

List Vehicles

Get all vehicles.

GET /api/vehicles

Response

{
  "data": [
    {
      "guid": "vehicle-uuid",
      "name": "Van 001",
      "licensePlate": "ABC 123",
      "type": "van",
      "status": "available",
      "currentDriver": {
        "guid": "driver-uuid",
        "name": "John Driver"
      },
      "tracker": {
        "guid": "tracker-uuid",
        "lastUpdate": "2024-01-16T14:30:00Z"
      }
    }
  ],
  "success": true
}

Create Vehicle

Add a new vehicle.

POST /api/vehicle

Request Body

{
  "name": "Van 002",
  "licensePlate": "XYZ 789",
  "type": "van",
  "make": "Ford",
  "model": "Transit",
  "year": 2023,
  "capacity": {
    "weight": 1500,
    "volume": 12
  }
}

Response

{
  "data": {
    "guid": "vehicle-uuid",
    "name": "Van 002",
    "licensePlate": "XYZ 789"
  },
  "success": true
}

Update Vehicle

Update vehicle information.

PUT /api/vehicle

Request Body

{
  "guid": "vehicle-uuid",
  "name": "Van 002 (Updated)",
  "status": "maintenance"
}

Response

{
  "data": {
    "guid": "vehicle-uuid",
    "name": "Van 002 (Updated)"
  },
  "success": true
}

Delete Vehicle

Remove a vehicle.

DELETE /api/vehicle/{guid}

Response

{
  "success": true
}

Get Vehicle Location

Get current location and recent positions.

GET /api/vehicle/location/{guid}

Query Parameters

Parameter	Type	Description
from	string	Start date/time
to	string	End date/time

Example Request

GET /api/vehicle/location/vehicle-uuid?from=2024-01-16T08:00:00Z&to=2024-01-16T17:00:00Z

Response

{
  "data": {
    "vehicleId": "vehicle-uuid",
    "currentLocation": {
      "latitude": 40.7128,
      "longitude": -74.0060,
      "timestamp": "2024-01-16T14:30:00Z",
      "speed": 35,
      "heading": 180
    },
    "positions": [
      {
        "latitude": 40.7100,
        "longitude": -74.0050,
        "timestamp": "2024-01-16T14:00:00Z"
      },
      {
        "latitude": 40.7115,
        "longitude": -74.0055,
        "timestamp": "2024-01-16T14:15:00Z"
      },
      {
        "latitude": 40.7128,
        "longitude": -74.0060,
        "timestamp": "2024-01-16T14:30:00Z"
      }
    ]
  },
  "success": true
}

Get Travel History

Get historical travel data for a vehicle.

GET /api/vehicle/travel-history/{id}

Response

{
  "data": [
    {
      "date": "2024-01-16",
      "distanceTraveled": 125.5,
      "travelTime": "6h 30m",
      "startLocation": "Warehouse A",
      "endLocation": "Warehouse A",
      "stops": 15,
      "fuelUsed": null
    },
    {
      "date": "2024-01-15",
      "distanceTraveled": 98.2,
      "travelTime": "5h 15m",
      "startLocation": "Warehouse A",
      "endLocation": "Warehouse A",
      "stops": 12,
      "fuelUsed": null
    }
  ],
  "success": true
}

List Tracking Devices

Get all tracking devices.

GET /api/tracking/devices

Response

{
  "data": [
    {
      "guid": "device-uuid",
      "deviceId": "DEV001",
      "type": "gps_tracker",
      "status": "active",
      "assignedVehicle": {
        "guid": "vehicle-uuid",
        "name": "Van 001"
      },
      "lastSeen": "2024-01-16T14:30:00Z",
      "batteryLevel": 85
    }
  ],
  "success": true
}

Add Tracking Device

Register a new tracking device.

POST /api/tracking/add-device

Request Body

{
  "deviceId": "DEV002",
  "type": "gps_tracker",
  "vehicleId": "vehicle-uuid"
}

Response

{
  "data": {
    "guid": "device-uuid",
    "deviceId": "DEV002",
    "status": "active"
  },
  "success": true
}

Vehicle Statuses

Status	Description
available	Ready for use
in_use	Currently on a dispatch
maintenance	Being serviced
inactive	Not operational

Device Statuses

Status	Description
active	Transmitting normally
offline	Not transmitting
low_battery	Battery needs charging
error	Device error

Error Responses

404 Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Vehicle not found"
  }
}

400 Bad Request

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid device ID"
  }
}