Skip to main content

​
Overview

The DriverAvailabilityApiService manages driver online/offline status, location pinging, and “matchable” status for trip assignment eligibility. Location: src/app/core/services/http/driver-availability-api.service.ts

​
Public Methods

​
updateStatus()

Updates the driver’s availability status (online/offline).
​
payload
UpdateDriverAvailabilityStatus
required
Status update information
Returns: Observable<DriverAvailabilitySnapshot> 
const payload: UpdateDriverAvailabilityStatus = {
  driverId: 'driver_123',
  isAvailable: true,
  location: {
    lat: 20.0217,
    lng: -75.8294
  }
};

this.driverAvailabilityService.updateStatus(payload).subscribe({
  next: (snapshot) => {
    console.log('Status updated:', snapshot.isAvailable);
    console.log('Matchable:', snapshot.isMatchable);
  }
});

​
pingLocation()

Sends periodic location updates while the driver is online.
​
payload
DriverAvailabilityPing
required
Location ping data
Returns: Observable<void> 
// Send location ping every 10 seconds while online
this.locationInterval = setInterval(() => {
  if (this.isOnline) {
    const payload: DriverAvailabilityPing = {
      driverId: this.driverId,
      location: {
        lat: this.currentLat,
        lng: this.currentLng
      },
      accuracy: this.locationAccuracy,
      timestamp: new Date().toISOString()
    };

    this.driverAvailabilityService.pingLocation(payload).subscribe();
  }
}, 10000);

​
getStatus()

Retrieves the current availability status for a driver.
​
driverId
string
required
The driver’s unique identifier
Returns: Observable<DriverAvailabilitySnapshot> 
this.driverAvailabilityService.getStatus(driverId).subscribe({
  next: (snapshot) => {
    this.isOnline = snapshot.isAvailable;
    this.isMatchable = snapshot.isMatchable;
    this.currentVehicle = snapshot.currentVehicleId;
  }
});

​
Response Types

​
DriverAvailabilitySnapshot

interface DriverAvailabilitySnapshot {
  driverId: string;
  isAvailable: boolean;
  isMatchable: boolean;  // Can receive trip assignments
  reason?: AvailabilityReason;
  currentVehicleId?: string;
  lastLocation?: Location;
  lastPingAt?: string;
  onTripId?: string;  // If currently on a trip
}

​
AvailabilityReason

type AvailabilityReason = 
  | 'OFFLINE'          // Driver manually went offline
  | 'ON_TRIP'          // Currently driving a passenger
  | 'BREAK'            // On break
  | 'UNAVAILABLE'      // Temporarily unavailable
  | 'END_OF_SHIFT';    // Finished working

​
Availability States

Available

Driver is online and can receive trip assignments (isAvailable: true, isMatchable: true)

Online but Not Matchable

Driver is online but not eligible for new trips (e.g., needs to select a vehicle)

On Trip

Driver is currently on an active trip (isAvailable: true, isMatchable: false)

Offline

Driver is not available for any trips (isAvailable: false)

​
Location Pinging Strategy

1

Go Online

When driver toggles online status, start location ping interval
2

Ping Every 10 Seconds

Send location updates while online and not on trip
3

Increase Frequency During Trip

Ping every 5 seconds while actively on a trip for real-time tracking
4

Stop When Offline

Clear interval when driver goes offline
Example implementation: 
export class AvailabilityManager {
  private locationInterval?: any;
  private pingFrequency = 10000; // 10 seconds

  goOnline(driverId: string) {
    this.startLocationPinging(driverId);
  }

  goOffline() {
    this.stopLocationPinging();
  }

  onTripStarted() {
    this.pingFrequency = 5000; // Increase to 5 seconds
    this.restartLocationPinging();
  }

  onTripCompleted() {
    this.pingFrequency = 10000; // Return to 10 seconds
    this.restartLocationPinging();
  }

  private startLocationPinging(driverId: string) {
    this.locationInterval = setInterval(() => {
      navigator.geolocation.getCurrentPosition(
        (position) => {
          const payload: DriverAvailabilityPing = {
            driverId,
            location: {
              lat: position.coords.latitude,
              lng: position.coords.longitude
            },
            accuracy: position.coords.accuracy,
            speed: position.coords.speed || 0,
            heading: position.coords.heading || 0,
            timestamp: new Date().toISOString()
          };
          this.driverAvailabilityService.pingLocation(payload).subscribe();
        },
        (error) => {
          console.error('Location error:', error);
        },
        { enableHighAccuracy: true }
      );
    }, this.pingFrequency);
  }

  private stopLocationPinging() {
    if (this.locationInterval) {
      clearInterval(this.locationInterval);
      this.locationInterval = undefined;
    }
  }

  private restartLocationPinging() {
    this.stopLocationPinging();
    this.startLocationPinging(this.driverId);
  }
}

​
Best Practices

Battery optimization: Use lower-frequency pings (15-30 seconds) when stationary to conserve battery.
Location permissions: Always request and verify location permissions before starting ping intervals.
Offline handling: Queue failed location pings and retry when connection is restored.

Build docs developers (and LLMs) love

Get started for freeTalk to us