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

# Predictive Insights

> Get demand forecast, ETA guidance, surge recommendations, and driver supply analysis.

Retrieve real-time predictive analytics about ride demand, estimated pickup times, surge pricing signals, and driver supply needs. This endpoint is useful for building dispatcher dashboards, driver incentive screens, or demand-aware rider UX.

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

## Request

**`GET /rides/insights/predictive`**

No parameters.

## Response

<ResponseField name="model" type="string">
  The model version used to generate these insights (e.g. `demand-heuristics-v1`).
</ResponseField>

<ResponseField name="generatedAt" type="string">
  ISO 8601 timestamp of when the insights were generated.
</ResponseField>

<ResponseField name="confidence" type="string">
  Confidence level of the forecast based on historical data volume. One of `LOW`, `MEDIUM`, or `HIGH`.
</ResponseField>

<ResponseField name="sampleSize" type="integer">
  Number of historical ride records used to generate the forecast.
</ResponseField>

<ResponseField name="demandForecast" type="object">
  Demand forecast for the next two hours.

  <Expandable title="DemandForecast fields">
    <ResponseField name="trend" type="string">
      Current demand trend. One of `RISING`, `STABLE`, or `SOFT`.
    </ResponseField>

    <ResponseField name="currentOpenRequests" type="integer">
      Number of rides currently in `REQUESTED` status.
    </ResponseField>

    <ResponseField name="nextHourDemand" type="integer">
      Forecasted number of ride requests in the next 60 minutes.
    </ResponseField>

    <ResponseField name="nextTwoHoursDemand" type="integer">
      Forecasted number of ride requests in the next 120 minutes.
    </ResponseField>

    <ResponseField name="peakWindow" type="string">
      The busiest two-hour window of the day based on historical data, in `HH:MM-HH:MM` format (e.g. `08:00-10:00`).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="surgeRecommendation" type="object">
  Surge pricing recommendation based on current demand-supply balance.

  <Expandable title="SurgeRecommendation fields">
    <ResponseField name="suggestedMultiplier" type="number">
      Recommended fare multiplier. `1.0` means no surge. Higher values indicate recommended price adjustments.
    </ResponseField>

    <ResponseField name="intensity" type="string">
      Human-readable surge level. One of `NORMAL`, `MODERATE`, `HIGH`, or `SEVERE`.
    </ResponseField>

    <ResponseField name="reason" type="string">
      Explanation of why this surge level is recommended.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="etaGuidance" type="object">
  Estimated pickup time guidance for riders booking now.

  <Expandable title="EtaGuidance fields">
    <ResponseField name="baselinePickupMinutes" type="integer">
      Typical pickup wait time under normal conditions, in minutes.
    </ResponseField>

    <ResponseField name="predictedPickupMinutes" type="integer">
      Predicted pickup wait time given current demand pressure, in minutes.
    </ResponseField>

    <ResponseField name="deltaMinutes" type="integer">
      How many minutes longer the predicted wait is compared to the baseline.
    </ResponseField>

    <ResponseField name="reason" type="string">
      Explanation of factors affecting pickup ETA.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="driverSupplyPlan" type="object">
  Analysis of active driver supply versus forecasted demand.

  <Expandable title="DriverSupplyPlan fields">
    <ResponseField name="activeDriversEstimate" type="integer">
      Estimated number of drivers currently active on the platform.
    </ResponseField>

    <ResponseField name="busyDrivers" type="integer">
      Number of drivers currently on an active ride (`ACCEPTED` or `PICKED` status).
    </ResponseField>

    <ResponseField name="recommendedOnlineDrivers" type="integer">
      Recommended number of online drivers to meet the next hour's forecasted demand.
    </ResponseField>

    <ResponseField name="additionalDriversNeeded" type="integer">
      How many additional drivers need to come online to meet demand. `0` means current supply is sufficient.
    </ResponseField>

    <ResponseField name="action" type="string">
      A human-readable action recommendation based on the supply analysis.
    </ResponseField>
  </Expandable>
</ResponseField>

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET http://localhost:8080/rides/insights/predictive \
    -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."
  ```

  ```json Response theme={null}
  {
    "model": "demand-heuristics-v1",
    "generatedAt": "2026-04-02T10:30:00Z",
    "confidence": "HIGH",
    "sampleSize": 142,
    "demandForecast": {
      "trend": "RISING",
      "currentOpenRequests": 7,
      "nextHourDemand": 18,
      "nextTwoHoursDemand": 31,
      "peakWindow": "08:00-10:00"
    },
    "surgeRecommendation": {
      "suggestedMultiplier": 1.25,
      "intensity": "MODERATE",
      "reason": "7 open requests versus 4 active drivers is pushing marketplace pressure above baseline."
    },
    "etaGuidance": {
      "baselinePickupMinutes": 12,
      "predictedPickupMinutes": 15,
      "deltaMinutes": 3,
      "reason": "Demand is rising, so pickup ETA is likely to stretch beyond the normal baseline."
    },
    "driverSupplyPlan": {
      "activeDriversEstimate": 4,
      "busyDrivers": 3,
      "recommendedOnlineDrivers": 14,
      "additionalDriversNeeded": 10,
      "action": "Bring 10 more drivers online to absorb forecasted demand."
    }
  }
  ```
</CodeGroup>

<Note>
  Confidence level reflects the size of your historical ride data. New deployments with fewer than 20 historical rides will show `LOW` confidence. Accuracy improves as more rides are recorded.
</Note>