Uber API

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

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]("method://User Activity (V1.1)) 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

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.|

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.

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');

| 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.|

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 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.|

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.|

sad