Predictive Insights

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

string

The model version used to generate these insights (e.g. demand-heuristics-v1).

string

ISO 8601 timestamp of when the insights were generated.

string

Confidence level of the forecast based on historical data volume. One of LOW, MEDIUM, or HIGH.

integer

Number of historical ride records used to generate the forecast.

object

Demand forecast for the next two hours.

Show DemandForecast fields

string

Current demand trend. One of RISING, STABLE, or SOFT.

integer

Number of rides currently in REQUESTED status.

integer

Forecasted number of ride requests in the next 60 minutes.

integer

Forecasted number of ride requests in the next 120 minutes.

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

object

Surge pricing recommendation based on current demand-supply balance.

Show SurgeRecommendation fields

number

Recommended fare multiplier. 1.0 means no surge. Higher values indicate recommended price adjustments.

string

Human-readable surge level. One of NORMAL, MODERATE, HIGH, or SEVERE.

string

Explanation of why this surge level is recommended.

object

Estimated pickup time guidance for riders booking now.

Show EtaGuidance fields

integer

Typical pickup wait time under normal conditions, in minutes.

integer

Predicted pickup wait time given current demand pressure, in minutes.

integer

How many minutes longer the predicted wait is compared to the baseline.

string

Explanation of factors affecting pickup ETA.

object

Analysis of active driver supply versus forecasted demand.

Show DriverSupplyPlan fields

integer

Estimated number of drivers currently active on the platform.

integer

Number of drivers currently on an active ride (ACCEPTED or PICKED status).

integer

Recommended number of online drivers to meet the next hour’s forecasted demand.

integer

How many additional drivers need to come online to meet demand. 0 means current supply is sufficient.

string

A human-readable action recommendation based on the supply analysis.

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.

Authentication

Rides

Payments

Notifications & Settings

Predictive Insights

Request

Response

Example

​Request

​Response

​Example

Request

Response

Example