Three lines

Uber

Developers

Riders API Reference

The Uber API makes it easy to tap into the digital mesh that runs across cities. Make requests to our API endpoints and we’ll give you everything you need to create new and magical experiences for your users. The possibilities are endless!

All production API requests are made to:

https://api.uber.com/<version>

The current version of the API is v1.2. Backwards incompatible changes will result in a version bump. Some of our API endpoints require OAuth 2.0 credentials. Please see the Authentication & Authorization guide to get started.

There is also a sandbox to use when developing and testing applications, with requests being made to:

https://sandbox-api.uber.com/<version>

REST

The Uber API is a RESTful API. This means that the API is designed to allow you to get, create, update, & delete objects with the HTTP verbs GET, POST, PUT, PATCH, & DELETE.

JSON

The Uber API speaks exclusively in JSON. This means that you should always set the Content-Type header to application/json to ensure that your requests are properly accepted and processed by the API.

Authentication

All API calls require authentication using either a server token or bearer token depending on the endpoint. Bearer tokens allow your application to access the Uber API on behalf of a user and are obtained after a user has authorized your application through one of the supported OAuth 2.0 authorization grants. Bearer tokens are valid for authentication on all endpoints within the API.

For endpoints where user context is not necessary, such as GET /v1/products, you may use your application’s server token instead of having to authenticate a specific user.

Note: We no longer issue new server tokens. We are planning to remove the support of server tokens in favour of scope based access tokens in the near future.

Some endpoints such as Ride Request - Receipt require privileged scopes to be used in production by all Uber riders. For more information read about scopes.

Cross-Origin Resource Sharing

The Uber API supports CORS for communicating from Javascript for these endpoints. You will need to specify an Origin URI (found in the Settings tab under Security section) when creating your application to allow for CORS to be whitelisted for your domain. Please note that your server_token is still considered sensitive and it is your responsibility to protect it.

var xhr = new XMLHttpRequest();
xhr.open('GET', 'https://api.uber.com/v1.2/products?latitude=37.7759792&longitude=-122.41823');
xhr.setRequestHeader("Authorization", "Token <TOKEN>");
xhr.send();

Pagination

Some endpoints such as Rider History return a potentially lengthy array of objects. In order to keep the response sizes manageable the API will take advantage of pagination. Pagination is a mechanism for returning a subset of the results for a request and allowing for subsequent requests to “page” through the rest of the results until the end is reached. Paginated endpoints follow a standard interface that accepts two query parameters, limit and offset, and return a payload that follows a standard form. These parameters names and their behavior are borrowed from PostgreSQL LIMIT and OFFSET keywords.

Versioning

The Uber API is constantly being worked on to add features, make improvements, and fix bugs. This means that you should expect changes to be introduced and documented. Whenever we make a significant change to an endpoint, we will increase the version number used in the path of the resource being requested.

However, there are some changes or additions that are considered backwards-compatible and your applications should be flexible enough to handle them. These include:

  • Adding new endpoints to the API
  • Adding new attributes to the response of an existing endpoint
  • Changing the order of attributes of responses (JSON by definition is an object of unordered key/value pairs)

Common Types

IDs in the Uber API are not guaranteed to be UUIDs and will be variable length.

Date and time will be expressed as an integer which represents the number of seconds since the Unix epoch in UTC.

Latitude and longitude will be expressed as floats, with the precision on both the request and response up to six decimal places.

Phone numbers will be expressed in E.164 format.

Country codes will be expressed as ISO 3166-1 alpha-3 code.

HTTP Status Codes

Status Code Description
200 OK. Everything worked as expected.
201 Created. We will return a 201 after a successful POST where a resource was created.
302 Retry request on given redirect URI.
400 Malformed request.
401 Unauthorized. The request requires user authentication (not logged in). Also used for invalid OAuth 2.0 credentials.
403 Forbidden. Also used for unauthorized requests such as improper OAuth 2.0 scopes or permissions issues.
403 User not allowed. User is banned and is not permitted to request a ride.
404 Not found.
406 Unacceptable content type. Client sent an accepts header for a content type which does not exist on the server. Body includes a list of acceptable content types, such as “Unacceptable content type. Request resource as: application/json.
409 A conflict needs to be resolved before the request can be made.
422 Invalid request. The request body is parse-able however with invalid content or there are issues with a rider’s user account.
429 Too Many Requests. Exceeded the rate limit for requests.
500 Internal Server Error.
503 The backend server is not available.

Errors

Error responses will have a consistently formed JSON body. The keys may include:

Key Value
message Human readable message which corresponds to the client error.
code Underscored delimited string.
fields (optional) A hash of field names that have validations. This has a value of an array with member strings that describe the specific validation error.
Error Response

Status-Code: 422 Invalid Request

{
  "message": "Invalid user",
  "code": "invalid",
  "fields": {
    "first_name": ["Required"]
  }
}

API Endpoints

Method Endpoint Description
GET /products List products
GET /products/{product_id} Get product details
GET /estimates/price Get price estimates
GET /estimates/time Get time estimates
GET /me Get user information
PATCH /me Apply a user promotion
GET /history Get user history
GET /places/{place_id} Get a saved place
PUT /places/{place_id} Update a saved place
POST /requests/estimate Get request estimate
POST /requests Create ride request
GET /requests/{request_id} Get ride details
DELETE /requests/{request_id} Cancel request
PATCH /requests/{request_id} Update request
GET /requests/{request_id}/map Get tracking map
GET /requests/{request_id}/receipts Get receipt

Uber

Developers
© 2023 Uber Technologies Inc.