¶ Reserve Demand Shedding

Dynamically manage high demand for Reserve Rides based on real-time conditions, improving reliability and success rates.

When demand exceeds available capacity, the system temporarily limits new reservations. The Get Estimates API provides indicators reflecting ride availability, while the Create Guest Trip API enforces these restrictions.

¶ Handling Reserve Demand Shedding in Get Estimates API

The Get Estimates API now includes the fulfillment_indicators.request_blocker.block_type field, which indicates whether a ride can be booked.

¶ Possible Values and Actions

Note: UNKNOWN means the shedding information is not available for the given pickup time and location. You may proceed to book a ride.

¶ API Response Example with Reserve Shedding

"fulfillment_indicators": {
  "request_blocker": {
    "block_type": "BLOCK"
  }
}

¶ Handling reserve demand shedding in Create Guest Trip API

If a reserved ride request is made for a product with block_type=BLOCK, the Create Guest Trip API will return an error message indicating temporary unavailability.

¶ Error Response Example

{
  "error": {
    "code": "supply_capacity_reached",
    "message": "Reserving a Black SUV is temporarily unavailable. Try reserving at a different time or selecting another ride option."
  }
}

¶ Availability Predictions

Assess the likelihood of fulfilling a scheduled ride based on demand and supply conditions.

When a scheduled ride estimation request is made, the system provides a confidence level for each vehicle, indicating the likelihood of fulfillment.

Correctly interpret these predictions, ensuring users receive accurate availability information when booking scheduled rides, leading to a seamless booking experience.

¶ API Response Example with Availability Prediction:

"availability_predictor": {
  "predictor_result": "GREEN"
}

¶ Implementation Recommendation:

Note: A prediction value of UNKNOWN means that the prediction is not available for the given vehicle, ride type (e.g., Reserve), or pickup time.

¶ Identifying Reserved Vs Scheduled Rides

Based on the duration between ‘pickup time’ and ‘estimation request time’, the response of the estimate API call will include a field called product.advance_booking_type.

If the value is:

• Reserve: This means that if you proceed to book the specific vehicle type, the ride will be considered a reserve ride.
• Scheduled: This means that if you proceed to book the specific vehicle type, the ride will be considered a scheduled ride.

Different vehicles may have different thresholds indicated in the scheduled_threshold_minutes field.

• If the duration between ‘pickup time’ and ‘estimation request time’ is less than the threshold, the ride will be considered scheduled.
• If the duration between ‘pickup time’ and ‘estimation request time’ is greater than the threshold, the ride will be considered reserve.

Only the products that have reserve_info.enabled=True are eligible for reserve rides.

¶ Reserved Shedding Vs Availability Predictions

It is crucial for partners to correctly interpret API fields based on ride type:

¶ For Reserve Rides:

• Use fulfillment_indicators.request_blocker.block_type to determine if the reservation can proceed.
• Partners should NOT use fulfillment_indicators.availability_predictor.
• The system determines only whether the request will be accepted (BLOCK, WARN, NONE, or UNKNOWN).

¶ For Scheduled Rides:

• The system provides a probability estimate for servicing the scheduled ride request using color-coded indicators (GREEN, YELLOW, RED).
• This is because a scheduled ride behaves like an on-demand ride a few minutes before pickup.
• Use fulfillment_indicators.availability_predictor.predictor_result for availability predictions.

Note: Do not consider request_blocker and availability_predictor as one and the same.