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

# Nearby Drivers

> Find available drivers within a given radius of a location.

Query the live driver location index to discover drivers currently near a specific coordinate. Results reflect each driver's most recently reported position.

**No authentication required** — this is a public endpoint.

## Request

**`GET /rides/drivers/nearby`**

<ParamField query="lat" type="number" required>
  Latitude of the center point to search from.
</ParamField>

<ParamField query="lon" type="number" required>
  Longitude of the center point to search from.
</ParamField>

<ParamField query="radiusKm" type="number">
  Search radius in kilometers. Defaults to `5` if not specified.
</ParamField>

<ParamField query="limit" type="integer">
  Maximum number of drivers to return. Defaults to `10` if not specified.
</ParamField>

## Response

An array of driver location objects. Returns an empty array if no drivers are found within the radius.

<ResponseField name="driverId" type="number">
  Unique identifier of the driver.
</ResponseField>

<ResponseField name="lat" type="number">
  Current latitude of the driver.
</ResponseField>

<ResponseField name="lon" type="number">
  Current longitude of the driver.
</ResponseField>

<ResponseField name="distanceKm" type="number">
  Distance in kilometers from the queried coordinate to the driver's current location.
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "http://localhost:8080/rides/drivers/nearby?lat=12.9757&lon=77.6011&radiusKm=3&limit=5"
  ```

  ```json Response theme={null}
  [
    {
      "driverId": 7,
      "lat": 12.9740,
      "lon": 77.5998,
      "distanceKm": 0.21
    },
    {
      "driverId": 15,
      "lat": 12.9781,
      "lon": 77.6055,
      "distanceKm": 0.58
    },
    {
      "driverId": 23,
      "lat": 12.9712,
      "lon": 77.5974,
      "distanceKm": 1.34
    }
  ]
  ```
</CodeGroup>

<Note>
  Driver locations are updated in real time as drivers report their positions. Results may be a few seconds behind each driver's actual location.
</Note>

<Warning>
  When no drivers are available in the search area, the endpoint returns an empty array (`[]`) with a `200 OK` status. Your client should handle an empty result gracefully.
</Warning>

<Tip>
  Use a smaller `radiusKm` value in dense urban areas to keep the result set relevant. In low-density areas, increase the radius or omit it to use the default of 5 km.
</Tip>