POST /requests/estimate
¶ Ride Request - Estimate
The Request Estimate endpoint allows a ride to be estimated given the desired product, start, and end locations. If the pickup ETA is null, there are no cars available even if an estimate may still be given to the user.
You should use this endpoint to get an upfront fare before requesting a ride. In some products upfront fares are not enabled so you can use this endpoint to determine if surge pricing is in effect for the product/location. Do this before attempting to make a ride request so that you can preemptively have a user confirm surge by sending them to the surge_confirmation_href
provided in the response.
This endpoint will either return an upfront fare (in the fare
key) or a range estimate (in the estimate
key) depending on the configuration of the product.
See the Ride Request tutorial for a step-by-step guide to requesting rides on behalf of an Uber user. Please review the sandbox documentation on how to develop and test against these endpoints without making real-world Ride Requests and being charged.
¶ Resource
POST /v1.2/requests/estimate
¶ Authorization
OAuth 2.0 user access token with the request
scope.
¶ Rate Limit
¶ POST Parameters
Name | Type | Description |
---|---|---|
product_id |
string |
The unique ID of the product being requested. If none is provided, it will default to the cheapest product for the given location. |
start_latitude |
float |
The beginning or “pickup” latitude. Either this or start_place_id must be specified. |
start_longitude |
float |
The beginning or “pickup” longitude. Either this or start_place_id must be specified. |
start_place_id (optional) |
string |
The beginning or “pickup” place ID. This is the name of an Uber saved place. Only “home” or “work” is acceptable. Either this or start_latitude and start_longitude must be specified. |
end_latitude |
float |
The end or “destination” latitude. Either this or end_place_id must be specified. |
end_longitude |
float |
The end or “destination” longitude. Either this or end_place_id must be specified. |
end_place_id (optional) |
string |
The final or destination place id. This is the name of an Uber saved place. Only “home” or “work” is acceptable. Either this or end_latitude and end_longitude may be specified. |
seat_count (optional) |
int |
The number of seats required for uberPOOL. Default and maximum value is 2. |
¶ Example Request
curl -X POST \
-H 'Authorization: Bearer <TOKEN>' \
-H 'Accept-Language: en_US' \
-H 'Content-Type: application/json' \
-d '{
"start_latitude": 37.7752278,
"start_longitude": -122.4197513,
"end_latitude": 37.7773228,
"end_longitude": -122.4272052
}' "https://api.uber.com/v1.2/requests/estimate"
¶ Example Response with Upfront Fares
Status-Code: 200 OK
{
"fare": {
"value": 5.73,
"fare_id": "d30e732b8bba22c9cdc10513ee86380087cb4a6f89e37ad21ba2a39f3a1ba960",
"expires_at": 1476953293,
"display": "$5.73",
"currency_code": "USD",
"breakdown": [
{
"type": "promotion",
"value": -2.00,
"name": "Promotion"
},
{
"type": "base_fare",
"notice": "Fares are slightly higher due to increased demand",
"value": 7.73,
"name": "Base Fare"
}
]
},
"trip": {
"distance_unit": "mile",
"duration_estimate": 540,
"distance_estimate": 2.39
},
"pickup_estimate": 2
}
¶ Example Response with Surge Pricing
Status-Code: 200 OK
{
"estimate": {
"surge_confirmation_href": "https:\/\/api.uber.com\/v1\/surge-confirmations\/7d604f5e",
"high_estimate": 11,
"surge_confirmation_id": "7d604f5e",
"minimum": 5,
"low_estimate": 8,
"fare_breakdown": [
{
"low_amount": 1.25,
"high_amount": 1.25,
"display_amount": "1.25",
"display_name": "Base Fare"
},
{
"low_amount": 1.92,
"high_amount": 2.57,
"display_amount": "1.92-2.57",
"display_name": "Distance"
},
{
"low_amount": 2.50,
"high_amount": 3.50,
"display_amount": "2.50-3.50",
"display_name": "Surge x1.5"
},
{
"low_amount": 1.25,
"high_amount": 1.25,
"display_amount": "1.25",
"display_name": "Booking Fee"
},
{
"low_amount": 1.36,
"high_amount": 1.81,
"display_amount": "1.36-1.81",
"display_name": "Time"
}
],
"surge_multiplier": 1.5,
"display": "$8-11",
"currency_code": "USD"
},
"trip": {
"distance_unit": "mile",
"duration_estimate": 480,
"distance_estimate": 1.95
},
"pickup_estimate": 2
}
Name | Type | Description |
---|---|---|
pickup_estimate |
integer |
The estimate vehicle arrival time in minutes. null if no cars are available. |
estimate |
object |
Estimated fare details. Only products that don’t support upfront fares return this value. |
estimate.surge_multiplier |
float |
Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Fare estimates below factor in the surge multiplier. |
estimate.surge_confirmation_id |
string |
A user’s unique surge session identifier. null if no surge is in effect. |
estimate.surge_confirmation_href |
string |
The URL a user must visit to accept surge pricing. |
estimate.minimum |
integer |
The minimum trip fare. Only used and displayed if no end location is provided. |
estimate.display |
string |
Estimates are ranges except for the TAXI product, which uses “Metered”. |
estimate.low_estimate |
integer |
Lower bound of the estimate. |
estimate.high_estimate |
integer |
Upper bound of the estimate. |
estimate.currency_code |
string |
ISO 4217 currency code. |
estimate.fare_breakdown |
array |
Charges that contribute to the total fare. Trips with upfront pricing don’t have a breakdown. |
estimate.fare_breakdown[].low_amount |
float |
Lower bound of the charge. |
estimate.fare_breakdown[].high_amount |
float |
Upper bound of the charge. |
estimate.fare_breakdown[].display_amount |
float |
Formatted string of the breakdown charge. Charges are ranges except for flat charges, which are single numbers. |
estimate.fare_breakdown[].display_name |
string |
Charge name. |
trip |
object |
Estimated distance details. |
trip.distance_estimate |
float |
Expected activity distance. |
trip.distance_unit |
string |
The distance unit, either mile or km . |
trip.duration_estimate |
integer |
Expected activity duration (in seconds). |
fare |
string |
The upfront fare details. |
fare.fare_id |
string |
A unique upfront fare identifier. |
fare.value |
string |
The total upfront fare value. |
fare.currency_code |
string |
ISO 4217 currency code. |
fare.display |
string |
Formatted string of estimate in local currency. |
fare.expires_at |
int |
The fare_id expiration as a Unix timestamp. |
fare.breakdown |
array |
An array of objects which make up the fare. The value of these objects can be summed to arrive at fare.value . |
fare.breakdown[].type |
string |
The type of breakdown this object represents. Can be base_fare or promotion . |
fare.breakdown[].value |
float |
The value of this portion of the fare. This can be a negative or positive value. |
fare.breakdown[].name |
string |
A string that can be displayed to the user representing this portion of the fare. |
fare.breakdown[].notice |
string |
A notice to show to the rider when a fare is higher than normal due to increased demand. |
¶ HTTP Error Codes
Below is a list of the HTTP error codes this endpoint could return.
HTTP Status | Code | Description |
---|---|---|
403 | current_trip_exists | Trip estimates not allowed while the user is currently on a trip. |
404 | not_found | Invalid product_id. |
404 | no_product_found | Could not find a default product. |
422 | distance_exceeded | Distance between start and end location exceeds 100 miles. |
422 | same_pickup_dropoff | Pickup and Dropoff can’t be the same. |