> ## Documentation Index
> Fetch the complete documentation index at: https://rideshare.docs.sumit-dhondikar.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Book a Ride

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

<Note>
  All booking and history endpoints require an `Authorization` header with a valid bearer token.

  ```bash theme={null}
  Authorization: Bearer <your_token>
  ```
</Note>

<Steps>
  <Step title="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.

    ```bash theme={null}
    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**

    ```json theme={null}
    {
      "estimatedFare": 142.50,
      "rideType": "STANDARD",
      "distanceKm": 10,
      "routePreference": "FASTEST",
      "currency": "INR"
    }
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    POST /rides/book
    Authorization: Bearer <your_token>
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "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**

    ```json theme={null}
    {
      "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.
  </Step>

  <Step title="Track ride status">
    Poll `GET /rides/status/{rideId}` to check the current state of your ride.

    ```bash theme={null}
    GET /rides/status/1042
    ```

    **Example response**

    ```json theme={null}
    {
      "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                |

    <Tip>
      When the status is `ACCEPTED`, use `driverLat` and `driverLon` to show the driver's live position on a map.
    </Tip>
  </Step>

  <Step title="Submit feedback">
    After the ride reaches `COMPLETED` status, submit a rating and optional comment.

    ```bash theme={null}
    POST /rides/feedback/1042
    Authorization: Bearer <your_token>
    Content-Type: application/json
    ```

    ```json theme={null}
    {
      "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**

    ```json theme={null}
    {
      "id": 1042,
      "status": "COMPLETED",
      "riderRating": 5,
      "riderFeedback": "Great ride, very smooth!"
    }
    ```
  </Step>
</Steps>

## View ride history

Retrieve a list of all rides associated with your account.

```bash theme={null}
GET /rides/history
Authorization: Bearer <your_token>
```

**Example response**

```json theme={null}
[
  {
    "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.

```bash theme={null}
POST /rides/cancel/1042
Authorization: Bearer <your_token>
Content-Type: application/json
```

```json theme={null}
{
  "reason": "Plans changed"
}
```

<Warning>
  Cancelling a ride after a driver has been assigned may incur a `cancellationFee`. Check the returned `cancellationFee` field in the response.
</Warning>