Uber API

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!

Base URI

https://api.uber.com
Documentation
Deep Linking

Deep linking provides application interoperability between a native app or web view, and the native Uber application. Please refer to the UX Recommendations in the Uber API Design Guidelines to determine when to use each deep linking option.

#IOS

For deep linking on iOS, first check to see if the Uber app is installed on the user’s device. If the Uber app is installed, launch the Uber app; if the Uber app is not installed, launch Uber’s mobile site (m.uber.com).

To determine if the Uber app is installed on iOS, use the following call:

if ([[UIApplication sharedApplication] canOpenURL:[NSURL URLWithString:@"uber://"]]) {
    // Do something awesome - the app is installed! Launch App.
}
else {
    // No Uber app! Open Mobile Website.
}

##LAUNCHING THE UBER APP

To launch the Uber app, use the following call (at a minimum):

uber://?action=setPickup&pickup=my_location

You can add additional query parameters as listed below. Note that there is no need to add an additional setDropoff action. Please refer to the examples below as needed.

Query Parameters

Passing parameters can make the Uber experience even more seamless for your users. For example, dropoff location parameters can be used to automatically pass the user’s destination information over to the driver.

Parameters used in linking must be URL-encoded with %20 for spaces. Note that the keys for pickup and dropoff are the same. nickname and formatted_address may be omitted if they are the same.

Name Type Description
client_id int Client identifier of the requesting application
product_id string The product to populate in pickup
pickup[latitude] float The latitude coordinate for pickup
pickup[longitude] float The longitude coordinate for pickup
pickup[nickname] string A URL-encoded string of the pickup location name
pickup[formatted_address] string URL-encoded address
pickup=my_location (none) User's current location
dropoff[latitude] float The latitude coordinate for dropoff
dropoff[longitude] float The longitude coordinate for dropoff
dropoff[nickname] string A URL-encoded string of the dropoff location name
dropoff[formatted_address] string URL-encoded address

Example

Set pickup and dropoff locations with latitude & longitude pairs, nicknames and formatted addresses. Select Uber product by passing product_id returned from the Products endpoint.

uber://?client_id=YOUR_CLIENT_ID&action=setPickup&pickup[latitude]=37.775818&pickup[longitude]=-122.418028&pickup[nickname]=UberHQ&pickup[formatted_address]=1455%20Market%20St%2C%20San%20Francisco%2C%20CA%2094103&dropoff[latitude]=37.802374&dropoff[longitude]=-122.405818&dropoff[nickname]=Coit%20Tower&dropoff[formatted_address]=1%20Telegraph%20Hill%20Blvd%2C%20San%20Francisco%2C%20CA%2094133&product_id=a1111c8c-c720-46c3-8534-2fcdd730040d

#ANDROID

For deep linking on Android, first check to see if the Uber app is installed on the user’s device. If the Uber app is installed, launch the Uber app; if the Uber app is not installed, launch Uber’s mobile site (m.uber.com).

To determine if the Uber app is installed on Android, use the following call:

PackageManager pm = context.getPackageManager(); try

{
   pm.getPackageInfo("com.ubercab", PackageManager.GET_ACTIVITIES);
   // Do something awesome - the app is installed! Launch App.
}
catch (PackageManager.NameNotFoundException e)
{
   // No Uber app! Open Mobile Website.
}

Android supports the same URL and query parameters as iOS, so please refer to the App Launch section for iOS for more information and examples.

#MOBILE WEB

For scenarios where the user does not have the Uber app installed on their device, deep link to the Uber mobile site (m.uber.com)

##LAUNCHING THE UBER MOBILE SITE

To launch the Uber mobile site (m.uber.com), use the following call and pass your client ID to allow the user to sign up for Uber:

GET https://m.uber.com/sign-up?client_id=YOUR_CLIENT_ID

Query Parameters

Passing parameters can make the Uber experience even more seamless for your users. To make the signup process more seamless, pass additional query parameters about the user. Also, dropoff location parameters can be used to automatically pass the user’s destination information over to the driver.

Parameters used in linking must be URL-encoded with %20 for spaces.

Name Type Description
client_id string Client identifier of the requesting application. Required to correctly attribute new signups originating from your app.
first_name (optional) string First name of the user. Recommended to provide seamless signup experience.
last_name (optional) string Last name of the user. Recommended to provide seamless signup experience.
email (optional) string User's email address. Recommended to provide seamless signup experience.
country_code (optional) string 2 Letter ISO Country code.
mobile_country_code (optional) string Country code for the mobile phone number.
mobile_phone (optional) string Mobile phone number.
zipcode (optional) string User's zip code.
device_id (optional) string Unique device identifier.
android_device_id (optional) string IMEI for Android devices.
google_aid (optional) string Google advertising identifier (For Android devices).
ios_aid (optional) string iOS advertising identifier (For iOS devices).
windows_aid (optional) string Windows advertising identifier(For Windows devices).
product_id (optional) string Product option selected by the user.
pickup_latitude (optional) float Latitude component of pickup location.
pickup_longitude (optional) float Longitude component of pickup location.
pickup_nickname (optional) string Nickname to show for pickup location.
pickup_address (optional) string Formatted pickup address to show to user.
dropoff_latitude (optional) float Latitude component of dropoff location.
dropoff_longitude (optional) float Longitude component of dropoff location.
dropoff_nickname (optional) string Nickname to show for dropoff location.
dropoff_address (optional) string Formatted dropoff address to show to user

Example

Set pickup and dropoff locations with latitude & longitude pairs, nicknames and formatted addresses. Select Uber product by passing product_id returned from the Products endpoint.

https://m.uber.com/sign-up?client_id=YOUR_CLIENT_ID
&first_name=myFirstName&last_name=myLastName&email=test@example.com
&country_code=us&mobile_country_code=%2B1&mobile_phone=123-456-7890
&zipcode=94111&product_id=a1111c8c-c720-46c3-8534-2fcdd730040d&pickup_latitude=37.775818
&pickup_longitude=-122.418028&pickup_nickname=Uber%20HQ
&pickup_address=1455%20Market%20St%2C%20San%20Francisco%2C%20CA%2094103
&dropoff_latitude=37.802374&dropoff_longitude=-122.405818
&dropoff_nickname=Coit%20Tower
&dropoff_address=1%20Telegraph%20Hill%20Blvd%2C%20San%20Francisco%2C%20CA%2094133
Authentication

The Uber API implements the OAuth 2.0 standard for secure authentication and authorization. All communication with our servers must be over SSL (https://).

AUTHENTICATION OR AUTHORIZATION?

Before you begin, you should determine what level of access your application needs. Many applications will only use the Products, Price Estimates, and Time Estimates endpoints. For these, you only need to use the server_token to access resources via the API Token Authentication.

If your application will access resources on behalf of an Uber user, such as with the Me and User Activity) endpoints, you will need to follow the three-legged OAuth 2.0 flow in order to obtain an access_token.

API TOKEN AUTHENTICATION

In order to access protected resources you can pass your API Token, called a server_token. This must be passed as an Authorization header with type Token.

Example:

curl -H 'Authorization: Token YOUR_SERVER_TOKEN' \
'https://api.uber.com/v1/products?latitude=37.7759792&longitude=-122.41823'

OAUTH 2.0

OAuth 2.0is a specification outlined in RFC 6749 that allows third-party services to make requests on behalf of a user without accessing passwords and other sensitive information. If you are unfamiliar with OAuth 2.0, check out Aaron Parecki's "OAuth 2 Simplified" guide. We recommend that you use a pre-built library to perform grant and token exchanges. Python, Ruby, or NodeJS.

STEP ONE: AUTHORIZE

The first step of the flow is to redirect a user to the following URL, with the appropriate query parameters for your application. The response will be an HTML web form where the resource owner is authenticated with the Uber API and is prompted to approve or deny your request for OAuth 2.0 permissions. The scope requested (or the application defaults) will be displayed.

GET https://login.uber.com/oauth/authorize
Parameter Description
response_type OAuth 2.0 response type. code is the only acceptable input at this time.
client_id The client ID of your application.
scopes (optional) Comma delimited list of grant scopes you would like to have permission to access on behalf of the user.
state (optional) State which will be passed back to you to prevent tampering.
redirect_uri(optional) The URI we will redirect back to after an authorization by the resource owner. The base of the URI must match the redirect_uri used during the registration of your application.

STEP TWO: RECEIVE REDIRECT

Once the Uber user authenticates and authorizes your app, Uber will issue an HTTP 302 redirect to the redirect_uri passed in. On that redirect, you will receive an authorization code, which is single use and expires in 10 minutes.

GET https://your-redirect-uri/?code=AUTHORIZATION_CODE

####STEP THREE: GET AN ACCESS TOKEN

Exchange this authorization code for an access_token, which will allow you to make requests on behalf of a user. The access_token expires in 30 days. The grant_type may be authorization_code or refresh_token.

curl -F 'client_secret=YOUR_CLIENT_SECRET' \
    -F 'client_id=YOUR_CLIENT_ID' \
    -F 'grant_type=authorization_code' \
    -F 'redirect_uri=YOUR_REDIRECT_URI' \
    -F 'code=AUTHORIZATION_CODE' \
    https://login.uber.com/oauth/token

####RESPONSE

{
    "access_token": "EE1IDxytP04tJ767GbjH7ED9PpGmYvL",
    "token_type": "Bearer",
    "expires_in": 2592000,
    "refresh_token": "Zx8fJ8qdSRRseIVlsGgtgQ4wnZBehr",
    "scope": "profile history"
}

####STEP FOUR: USE BEARER TOKEN

Pass the access_token returned in the response in the Authorization header with the type Bearer to make requests on behalf of a user.

curl -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' 'https://api.uber.com/v1/products?latitude=37.7759792&longitude=-122.41823'
```http
####STEP FIVE: REFRESHING TOKENS

When the user's access_token has expired, you may obtain a fresh access_token by exchanging the refresh_token that is associated with the access_token.
```http
curl -F 'client_secret=YOUR_CLIENT_SECRET' \
    -F 'client_id=YOUR_CLIENT_ID' \
    -F 'grant_type=refresh_token' \
    -F 'redirect_uri=YOUR_REDIRECT_URI' \
    -F 'refresh_token=REFRESH_TOKEN' \
    https://login.uber.com/oauth/token

###REFERENCE

####APPLICATION PARAMETERS

After you've registered your developer account and application, you'll able to access the following parameters for your application on the Applications page.

Parameter Description
client_id A 32 character string (public)
client_secret A 40 character string. DO NOT SHARE. This should not be available on any public facing server or web site. If you have been compromised or shared this token accidentally please reset your client_secret via our web interface. This will require updating your application to use the newly issued client_secret.
server_token A 40 character string. DO NOT SHARE. This must be used for requests that are not issued on behalf of a User.

####AUTHENTICATION ERRORS

Parameter Description
invalid_request Required parameters were not provided.
invalid_client The client ID or secret provided is invalid.
invalid_grant Valid grant types are authorization_code and refresh_token
invalid_scope The scope parameter provided is not a valid subset of scopes.
server_error The server returned an unknown error.
temporarily_unavailable The endpoint is temporarily unable to respond.
Common Types

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.

CORS

The Uber API supports CORS(CROSS-ORIGIN RESOURCE SHARING) for communicating from Javascript. You will need to set an Origin URI when creating your application to allow for CORS to 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.setRequestHeader("Authorization", "Token YOUR_SERVER_TOKEN");
xhr.open('GET', 'https://api.uber.com/v1/products?latitude=37.7759792&longitude=-122.41823');
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.
400 Malformed request.
401 Unauthorized the request requires user authentication (not logged in).
403 Forbidden. Also used for unauthorized requests such as improper OAuth 2.0 scopes or permissions issues.
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
422 Invalid request. The request body is parse-able however with invalid content.
429 Too Many Requests. Rate limited.
500 Internal Server Error.
Localization

Timezones: As stated above, all timezones will be expressed as a UTC epoch and it is the responsibility of the client to localize.

Currency: Currency will be rendered in the local currency of a given latitude & longitude pair. A fare estimate in San Francisco will be given in dollars, while a fare estimate in Paris will be displayed in euros. We also provide the ISO 4217 currency code for your own conversions.

Translations: Uber API respects an Accept-Language header given by the client for languages for which we support translations. We support Section 14.4 of RFC 2616. We will return a Content-Language response header with the content's localization.

Uber API, Uber’s mobile website and mobile applications support a variety of languages and locales specified via standard Accepts-Language headers. We continue to add more languages as we add more locales. Currently, the following locales are supported:

Code Description
ar_SA Arabic (Saudi Arabia)
de_DE German (Germany)
en_US English (United States)
fr_FR French (France)
it_IT Italian (Italy)
ja_JP Japanese (Japan)
ko_KR Korean (Korea)
ms_MY Malay (Malaysia)
nl_NL Dutch (Netherlands)
pt_BR Portuguese (Brazil)
ru_RU Russian (Russia)
sv_SE Swedish (Sweden)
th_TH Thai (Thailand)
tl_PH Tagalog (Philippines)
zh_CN Chinese (China)
zh_TW Chinese (Taiwan)
Rate Limiting

Rate limiting is implemented on the basis of a specific client's secret token. By default, 1,000 requests per hour can be made per secret token. If you would like to request an increase to your rate limit, please use the Support page to reach out to us with relevant information explaining your specific use case.

HTTP responses will return a 429 status code for any request until the rate limit has dropped below the required threshold.

Furthermore, we will supply X-Rate-Limit-* headers for all requests containing the current state of the secret token’s rate limit.

Header Description
X-Rate-Limit-Limit Total number of requests possible.
X-Rate-Limit-Remaining Number of requests left in the rate limit window.
X-Rate-Limit-Reset Timestamp when the rate limit will reset.
Scopes

During the registration process, you'll be prompted to select the scopes your application needs. You can also edit these preferences or add new scopes at a later time. Users will be asked to grant permission for your application's specific scopes when they authenticate. Here is a list of scopes that you can choose from:

Scope Description
profile Access the basic profile information on a user's Uber account including their first name, email address, and profile picture.
history Pull trip data including the locations, times, and product type of a user's historical pickups and drop-offs.
API Methods
GET /v1/products
GET /v1/estimates/price
GET /v1/estimates/time
GET /v1/promotions
GET /v1.1/history
GET /v1/me
Product types
GET /v1/products

The Products endpoint returns information about the Uber products offered at a given location. The response includes the display name and other details about each product, and lists the products in the proper display order.

Request parameters

latitude
string required

Latitude component of location

Example:
38.98
longitude
string required

Longitude component of location.

Example:
-77.15
access_token
string optional
server_token
string optional
Example:
1cec7aab0117c1b123bbeee5fdb79aef

Responses

200 OK
Body
Object
products
Object
product_id
string
Example:
327f7914-cd12-4f77-9e0c-b27bac580d03
description
string
Example:
The original Uber
display_name
string
Example:
UberBLACK
capacity
number
Example:
4
image
string
Example:
http://...

Examples

GET https://api.uber.com/v1/products?server_token=qgKkN8i08Ev39hLExCrgk26Adr0MFYCIVPkE9z44&latitude=38.98&longitude=-77.15 HTTP/1.1 
Price estimates
GET /v1/estimates/price

The Price Estimates endpoint returns an estimated price range for each product offered at a given location. The price estimate is provided as a formatted string with the full price range and the localized currency symbol.

The response also includes low and high estimates, and the ISO 4217 currency code for situations requiring currency conversion. When surge is active for a particular product, its surge_multiplier will be greater than 1, but the price estimate already factors in this multiplier.

Request parameters

start_latitude
string required

Latitude component of start location.

Example:
38.98
start_longitude
string required

Longitude component of start location

Example:
-77.03
end_latitude
string required

Latitude component of end location.

Example:
39.06
end_longitude
string required

Longitude component of end location.

Example:
-77.01
server_token
string optional
access_token
string optional

Responses

200 OK
Body
Object
prices
Time estimates
GET /v1/estimates/time

The Time Estimates endpoint returns ETAs for all products offered at a given location, with the responses expressed as integers in seconds. We recommend that this endpoint be called every minute to provide the most accurate, up-to-date ETAs.

Request parameters

start_longitude
number required

Latitude component.

Example:
-77.15
start_latitude
number required

Longitude component.

Example:
38.98
customer_uuid
string optional

Unique customer identifier to be used for experience customization.

product_id
string optional

Unique identifier representing a specific product for a given latitude & longitude.

Example:
dee8691c-8b48-4637-b048-300eee72d58d
server_token
string optional
access_token
string optional

Responses

200 OK
Body
Object
times
Object
product_id
string

Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.

Example:
5f41547d-805d-4207-a297-51c571cf2a8c
display_name
string

Display name of product.

Example:
UberBLACK
estimate
number

ETA for the product (in seconds). Always show estimate in minutes.

Example:
410
Promotions
GET /v1/promotions

The Promotions endpoint returns information about the promotion that will be available to a new user based on their activity's location. These promotions do not apply for existing users.

Request parameters

start_latitude
string required

Latitude component.

start_longitude
string required

Longitude component.

customer_uuid
string optional

Unique customer identifier to be used for experience customization.

product_id
string optional

Unique identifier representing a specific product for a given latitude & longitude.

Responses

200 OK
Body
Object
display_text
string

A localized string we recommend to use when offering the promotion to users.

Example:
Free ride up to $30
localized_value
string

The value of the promotion that is available to a user in this location in the local currency.

Example:
$30
type
string

The type of the promo which is either trip_credit or account_credit.

Example:
trip_credit
User Activity (V1.1)
GET /v1.1/history

The User Activity endpoint returns a limited amount of data about a user's lifetime activity with Uber. The response will include pickup and dropoff times, the distance of past requests, and information about which products were requested.

The history array in the response will have a maximum length based on the limit parameter. The response value count may exceed limit, therefore subsequent API requests may be necessary.

This method requires access-token with history_lite scope

Request parameters

offset
number required

Offset the list of returned results by this amount. Default is zero.

Example:
1
limit
number required

Number of items to retrieve. Default is 5, maximum is 50.

Example:
41
access_token
string required

access_token with history_lite scope

Responses

200 OK
Body
Object
offset
number

Position in pagination.

Example:
0
limit
number

Number of items to retrieve (50 max).

Example:
1
count
number

Total number of items available.

Example:
5
history
Object
uuid
string

Unique activity identifier.

Example:
7354db54-cc9b-4961-81f2-0094b8e2d215
request_time
number

Unix timestamp of activity request time.

Example:
1401884467
product_id
string

Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.

Example:
edf5e5eb-6ae6-44af-bec6-5bdcf1e3ed2c
status
string

Status of the activity. Only returns completed for now.

Example:
completed
distance
number

Length of activity in miles.

Example:
0.0279562
start_time
number

Unix timestamp of activity start time.

Example:
1401884646
end_time
number

Unix timestamp of activity end time.

Example:
1401884732
User profile
GET /v1/me

The User Profile endpoint returns information about the Uber user that has authorized with the application. This method can be used only if you got access token with the profile scope

Request parameters

access_token
string optional

profile scope is required

Responses

200 OK
Body
Object
first_name
string
Example:
Uber
last_name
string
Example:
Developer
email
string
Example:
developer@uber.com
picture
string
Example:
https://...
promo_code
string
Example:
teypo
Data Reference
Product

The type of a trip

Object
product_id
string

Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.

Example:
327f7914-cd12-4f77-9e0c-b27bac580d03
description
string

Description of product.

Example:
The original Uber
display_name
string

Display name of product.

Example:
UberBLACK
capacity
number

Capacity of product. For example, 4 people.

Example:
4
image
string

Image URL representing the product.

Example:
http://...
Price
Object
product_id
string

Unique identifier representing a specific product for a given latitude & longitude. For example, uberX in San Francisco will have a different product_id than uberX in Los Angeles.

Example:
08f17084-23fd-4103-aa3e-9b660223934b
currency_code
string

ISO 4217 currency code.

Example:
USD
display_name
string

Display name of product

Example:
UberBLACK
estimate
string

Formatted string of estimate in local currency of the start location. Estimate could be a range, a single number (flat rate) or "Metered" for TAXI.

Example:
$23-29
low_estimate
number

Lower bound of the estimated price.

Example:
23
high_estimate
number

Upper bound of the estimated price.

Example:
29
surge_multiplier
number

Expected surge multiplier. Surge is active if surge_multiplier is greater than 1. Price estimate already factors in the surge multiplier.

Example:
1
duration
number

Expected activity duration (in seconds). Always show duration in minutes.

Example:
640
distance
number

Expected activity distance (in miles).

Example:
5.34
Methods: Price estimates
ErrorModel

Error response data model

Object
message
string

Human readable message which corresponds to the client error.

Example:
Invalid user
code
string

Underscored delimited string.

Example:
invalid
fields
unknown

A hash of field names that have validations. This has a value of an array with member strings that describe the specific validation error.

Example:
"first_name": ["Required"]
temp

sad