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

# Driver Workflow

> Accept rides, verify OTPs, share your live location, and complete trips using the RideShare API.

<Note>
  Endpoints that update ride state or location require an `Authorization` header with a valid bearer token.

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

<Steps>
  <Step title="View available rides">
    Fetch all rides that riders have requested but no driver has accepted yet.

    ```bash theme={null}
    GET /rides/requested
    ```

    **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",
        "riderName": "Priya S.",
        "createdAt": "2026-04-02T10:15:00Z"
      }
    ]
    ```

    Poll this endpoint regularly or integrate with your notification handler to pick up new requests quickly.
  </Step>

  <Step title="Accept a ride">
    Claim a ride by posting the `ACCEPTED` status along with your driver ID.

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

    ```json theme={null}
    {
      "status": "ACCEPTED",
      "driverId": "55"
    }
    ```

    **Example response**

    ```json theme={null}
    {
      "id": 1042,
      "status": "ACCEPTED",
      "driverId": 55,
      "acceptedAt": "2026-04-02T10:17:00Z",
      "startOtp": "4521",
      "pickupLocation": "MG Road, Bengaluru",
      "dropLocation": "Koramangala, Bengaluru",
      "fare": 142.50
    }
    ```

    The response includes `startOtp`. Keep this value — the rider will read it back to you at pickup to confirm the correct passenger before you start the trip.
  </Step>

  <Step title="Mark the ride as picked up">
    Once you have arrived and the rider confirms their identity by giving you the `startOtp`, post the `PICKED` status with that OTP to start the trip.

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

    ```json theme={null}
    {
      "status": "PICKED",
      "otp": "4521"
    }
    ```

    <Warning>
      The request will fail if the `otp` value does not match the `startOtp` stored against the ride. Always verify the OTP with the rider before submitting this request.
    </Warning>

    **Example response**

    ```json theme={null}
    {
      "id": 1042,
      "status": "PICKED",
      "endOtp": "7832"
    }
    ```

    The response now includes `endOtp`. You will need this to complete the ride at the destination.
  </Step>

  <Step title="Update your live location">
    While the trip is in progress, post your current coordinates so the rider can track you in real time.

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

    ```json theme={null}
    {
      "lat": 12.9650,
      "lon": 77.6100
    }
    ```

    **Example response**

    ```json theme={null}
    {
      "id": 1042,
      "driverLat": 12.9650,
      "driverLon": 77.6100,
      "driverLocationUpdatedAt": "2026-04-02T10:22:10Z"
    }
    ```

    <Tip>
      Send a location update every 5–10 seconds during the trip. Infrequent updates result in a choppy map experience for the rider, which negatively affects your rating.
    </Tip>
  </Step>

  <Step title="Complete the ride">
    At the destination, ask the rider for the `endOtp` and post the `COMPLETED` status with that value to close out the trip.

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

    ```json theme={null}
    {
      "status": "COMPLETED",
      "otp": "7832"
    }
    ```

    <Warning>
      The request will fail if the `otp` value does not match the `endOtp` stored against the ride. The rider must provide the correct code before you can mark the trip as complete.
    </Warning>

    **Example response**

    ```json theme={null}
    {
      "id": 1042,
      "status": "COMPLETED",
      "fare": 142.50,
      "paymentMode": "upi",
      "paymentStatus": "PAID"
    }
    ```
  </Step>
</Steps>

## Find nearby drivers

Use this endpoint to surface available drivers close to a given location — useful for building a dispatcher view or a rider-facing "drivers near you" preview.

```bash theme={null}
GET /rides/drivers/nearby?lat=12.97&lon=77.59&radiusKm=5&limit=10
```

| Parameter  | Required | Default | Description                         |
| ---------- | -------- | ------- | ----------------------------------- |
| `lat`      | Yes      | —       | Latitude of the search centre       |
| `lon`      | Yes      | —       | Longitude of the search centre      |
| `radiusKm` | No       | `5`     | Search radius in kilometres         |
| `limit`    | No       | `10`    | Maximum number of drivers to return |

**Example response**

```json theme={null}
[
  {
    "driverId": 55,
    "lat": 12.9730,
    "lon": 77.5960,
    "distanceKm": 0.8
  },
  {
    "driverId": 61,
    "lat": 12.9680,
    "lon": 77.5900,
    "distanceKm": 1.4
  }
]
```

If no drivers are cached in the search area the endpoint returns an empty array (`[]`).