Driver 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"]
}
}
¶ Time frame
The payments and trips endpoints allow to define a start and end time for the query. Both, from_time
and to_time
are optional query parameters. Please check out the endpoint documentation to understand behavior when one or both parameters are omitted.
¶ Endpoints
Method | Endpoint | Description |
---|---|---|
POST | /v2/token | none |
GET | /v1/partners/me | Get driver profile |
GET | /v1/partners/payments | Get driver payments |
GET | /v1/partners/trips | Get driver trips |