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.