Skip to main content
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

​
model
string
The model version used to generate these insights (e.g. demand-heuristics-v1).
​
generatedAt
string
ISO 8601 timestamp of when the insights were generated.
​
confidence
string
Confidence level of the forecast based on historical data volume. One of LOW, MEDIUM, or HIGH.
​
sampleSize
integer
Number of historical ride records used to generate the forecast.
​
demandForecast
object
Demand forecast for the next two hours.
​
surgeRecommendation
object
Surge pricing recommendation based on current demand-supply balance.
​
etaGuidance
object
Estimated pickup time guidance for riders booking now.
​
driverSupplyPlan
object
Analysis of active driver supply versus forecasted demand.

​
Example

curl -X GET http://localhost:8080/rides/insights/predictive \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

{
  "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."
  }
}
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.