Book a Ride

Request a ride, track its progress, and submit feedback using the RideShare API.

All booking and history endpoints require an Authorization header with a valid bearer token.

Authorization: Bearer <your_token>

1. Estimate the fare

   Before booking, call the estimate endpoint to preview the fare for your trip. Pass distanceKm (required) along with the optional coordinates and preferences.

   GET /rides/estimate?distanceKm=10&rideType=STANDARD&pickupLat=12.9716&pickupLon=77.5946&dropLat=12.9352&dropLon=77.6245&routePreference=FASTEST
   

   Parameter	Required	Description
   distanceKm	Yes	Trip distance in kilometres
   rideType	No	STANDARD, PREMIUM, etc.
   pickupLat	No	Pickup latitude
   pickupLon	No	Pickup longitude
   dropLat	No	Drop-off latitude
   dropLon	No	Drop-off longitude
   routePreference	No	FASTEST, SHORTEST, etc.

   Example response

   {
     "estimatedFare": 142.50,
     "rideType": "STANDARD",
     "distanceKm": 10,
     "routePreference": "FASTEST",
     "currency": "INR"
   }
   
2. Book the ride

   Submit a POST /rides/book request with your pickup and drop-off details. The API assigns your authenticated user as the rider automatically.

   POST /rides/book
   Authorization: Bearer <your_token>
   Content-Type: application/json
   

   {
     "pickupLocation": "MG Road, Bengaluru",
     "dropLocation": "Koramangala, Bengaluru",
     "pickupLat": 12.9716,
     "pickupLon": 77.5946,
     "dropLat": 12.9352,
     "dropLon": 77.6245,
     "paymentMode": "upi"
   }
   

   Field	Type	Description
   pickupLocation	string	Human-readable pickup address
   dropLocation	string	Human-readable drop-off address
   pickupLat	number	Pickup latitude
   pickupLon	number	Pickup longitude
   dropLat	number	Drop-off latitude
   dropLon	number	Drop-off longitude
   paymentMode	string	Payment method (e.g. upi, cash, card)

   Example response

   {
     "id": 1042,
     "pickupLocation": "MG Road, Bengaluru",
     "dropLocation": "Koramangala, Bengaluru",
     "pickupLat": 12.9716,
     "pickupLon": 77.5946,
     "dropLat": 12.9352,
     "dropLon": 77.6245,
     "fare": 142.50,
     "paymentMode": "upi",
     "status": "REQUESTED",
     "riderId": 7,
     "createdAt": "2026-04-02T10:15:00Z"
   }
   

   Save the returned id — you need it to track the ride and submit feedback.

3. Track ride status

   Poll GET /rides/status/{rideId} to check the current state of your ride.

   GET /rides/status/1042
   

   Example response

   {
     "id": 1042,
     "status": "ACCEPTED",
     "driverId": 55,
     "driverLat": 12.9730,
     "driverLon": 77.5960,
     "driverLocationUpdatedAt": "2026-04-02T10:17:45Z",
     "pickupLocation": "MG Road, Bengaluru",
     "dropLocation": "Koramangala, Bengaluru",
     "fare": 142.50,
     "paymentMode": "upi",
     "startOtp": "4521",
     "createdAt": "2026-04-02T10:15:00Z",
     "acceptedAt": "2026-04-02T10:17:00Z"
   }
   

   The status field progresses through the following values:

   Status	Meaning
   REQUESTED	Ride booked, waiting for a driver
   ACCEPTED	A driver has accepted your ride
   PICKED	Driver has started the trip
   COMPLETED	Ride finished
   CANCELLED	Ride was cancelled

   When the status is ACCEPTED, use driverLat and driverLon to show the driver’s live position on a map.

4. Submit feedback

   After the ride reaches COMPLETED status, submit a rating and optional comment.

   POST /rides/feedback/1042
   Authorization: Bearer <your_token>
   Content-Type: application/json
   

   {
     "rating": 5,
     "comment": "Great ride, very smooth!"
   }
   

   Field	Type	Description
   rating	integer	Score from 1 to 5
   comment	string	Optional free-text feedback

   Example response

   {
     "id": 1042,
     "status": "COMPLETED",
     "riderRating": 5,
     "riderFeedback": "Great ride, very smooth!"
   }
   

View ride history

Retrieve a list of all rides associated with your account.

GET /rides/history
Authorization: Bearer <your_token>

Example response

[
  {
    "id": 1042,
    "pickupLocation": "MG Road, Bengaluru",
    "dropLocation": "Koramangala, Bengaluru",
    "fare": 142.50,
    "status": "COMPLETED",
    "riderRating": 5,
    "createdAt": "2026-04-02T10:15:00Z"
  },
  {
    "id": 1038,
    "pickupLocation": "Indiranagar, Bengaluru",
    "dropLocation": "Whitefield, Bengaluru",
    "fare": 310.00,
    "status": "COMPLETED",
    "riderRating": 4,
    "createdAt": "2026-04-01T08:45:00Z"
  }
]

Cancel a ride

Cancel a ride that has not yet been completed by calling POST /rides/cancel/{rideId}. Provide an optional reason in the request body.

POST /rides/cancel/1042
Authorization: Bearer <your_token>
Content-Type: application/json

{
  "reason": "Plans changed"
}

Cancelling a ride after a driver has been assigned may incur a cancellationFee. Check the returned cancellationFee field in the response.