Rides API

Service Structure

// Location: src/api/services/rideService.ts
export const rideService = {
  // Ride Creation
  addRide: (rideData) => apiCall(AppConstants.addRide, rideData),
  
  // Ride Retrieval
  getPassengerRides: () => apiCall(AppConstants.getPassengerRides),
  getDriverRides: () => apiCall(AppConstants.getDriverRides),
  
  // Ride Search & Booking
  searchRides: (searchParams) => apiCall(AppConstants.searchRides, searchParams),
  bookRide: (bookingData) => apiCall(AppConstants.bookRide, bookingData),
  
  // Ride Management
  updateTripStatus: (statusData) => apiCall(AppConstants.updateTripStatus, statusData),
  completeRide: (rideId) => apiCall(AppConstants.completeRide, { ride_id: rideId }),
  
  // Ride Details & Status
  getRideDetails: (rideId) => apiCall(AppConstants.getRideDetails, { ride_id: rideId }),
  getBookingStatus: (bookingId) => apiCall(AppConstants.getBookingStatus, { booking_id: bookingId }),
  
  // Ride Alerts
  createRideAlert: (alertData) => apiCall(AppConstants.createRideAlert, alertData)
};

Request Body

{
  "pickup_location": "123 Main St, New York, NY",
  "pickup_latitude": 40.7128,
  "pickup_longitude": -74.0060,
  "drop_location": "456 Broadway, New York, NY", 
  "drop_latitude": 40.7589,
  "drop_longitude": -73.9851,
  "depart_date": "2024-01-15",
  "pickup_time": "08:00",
  "arrival_time": "09:30",
  "available_seats": 3,
  "price_per_person": 25.00,
  "currency": "USD",
  "vehicle_id": 123,
  "notes": "Comfortable sedan, non-smoking trip",
  "recurring": false,
  "recurring_days": [], // ["monday", "wednesday", "friday"] for recurring rides
  "route_distance": 15.5, // kilometers
  "estimated_duration": 90 // minutes
}

Success Response

{
  "status_code": "1",
  "status_message": "Ride created successfully",
  "data": {
    "ride_id": 789,
    "pickup_location": "123 Main St, New York, NY",
    "drop_location": "456 Broadway, New York, NY",
    "depart_date": "2024-01-15",
    "pickup_time": "08:00",
    "available_seats": 3,
    "price_per_person": 25.00,
    "status": "active",
    "created_at": "2024-01-01T12:00:00Z",
    "booking_url": "https://wi-carpool.com/ride/789"
  }
}

// In PostRide component
const handleSubmit = async (rideData) => {
  try {
    const response = await rideService.addRide({
      pickup_location: rideData.from,
      drop_location: rideData.to,
      depart_date: rideData.date,
      pickup_time: rideData.time,
      available_seats: parseInt(rideData.seats),
      price_per_person: parseFloat(rideData.price),
      vehicle_id: rideData.vehicleId,
      notes: rideData.notes
    });
    
    if (response.status_code === "1") {
      toast({
        title: "Ride Created",
        description: "Your ride has been posted successfully!"
      });
      navigate('/driver/dashboard');
    }
  } catch (error) {
    toast({
      title: "Error",
      description: "Failed to create ride. Please try again.",
      variant: "destructive"
    });
  }
};

Request Body

{
  "pickup_location": "New York, NY",
  "drop_location": "Philadelphia, PA",
  "depart_date": "2024-01-15",
  "passenger_count": 2,
  "max_price": 50.00,
  "departure_time_min": "06:00",
  "departure_time_max": "10:00",
  "radius_km": 10, // Search radius from pickup/drop locations
  "sort_by": "price", // "price", "time", "rating", "distance"
  "sort_order": "asc"
}

Success Response

{
  "status_code": "1",
  "status_message": "Rides found",
  "data": {
    "rides": [
      {
        "ride_id": 789,
        "driver_id": 456,
        "driver_name": "John Driver",
        "driver_rating": 4.8,
        "driver_avatar": "https://example.com/avatar.jpg",
        "pickup_location": "123 Main St, New York, NY",
        "drop_location": "456 Market St, Philadelphia, PA",
        "depart_date": "2024-01-15",
        "pickup_time": "08:00",
        "arrival_time": "11:00",
        "available_seats": 2,
        "total_seats": 4,
        "price_per_person": 35.00,
        "currency": "USD",
        "vehicle": {
          "make": "Toyota",
          "model": "Camry",
          "year": 2022,
          "color": "Silver",
          "license_plate": "ABC123"
        },
        "distance_from_pickup": 0.5, // km from search pickup point
        "distance_to_drop": 0.3, // km to search drop point
        "instant_booking": true,
        "cancellation_policy": "flexible"
      }
    ],
    "total_results": 15,
    "page": 1,
    "per_page": 10
  }
}

Query Parameters

GET /available_rides?page=1&limit=20&sort=departure_time

Frontend Implementation

// In useRideSearch hook
const handleSearch = async () => {
  try {
    const response = await availableRidesService.getAvailableRides();
    
    if (response.status_code === "1" && Array.isArray(response.rides)) {
      let rides = response.rides;
      
      // Filter out rides posted by current user
      if (user?.id) {
        rides = rides.filter(ride => 
          ride.driver_id.toString() !== user.id.toString()
        );
      }
      
      // Apply location filters
      if (from) {
        rides = rides.filter(ride => 
          ride.pickup_location.toLowerCase().includes(from.toLowerCase())
        );
      }
      
      if (to) {
        rides = rides.filter(ride => 
          ride.drop_location.toLowerCase().includes(to.toLowerCase())
        );
      }
      
      setSearchResults(rides);
    }
  } catch (error) {
    console.error("Search error:", error);
    setSearchResults([]);
  }
};

Request Body

{
  "ride_id": 789,
  "passenger_id": 123,
  "seats_requested": 2,
  "pickup_location": "123 Main St, New York, NY", // Can be different from ride's main pickup
  "drop_location": "456 Market St, Philadelphia, PA", // Can be different from ride's main drop
  "special_requests": "Please pick up from front entrance",
  "contact_number": "+1234567890",
  "payment_method": "wallet", // "wallet", "card", "cash"
  "payment_amount": 70.00,
  "instant_booking": true
}

Success Response

{
  "status_code": "1",
  "status_message": "Booking successful",
  "data": {
    "booking_id": 456,
    "ride_id": 789,
    "booking_reference": "WCP-789-456",
    "status": "confirmed", // "pending", "confirmed", "cancelled"
    "seats_booked": 2,
    "total_amount": 70.00,
    "payment_status": "completed",
    "pickup_time": "08:00",
    "pickup_location": "123 Main St, New York, NY",
    "drop_location": "456 Market St, Philadelphia, PA",
    "driver_contact": {
      "name": "John Driver",
      "phone": "+1987654321",
      "avatar": "https://example.com/avatar.jpg"
    },
    "vehicle_details": {
      "make": "Toyota",
      "model": "Camry",
      "color": "Silver",
      "license_plate": "ABC123"
    },
    "booking_time": "2024-01-01T10:00:00Z",
    "cancellation_deadline": "2024-01-15T06:00:00Z"
  }
}

Request Body

{
  "trip_id": 789,
  "status": "in_progress", // "pending", "started", "in_progress", "completed", "cancelled"
  "latitude": 40.7128,
  "longitude": -74.0060,
  "timestamp": "2024-01-15T08:30:00Z",
  "notes": "Running 5 minutes behind schedule"
}

Status Values

// Available status values
"pending"      // Ride created, waiting for bookings
"confirmed"    // Bookings confirmed, ready to start
"started"      // Driver has departed for pickup
"in_progress"  // Trip is ongoing
"completed"    // Trip finished successfully
"cancelled"    // Trip cancelled
"delayed"      // Trip is delayed
"no_show"      // Passenger didn't show up

Request Body

{
  "ride_id": 789,
  "completion_time": "2024-01-15T11:00:00Z",
  "final_location": "456 Market St, Philadelphia, PA",
  "actual_distance": 16.2, // kilometers
  "passenger_ratings": [
    {
      "passenger_id": 123,
      "rating": 5,
      "feedback": "Great passenger, very punctual"
    }
  ],
  "trip_issues": [], // Optional array of any issues encountered
  "additional_charges": 0.00 // Any extra charges (tolls, etc.)
}

Success Response

{
  "status_code": "1",
  "status_message": "Ride completed successfully",
  "data": {
    "ride_id": 789,
    "completion_time": "2024-01-15T11:00:00Z",
    "total_earnings": 70.00,
    "platform_fee": 7.00,
    "net_earnings": 63.00,
    "payment_status": "processed",
    "invoice_id": "INV-789-456",
    "next_payout_date": "2024-01-22T00:00:00Z"
  }
}

Query Parameters

GET /get_ride_as_passenger?status=all&page=1&limit=20&date_from=2024-01-01&date_to=2024-01-31

Success Response

{
  "status_code": "1",
  "status_message": "Passenger rides retrieved",
  "data": {
    "rides": [
      {
        "booking_id": 456,
        "ride_id": 789,
        "booking_reference": "WCP-789-456",
        "status": "completed",
        "pickup_location": "123 Main St, New York, NY",
        "drop_location": "456 Market St, Philadelphia, PA",
        "depart_date": "2024-01-15",
        "pickup_time": "08:00",
        "arrival_time": "11:00",
        "seats_booked": 2,
        "amount_paid": 70.00,
        "currency": "USD",
        "driver": {
          "id": 456,
          "name": "John Driver",
          "rating": 4.8,
          "avatar": "https://example.com/avatar.jpg"
        },
        "vehicle": {
          "make": "Toyota",
          "model": "Camry",
          "color": "Silver",
          "license_plate": "ABC123"
        },
        "can_rate": true,
        "can_cancel": false,
        "can_message": true
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_rides": 48,
      "per_page": 10
    },
    "statistics": {
      "total_rides": 48,
      "completed_rides": 42,
      "cancelled_rides": 6,
      "total_spent": 1250.00
    }
  }
}

Success Response

{
  "status_code": "1",
  "status_message": "Driver rides retrieved",
  "data": {
    "rides": [
      {
        "ride_id": 789,
        "status": "completed",
        "pickup_location": "123 Main St, New York, NY",
        "drop_location": "456 Market St, Philadelphia, PA",
        "depart_date": "2024-01-15",
        "pickup_time": "08:00",
        "total_seats": 4,
        "booked_seats": 3,
        "available_seats": 1,
        "price_per_person": 35.00,
        "total_earnings": 105.00,
        "platform_fee": 10.50,
        "net_earnings": 94.50,
        "passengers": [
          {
            "passenger_id": 123,
            "name": "Jane Passenger",
            "seats": 2,
            "rating": 4.9,
            "status": "completed"
          },
          {
            "passenger_id": 124,
            "name": "Bob Traveler", 
            "seats": 1,
            "rating": 4.7,
            "status": "completed"
          }
        ],
        "can_edit": false,
        "can_cancel": false
      }
    ],
    "statistics": {
      "total_rides": 25,
      "completed_rides": 23,
      "cancelled_rides": 2,
      "total_earnings": 2150.00,
      "average_rating": 4.8
    }
  }
}

Request Body

{
  "pickup_location": "New York, NY",
  "drop_location": "Philadelphia, PA",
  "depart_date": "2024-01-20",
  "flexible_dates": true,
  "date_range_days": 3, // ±3 days from depart_date
  "max_price": 40.00,
  "min_seats": 2,
  "preferred_departure_time": "08:00",
  "time_flexibility_hours": 2, // ±2 hours from preferred time
  "notification_methods": ["email", "push", "sms"],
  "auto_book": false, // Automatically book if matching ride found
  "alert_duration_days": 30 // How long to keep the alert active
}

Success Response

{
  "status_code": "1",
  "status_message": "Ride alert created successfully",
  "data": {
    "alert_id": 123,
    "pickup_location": "New York, NY",
    "drop_location": "Philadelphia, PA",
    "depart_date": "2024-01-20",
    "max_price": 40.00,
    "status": "active",
    "created_at": "2024-01-01T12:00:00Z",
    "expires_at": "2024-01-31T12:00:00Z",
    "notification_settings": {
      "email": true,
      "push": true,
      "sms": false
    }
  }
}

Request Body

{
  "ride_id": 789
}

Success Response

{
  "status_code": "1",
  "status_message": "Ride details retrieved",
  "data": {
    "ride_id": 789,
    "driver": {
      "id": 456,
      "first_name": "John",
      "last_name": "Driver",
      "profile_picture": "https://example.com/avatar.jpg",
      "rating": 4.8,
      "total_trips": 150,
      "member_since": "2022-03-15",
      "verification_status": "verified",
      "languages": ["English", "Spanish"]
    },
    "route": {
      "pickup_location": "123 Main St, New York, NY",
      "pickup_latitude": 40.7128,
      "pickup_longitude": -74.0060,
      "drop_location": "456 Market St, Philadelphia, PA",
      "drop_latitude": 39.9526,
      "drop_longitude": -75.1652,
      "distance": 95.2, // miles
      "estimated_duration": 120, // minutes
      "waypoints": [
        {
          "location": "Newark, NJ",
          "latitude": 40.7357,
          "longitude": -74.1724,
          "stop_duration": 10 // minutes
        }
      ]
    },
    "schedule": {
      "depart_date": "2024-01-15",
      "pickup_time": "08:00",
      "estimated_arrival": "11:00",
      "timezone": "America/New_York"
    },
    "pricing": {
      "price_per_person": 35.00,
      "currency": "USD",
      "includes": ["Gas", "Tolls"],
      "payment_methods": ["wallet", "card"],
      "cancellation_policy": "flexible"
    },
    "capacity": {
      "total_seats": 4,
      "available_seats": 2,
      "booked_seats": 2,
      "luggage_space": "medium"
    },
    "vehicle": {
      "make": "Toyota",
      "model": "Camry",
      "year": 2022,
      "color": "Silver",
      "license_plate": "ABC123",
      "features": ["AC", "Music", "Phone Charger"],
      "photos": [
        "https://example.com/car1.jpg",
        "https://example.com/car2.jpg"
      ]
    },
    "policies": {
      "smoking": false,
      "pets": false,
      "music": true,
      "max_luggage": "2 bags per person",
      "special_notes": "Please be ready at pickup time"
    },
    "current_passengers": [
      {
        "passenger_id": 123,
        "name": "Jane P.",
        "rating": 4.9,
        "seats": 2
      }
    ],
    "booking_options": {
      "instant_booking": true,
      "requires_approval": false,
      "advance_booking_hours": 2
    }
  }
}

Request Body

{
  "booking_id": 456
}

Success Response

{
  "status_code": "1",
  "status_message": "Booking status retrieved",
  "data": {
    "booking_id": 456,
    "booking_reference": "WCP-789-456",
    "status": "confirmed",
    "ride_status": "in_progress",
    "estimated_pickup": "2024-01-15T08:00:00Z",
    "estimated_arrival": "2024-01-15T11:00:00Z",
    "driver_location": {
      "latitude": 40.7300,
      "longitude": -74.0000,
      "last_updated": "2024-01-15T08:15:00Z",
      "eta_to_pickup": 15 // minutes
    },
    "tracking_enabled": true,
    "can_cancel": true,
    "cancellation_deadline": "2024-01-15T06:00:00Z",
    "contact_info": {
      "driver_phone": "+1987654321",
      "emergency_contact": "+1800123456"
    }
  }
}

Location Update Payload

// Pusher channel: private-ride-{ride_id}
// Event: location-update
{
  "driver_id": 456,
  "ride_id": 789,
  "latitude": 40.7300,
  "longitude": -74.0000,
  "heading": 90, // degrees
  "speed": 35, // mph
  "timestamp": "2024-01-15T08:30:00Z",
  "eta_to_pickup": 10, // minutes for next pickup
  "distance_to_destination": 85.5 // miles remaining
}

Status Update Events

// Various status update events
{
  "event": "ride_started",
  "ride_id": 789,
  "timestamp": "2024-01-15T08:00:00Z",
  "message": "Driver has departed for pickup"
}

{
  "event": "passenger_picked_up",
  "ride_id": 789,
  "passenger_id": 123,
  "timestamp": "2024-01-15T08:15:00Z",
  "remaining_pickups": 1
}

{
  "event": "trip_completed",
  "ride_id": 789,
  "timestamp": "2024-01-15T11:00:00Z",
  "final_location": "456 Market St, Philadelphia, PA"
}

Request Body (Passenger Rating Driver)

{
  "ride_id": 789,
  "driver_id": 456,
  "rating": 5,
  "categories": {
    "punctuality": 5,
    "cleanliness": 4,
    "driving": 5,
    "communication": 5,
    "vehicle_condition": 4
  },
  "feedback": "Great driver, very punctual and friendly!",
  "recommend": true,
  "trip_issues": [], // Optional array of any issues
  "anonymous": false
}

Request Body (Driver Rating Passenger)

{
  "ride_id": 789,
  "passenger_id": 123,
  "rating": 5,
  "categories": {
    "punctuality": 5,
    "respectfulness": 5,
    "cleanliness": 4,
    "communication": 5
  },
  "feedback": "Excellent passenger, on time and respectful",
  "recommend": true
}

Success Response

{
  "status_code": "1",
  "status_message": "Ratings retrieved successfully",
  "data": {
    "ride_id": 789,
    "driver_rating": {
      "average_rating": 4.8,
      "total_ratings": 2,
      "categories": {
        "punctuality": 4.5,
        "cleanliness": 4.0,
        "driving": 5.0,
        "communication": 5.0,
        "vehicle_condition": 4.5
      },
      "recent_feedback": [
        {
          "rating": 5,
          "feedback": "Great driver, very punctual and friendly!",
          "date": "2024-01-15",
          "anonymous": false
        }
      ]
    },
    "passenger_ratings": [
      {
        "passenger_id": 123,
        "rating": 5,
        "feedback": "Excellent passenger, on time and respectful",
        "date": "2024-01-15"
      }
    ]
  }
}

Standard Error Response

{
  "status_code": "0",
  "status_message": "Insufficient seats available",
  "data": {
    "error_code": "RIDE_003",
    "error_details": "Only 1 seat available, but 2 seats requested",
    "available_seats": 1,
    "requested_seats": 2,
    "suggestions": [
      "Reduce seat count to 1",
      "Search for alternative rides"
    ]
  }
}