This tutorial will walk you through the steps of using the Ride Request API in your Java app. The Rides SDK is an easy way to add Uber into your app. In this guide, we’ll be going through the entire process to get a working app with the Rides SDK configured. We will set up and configure the SDK, then walk through an example Ride Request integration.

¶ Adding the SDK

Once you have your app registered on the developer dashboard, you are ready to add it to your project. This will show you how to integrate into a new project, but the steps are the same for an existing app.

dependencies {
    compile 'com.uber.sdk:rides:0.5.2'
}

¶ Finding the SDK

The Rides SDK is open source and hosted on Github.

¶ Create an Uber session with a server token

Once you have created your app, you will be given a server_token, client_id, & client_secret. These will be used to authenticate your application and your users when calling the API.

Endpoints that do not require a user context can be accessed from your application server using your server token.

• GET /products
• GET /estimates/time
• GET /estimates/price

SessionConfiguration config = new SessionConfiguration.Builder()
    .setClientId("<CLIENT_ID>")
    .setServerToken("<SERVER_TOKEN>")
    .build();

ServerTokenSession session = new ServerTokenSession(config);

¶ Get a list of products available

Response<List<Product>> response = service.getProducts(37.79f, -122.39f).execute();
List<Product> products = response.body();
String productId = products.get(0).getProductId();

¶ Get estimates for time and price

Response<TimeEstimatesResponse> response = service.getPickupTimeEstimate(37.79f, -122.39f, productId).execute()

¶ Authorize a user for your application

If you need to access protected resources or modify resources (like getting a user’s ride history or requesting a ride), you will need the user to grant access to your application through the OAuth 2.0 Authorization Code flow. See Uber API docs on authentication.

The Authorization Code flow is a two-step authorization process. The first step is having the user authorize your app and the second involves requesting an OAuth 2.0 access token from Uber. This process is mandatory if you want to take actions on behalf of a user or access their information.

SessionConfiguration config = new SessionConfiguration.Builder()
    .setClientId("<CLIENT_ID>")
    .setClientSecret("<CLIENT_SECRET>")
    .setEnvironment(Environment.SANDBOX)
    .setScopes(Arrays.asList(Scope.PROFILE, Scope.REQUEST))
    .setRedirectUri("<REDIRECT_URI>")
    .build();

OAuth2Credentials credentials = new OAuth2Credentials.Builder()
    .setSessionConfiguration(config)
    .build();

String authorizationUrl = credentials.getAuthorizationUrl();

Replace the values of each placeholder above (<CLIENT_ID>, <CLIENT_SECRET>,<REDIRECT_URI>). You can find these values in your developer dashboard under the your application’s Auth tab. The <REDIRECT_URI> must match the one of the values listed in your dashboard.

Navigate the user to the auth_url where they can grant access to your application. After, they will be redirected to a redirect_url with the format <REDIRECT_URI>?code=UNIQUE_AUTH_CODE. Use this redirect_url to create a session and start UberRidesClient.

Credential credential = credentials.authenticate(authorizationCode, userId);
CredentialsSession session = new CredentialsSession(config, credential)
RidesService service = UberRidesApi.with(session).createService();

Keep credentials information in a secure data store and reuse them to make API calls on behalf of your user. The SDK will handle the token refresh for you automatically when it makes API requests with an UberRidesClient.

¶ Fetch a users profile

Response<UserProfile> response = service.getUserProfile().execute();

¶ Fetch a users activity

Response<UserActivityPage> response = service.getUserActivity().execute();

¶ Ride Requests

The Uber API gives you the ability to Request an Uber Product on behalf of users within your application. Given you know where a user currently is, where they want to go, and which Uber product they want to use to get there, you have all of the tools to make that happen with a few simple API endpoints.

1. In the products endpoint GET /products, products will have the upfront_fare_enabled field set to true.
2. Use the request estimate endpoint POST /requests/estimate with the product_id to get a fare_id. The fare_id can be used to lock down an upfront fare and arrival time for a trip. The fare_id expires after two minutes. If the fare_id is expired or not valid, we return a 422 error.
3. Request the ride using the request endpoint POST /requests with the fare_id returned in the previous step.

¶ The Sandbox

Because of the real-world nature of the Ride Request endpoints, which call active drivers on the system which result in financial transactions on Uber rider accounts, the Uber API provides a sandbox environment for testing. All ride requests made to the sandbox will result in a simulated ride request that can be programmatically updated. To get an understanding on how to set up your environment for making ride requests within the sandbox environment, see the sandbox guide.

¶ Request a Ride

# Get products for location
Response<List<Product>> response = service.getProducts(37.79f, -122.39f).execute();
List<Product> products = response.body();
String productId = products.get(0).getProductId();

# Get upfront fare for product with start/end location
RideRequestParameters rideRequestParameters = new RideRequestParameters.Builder().setPickupCoordinates(37.77f, -122.41f)
       .setProductId(productId)
       .setDropoffCoordinates(37.49f, -122.41f)
       .build();
RideEstimate rideEstimate = service.estimateRide(rideRequestParameters).execute().body();
String fareId = rideEstimate.getFareId();

# Request ride with upfront fare for product with start/end location
RideRequestParameters rideRequestParameters = new RideRequestParameters.Builder().setPickupCoordinates(37.77f, -122.41f)
       .setProductId(productId)
       .setFareId(fareId)
       .setDropoffCoordinates(37.49f, -122.41f)
       .build();
Ride ride = service.requestRide(rideRequestParameters).execute().body();
String rideId = ride.getRideId();

# Request ride details from request_id
Ride ride = service.getRideDetails(rideId).execute().body();

# Cancel a ride
Response<Void> response = service.cancelRide(rideId).execute();

As a Request is ongoing, you will want to display the details of the Request to the user in a way that helps them understand what is happening and give them the information they need to find or get in touch with their driver.

For instance, when a Request is processing it’s probably best to let the user know Uber is attempting to find them a driver. Using a spinner or other loading indicator can convey this message well.

Once a Request status has changed to accepted you can let your user know a vehicle is enroute, what the details of the driver are, and remind them their pickup location. You can even show them the location of the vehicle on a map because the Uber API provides this location information.

If the Request status becomes arriving you probably want to indicate this to the user in a way that gets their attention. And once a Request is in_progress you can provide the information a user might find useful once they are already in the vehicle.

Unfortunately, there are some times when a driver must cancel a Request, and your application should let the user know when this happens. This will be indicated when the status of a Request is returned as driver_canceled. At this point it’s usually helpful to make it easy for a user to re attempt a Request.

Lastly, sometimes a user needs to get in touch with a driver to clarify their location, so please provide an easy way to call or SMS the driver from within your application.

The possible values for status are:

Status	Description
processing	The Request is matching to the most efficient available driver.
no_drivers_available	The Request was unfulfilled because no drivers were available.
accepted	The Request has been accepted by a driver and is “en route” to start location.
arriving	The driver has arrived or will be shortly.
in_progress	The Request is “en route” from the start location to the end location.
driver_canceled	The Request has been canceled by the driver.
rider_canceled	The Request canceled by
completed	Request has been completed by the driver.

Check out our detailed guide for best practices implementing ride requests for your users.