> ## 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 Ride

> Create a new ride request for the authenticated rider.

Submit a booking request with pickup and drop-off details. The server automatically associates the ride with your account and sets the initial status to `REQUESTED`.

**Authentication required** — include `Authorization: Bearer <token>` in the request header.

## Request

**`POST /rides/book`**

<ParamField body="pickupLocation" type="string">
  Human-readable name or address of the pickup location.
</ParamField>

<ParamField body="dropLocation" type="string">
  Human-readable name or address of the drop-off location.
</ParamField>

<ParamField body="pickupLat" type="number">
  Latitude of the pickup point.
</ParamField>

<ParamField body="pickupLon" type="number">
  Longitude of the pickup point.
</ParamField>

<ParamField body="dropLat" type="number">
  Latitude of the drop-off point.
</ParamField>

<ParamField body="dropLon" type="number">
  Longitude of the drop-off point.
</ParamField>

<ParamField body="pickupLandmark" type="string">
  Landmark or additional detail for the pickup location (up to 600 characters).
</ParamField>

<ParamField body="dropLandmark" type="string">
  Landmark or additional detail for the drop-off location (up to 600 characters).
</ParamField>

<ParamField body="paymentMode" type="string">
  Payment method for the ride (e.g., `CASH`, `CARD`, `WALLET`).
</ParamField>

## Response

<ResponseField name="id" type="number">
  Unique identifier for the created ride.
</ResponseField>

<ResponseField name="status" type="string">
  Always `REQUESTED` on creation.
</ResponseField>

<ResponseField name="riderId" type="number">
  The ID of the authenticated rider who booked the ride.
</ResponseField>

<ResponseField name="fare" type="number">
  Computed fare for the ride.
</ResponseField>

<ResponseField name="pickupLocation" type="string">
  Pickup location as provided in the request.
</ResponseField>

<ResponseField name="dropLocation" type="string">
  Drop-off location as provided in the request.
</ResponseField>

<ResponseField name="pickupLat" type="number">
  Pickup latitude.
</ResponseField>

<ResponseField name="pickupLon" type="number">
  Pickup longitude.
</ResponseField>

<ResponseField name="dropLat" type="number">
  Drop-off latitude.
</ResponseField>

<ResponseField name="dropLon" type="number">
  Drop-off longitude.
</ResponseField>

<ResponseField name="pickupLandmark" type="string">
  Pickup landmark.
</ResponseField>

<ResponseField name="dropLandmark" type="string">
  Drop-off landmark.
</ResponseField>

<ResponseField name="paymentMode" type="string">
  Payment mode as provided in the request.
</ResponseField>

<ResponseField name="startOtp" type="string">
  OTP the driver must verify before starting the ride.
</ResponseField>

<ResponseField name="endOtp" type="string">
  OTP the rider must confirm to mark the ride as complete.
</ResponseField>

<ResponseField name="createdAt" type="string">
  ISO 8601 timestamp of when the ride was created.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "http://localhost:8080/rides/book" \
    -H "Authorization: Bearer <token>" \
    -H "Content-Type: application/json" \
    -d '{
      "pickupLocation": "MG Road, Bangalore",
      "dropLocation": "Indiranagar, Bangalore",
      "pickupLat": 12.9757,
      "pickupLon": 77.6011,
      "dropLat": 12.9784,
      "dropLon": 77.6408,
      "pickupLandmark": "Near Café Coffee Day",
      "dropLandmark": "Opposite HDFC Bank",
      "paymentMode": "CASH"
    }'
  ```

  ```json Response theme={null}
  {
    "id": 1021,
    "status": "REQUESTED",
    "riderId": 42,
    "fare": 145.00,
    "pickupLocation": "MG Road, Bangalore",
    "dropLocation": "Indiranagar, Bangalore",
    "pickupLat": 12.9757,
    "pickupLon": 77.6011,
    "dropLat": 12.9784,
    "dropLon": 77.6408,
    "pickupLandmark": "Near Café Coffee Day",
    "dropLandmark": "Opposite HDFC Bank",
    "paymentMode": "CASH",
    "startOtp": "4821",
    "endOtp": "7364",
    "createdAt": "2026-04-02T10:15:30Z"
  }
  ```
</CodeGroup>

<Note>
  The `status` field is always set to `REQUESTED` by the server regardless of any value you send in the request body.
</Note>