1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

function calculateEffectiveSupply(zone, vehicleType, time):
    // Raw count of online drivers in zone
    rawDriverCount = getOnlineDrivers(zone, vehicleType).length
    
    // Subtract drivers currently on trips
    onTripDrivers = getDriversOnTrip(zone, vehicleType).length
    
    // Add back drivers whose trips end soon (within 5 min)
    completingSoonDrivers = getDriversCompletingTrip(zone, vehicleType, within=5min)
    
    // Factor in drivers heading TO this zone
    inboundDrivers = getDriversHeadingToZone(zone, vehicleType, within=10min)
    
    // Factor in expected offline (drivers who typically go offline at this time)
    expectedAttrition = predictDriverAttrition(zone, time, window=15min)
    
    // Effective supply considers probability-weighted future state
    effectiveSupply = (
        rawDriverCount 
        - onTripDrivers 
        + completingSoonDrivers * 0.8  // 80% weight for uncertainty
        + inboundDrivers * 0.5         // 50% weight for less certainty
        - expectedAttrition * 0.7      // 70% weight for predicted departures
    )
    
    return max(effectiveSupply, 0)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

function calculateDemandSignals(zone, vehicleType, time):
    // Explicit demand: actual ride requests in last N minutes
    recentRequests = getRideRequests(zone, vehicleType, lastMinutes=5)
    explicitDemand = recentRequests.length
    
    // Unfulfilled demand: requests that didn't get matched
    unfulfilledDemand = recentRequests.filter(r => r.status == 'no_drivers').length
    
    // App opens without request (user checked, found high surge, closed)
    appOpensWithoutRequest = getAppOpensWithoutRideRequest(zone, lastMinutes=5)
    latentDemand = appOpensWithoutRequest * LATENT_DEMAND_FACTOR  // ~0.3
    
    // Historical pattern: expected demand based on historical data
    historicalBaseline = predictDemandFromHistory(zone, vehicleType, time)
    
    // Event-driven demand: concerts, sports, weather alerts
    eventDemand = getEventDrivenDemandPrediction(zone, time)
    
    // Combine signals with weights
    totalDemand = (
        explicitDemand * 1.0
        + unfulfilledDemand * 1.5  // Weight unfulfilled higher (real demand!)
        + latentDemand * 0.5
        + max(historicalBaseline - explicitDemand, 0) * 0.3  // If below baseline
        + eventDemand * 0.8
    )
    
    return totalDemand

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

function calculateBasicSurge(zone, vehicleType):
    supply = calculateEffectiveSupply(zone, vehicleType)
    demand = calculateDemandSignals(zone, vehicleType)
    
    // Avoid division by zero
    if supply == 0:
        return MAX_SURGE  // e.g., 5.0x
    
    // Simple ratio
    ratio = demand / supply
    
    // No surge if supply exceeds demand
    if ratio <= 1.0:
        return 1.0  // Base price
    
    // Map ratio to surge multiplier
    // ratio 1.5 → 1.3x, ratio 2.0 → 1.6x, ratio 3.0 → 2.2x, etc.
    surge = 1.0 + (ratio - 1.0) * SURGE_SENSITIVITY  // SURGE_SENSITIVITY ~0.5-0.8
    
    // Apply caps
    surge = clamp(surge, 1.0, MAX_SURGE)
    
    // Apply minimum step (no 1.05x surge, either 1.0 or 1.2+)
    if surge < MIN_MEANINGFUL_SURGE:  // e.g., 1.2
        surge = 1.0
    
    // Round to nearest step (1.2, 1.4, 1.6, 1.8, 2.0, etc.)
    return roundToStep(surge, 0.1)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

function calculateElasticityAwareSurge(zone, vehicleType, context):
    supply = calculateEffectiveSupply(zone, vehicleType)
    demand = calculateDemandSignals(zone, vehicleType)
    
    // Estimate demand elasticity for current context
    elasticity = estimateDemandElasticity(zone, context)
    // elasticity: -0.5 (inelastic) to -2.0 (elastic)
    // More negative = demand drops more with price increase
    
    // Target utilization (supply slightly exceeds demand for quality)
    targetUtilization = 0.85  // Want 85% of drivers occupied
    
    // Current utilization
    currentUtilization = min(demand / max(supply, 1), 1.0)
    
    // Price elasticity formula:
    // % change in quantity demanded = elasticity × % change in price
    // We want to find price that reduces demand to target utilization
    
    if currentUtilization <= targetUtilization:
        return 1.0  // No surge needed
    
    // Required demand reduction
    requiredReduction = (currentUtilization - targetUtilization) / currentUtilization
    
    // Price increase needed (inverting elasticity formula)
    // requiredReduction = -elasticity × priceIncrease
    // priceIncrease = requiredReduction / (-elasticity)
    priceIncrease = requiredReduction / abs(elasticity)
    
    surge = 1.0 + priceIncrease
    
    return clamp(roundToStep(surge, 0.1), 1.0, MAX_SURGE)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

class SurgeController:
    // Store recent surge values per zone
    surgeHistory = {}  // zone → list of (timestamp, surge)
    
    function getSmoothedSurge(zone, rawSurge):
        history = surgeHistory.get(zone, [])
        
        // Add current value
        history.append((now(), rawSurge))
        
        // Keep last 10 minutes of history
        history = history.filter(entry => entry.timestamp > now() - 10min)
        surgeHistory[zone] = history
        
        // Exponential weighted moving average
        // Recent values weighted more heavily
        weights = []
        values = []
        for (timestamp, surge) in history:
            age = now() - timestamp
            weight = exp(-age.seconds / 120)  // 2-minute half-life
            weights.append(weight)
            values.append(surge)
        
        smoothedSurge = weightedAverage(values, weights)
        
        // Rate limit: don't change more than 0.5x per update cycle
        lastSurge = history[-2].surge if len(history) > 1 else 1.0
        maxChange = 0.5
        smoothedSurge = clamp(
            smoothedSurge,
            lastSurge - maxChange,
            lastSurge + maxChange
        )
        
        return roundToStep(smoothedSurge, 0.1)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

class SurgeCalculatorService:
    RECOMPUTE_INTERVAL = 30  // seconds
    
    @scheduled(every=RECOMPUTE_INTERVAL)
    async function recomputeAllZones():
        zones = getAllActiveZones()  // Zones with recent activity
        
        for zone in zones:
            for vehicleType in ['UberX', 'UberXL', 'UberBlack']:
                // Get aggregated values
                supply = await supplyAggregator.getSupply(zone, vehicleType)
                demand = await demandAggregator.getDemand(zone, vehicleType)
                
                // Compute raw surge
                rawSurge = computeSurge(supply, demand, zone.context)
                
                // Apply smoothing
                smoothedSurge = smoother.smooth(zone, rawSurge)
                
                // Apply policy overrides (emergencies, promotions, regulations)
                finalSurge = policyEngine.apply(zone, smoothedSurge)
                
                // Store
                await zoneState.set(zone, vehicleType, finalSurge)
                await historyStore.append(zone, vehicleType, finalSurge, now())
        
        // Broadcast update to edge caches
        await broadcastSurgeUpdate()
        
        metrics.record('surge.recompute.completed', zones.length)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

class SurgePolicyEngine:
    
    function apply(zone, calculatedSurge):
        // Rule 1: Emergency surge caps
        if isEmergencyDeclared(zone.region):
            return min(calculatedSurge, EMERGENCY_SURGE_CAP)  // e.g., 1.5x
        
        // Rule 2: Regulatory caps (some cities limit surge)
        if zone.region.hasRegulatorySurgeCap:
            return min(calculatedSurge, zone.region.surgeCap)
        
        // Rule 3: New user protection (first 3 rides no surge)
        // (Applied at pricing service, not here)
        
        // Rule 4: Promo zones (marketing-driven surge suppression)
        if zone in getActivePromoZones():
            return 1.0  // No surge in promo areas
        
        // Rule 5: Time-of-day caps (late night safety concerns)
        if isLateNight() and zone.isResidential:
            return min(calculatedSurge, 2.0)
        
        // Rule 6: Event-specific handling
        event = getActiveEvent(zone)
        if event and event.isCommunityEvent:
            // Suppress surge during community events (PR consideration)
            return min(calculatedSurge, 1.3)
        
        return calculatedSurge

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

// API response for rider app price estimate
{
    "pickup": { "lat": 40.7484, "lng": -73.9857 },
    "dropoff": { "lat": 40.7614, "lng": -73.9776 },
    "estimates": [
        {
            "product": "UberX",
            "display_name": "UberX",
            "fare_estimate": {
                "low": 22.50,
                "high": 28.00,
                "currency": "USD"
            },
            "surge": {
                "is_surging": true,
                "multiplier": 1.8,
                "display_text": "Prices are higher due to increased demand",
                "estimated_end_time": "2024-01-15T18:45:00Z",  // When surge might drop
                "locked_until": "2024-01-15T18:25:00Z"  // Price locked for 5 min
            },
            "eta_minutes": 4,
            "alternatives": [
                {
                    "type": "wait",
                    "wait_minutes": 15,
                    "predicted_fare": { "low": 15.00, "high": 19.00 }
                },
                {
                    "type": "product_switch",
                    "product": "UberPool",
                    "fare_estimate": { "low": 12.00, "high": 16.00 }
                }
            ]
        }
    ]
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

class PredictiveSurgeEngine:
    
    async function predictSurge(zone, futureTime):
        // Feature extraction
        features = {
            // Historical patterns
            "historical_demand": getHistoricalDemand(zone, futureTime.dayOfWeek, futureTime.hour),
            "historical_supply": getHistoricalSupply(zone, futureTime.dayOfWeek, futureTime.hour),
            
            // Events
            "event_ending_nearby": getEventsEndingNear(zone, futureTime),
            "event_capacity": sumEventCapacity(zone, futureTime),
            
            // Weather
            "precipitation_probability": getWeatherForecast(zone, futureTime).precipProb,
            "temperature": getWeatherForecast(zone, futureTime).temp,
            
            // Calendar
            "is_holiday": isHoliday(futureTime),
            "is_payday": isPayday(futureTime),
            
            // Recent trends
            "current_surge": getCurrentSurge(zone),
            "surge_trend_30m": getSurgeTrend(zone, minutes=30),
        }
        
        // ML model predicts surge
        predictedSurge = model.predict(features)
        
        return {
            "zone": zone,
            "time": futureTime,
            "predicted_surge": predictedSurge,
            "confidence": model.confidence(features)
        }
    
    async function proactivelySendDriverNotifications():
        zones = getAllZones()
        predictions = []
        
        for zone in zones:
            for horizon in [15, 30, 60]:  // minutes ahead
                futureTime = now() + horizon.minutes
                prediction = await predictSurge(zone, futureTime)
                if prediction.predicted_surge > 1.5:
                    predictions.append(prediction)
        
        // Notify drivers near zones with upcoming high surge
        for prediction in predictions.sortBy(p => -p.predicted_surge):
            nearbyDrivers = getDriversNear(prediction.zone, radius=5km)
            for driver in nearbyDrivers:
                sendNotification(driver, 
                    f"High demand expected in {prediction.zone.name} " +
                    f"in {prediction.horizon} min. Head there for higher earnings!")