Three lines

Uber

Developers

POST /requests/estimate

You are viewing the latest version of this endpoint. See previous versions of this endpoint: 1.0.

Privileged Scope This endpoint requires a privileged scope to be used in production by all Uber riders. You can use this endpoint immediately when authenticated as yourself or any of your 5 registered developers. When you are ready to distribute your application broadly for use by all Uber riders, you may request FULL ACCESS. For more information read about scopes.

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

There is an endpoint specific rate limit for this endpoint of 100 requests per hour to protect against abuse. See the rate limit guide for more information on increasing your 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.

Uber

Developers
© 2023 Uber Technologies Inc.