This tutorial walks you through the steps to implement the Ride Request API in your Python app. The Rides SDK is an easy way to add Uber functionality into your app. You’ll set up and configure the SDK, and then work through an example Ride Request integration.

¶ Install the SDK

Once your app is registered on the developer dashboard, you’re ready to install the SDK. To install, run:

pip install uber-rides

The Rides SDK is open source, so you can find it on Github.

¶ Create an Uber session with a server token

Once you’ve created your app, you’ll be given a server_token, client_id, & client_secret. These are used to authenticate your application and the rider when calling the API.

Endpoints that don’t require rider context can be accessed from your application server using your server token.

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

from uber_rides.session import Session
from uber_rides.client import UberRidesClient

session = Session(server_token=<TOKEN>)
client = UberRidesClient(session)

¶ Get a list of available products

response = client.get_products(37.77, -122.41)
products = response.json.get('products')

¶ Get price and time estimates

response = client.get_products(37.77, -122.41)
products = response.json.get('products')

response = client.get_price_estimates(
    start_latitude=37.770,
    start_longitude=-122.411,
    end_latitude=37.791,
    end_longitude=-122.405,
    seat_count=2
)

estimate = response.json.get('prices')

¶ Authorize a rider for your application

To request a ride for a rider or to view a rider’s trip history, riders must grant access to your application through the OAuth 2.0 Authorization Code flow. See the Uber API docs on authentication for more information.

from uber_rides.auth import AuthorizationCodeGrant
auth_flow = AuthorizationCodeGrant(
    <CLIENT_ID>,
    <SCOPES>,
    <CLIENT_SECRET>,
    <REDIRECT_URI>
)
auth_url = auth_flow.get_authorization_url()

Replace the values of each placeholder above (<CLIENT_ID>, <CLIENT_SECRET>,<REDIRECT_URI> and <SCOPES>). 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.

Have riders sign in and use the auth_url to grant access to your application. After authorization is complete, riders are redirected to the redirect_url. The redirect_url uses this format: <REDIRECT_URI>?code=UNIQUE_AUTH_CODE. The redirect_url creates a session and starts the UberRidesClient.

session = auth_flow.get_session(redirect_url)
client = UberRidesClient(session, sandbox_mode=True)
credentials = session.oauth2credential

Make sure to store credentials information in a secure data store so riders don’t need to go through the authorization processes repeatedly. The SDK handles token refreshing automatically when it makes API requests with an UberRidesClient.

¶ Fetch a user’s profile

response = client.get_user_profile()
profile = response.json

first_name = profile.get('first_name')
last_name = profile.get('last_name')
email = profile.get('email')

¶ Fetch a user’s activity

response = client.get_user_activity()
history = response.json

¶ Ride Requests

The Uber API lets you Request an Uber Product for riders. Given you know a rider’s location, where they want to go, and which Uber product they want, you can request a ride for them with a few simple API endpoints.

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

¶ The Sandbox

Because Ride Request endpoints affect drivers and riders on the Uber platform, the Uber API provides a sandbox environment for testing. All ride requests made to the sandbox result in a simulated ride request that can be programmatically updated. To set up your environment for making ride requests within the sandbox environment, see the sandbox guide.

¶ Request a ride

# Get products for a location
response = client.get_products(37.77, -122.41)
products = response.json.get('products')

product_id = products[0].get('product_id')

# Get upfront fare and start/end locations
estimate = client.estimate_ride(
    product_id=product_id,
    start_latitude=37.77,
    start_longitude=-122.41,
    end_latitude=37.79,
    end_longitude=-122.41,
    seat_count=2
)
fare = estimate.json.get('fare')

# Request a ride with upfront fare and start/end locations
response = client.request_ride(
    product_id=product_id,
    start_latitude=37.77,
    start_longitude=-122.41,
    end_latitude=37.79,
    end_longitude=-122.41,
    seat_count=2,
    fare_id=fare['fare_id']
)

request = response.json
request_id = request.get('request_id')

# Request ride details using `request_id`
response = client.get_ride_details(request_id)
ride = response.json

# Cancel a ride
response = client.cancel_ride(request_id)
ride = response.json

While a trip is in process, you may want to display trip details to the rider so they understand what state their trip is in or so they can contact their driver.

For instance, when requests are in the processing state, it’s best to let the rider know Uber is attempting to find a driver. Using a spinner or other loading indicator conveys this message well.

Once the status is changed to accepted, you can let riders know a vehicle is enroute. You can also remind riders of their pickup location, show them their driver’s details, or show the driver’s location on a map.

When the request status changes to arriving, you may want to tell riders in a way that gets their attention.

When the status changes to in_progress, you can provide information that riders might find useful once they’re in the vehicle.

If a driver cancels a request, the status is changed to driver_canceled. You should tell riders if their requests are cancelled so they can request another driver.

Sometimes riders need to contact drivers to clarify pickup locations or vehicle details. You should provide an easy way to call or SMS drivers from within your app.

The possible status values are:

Status	Description
processing	Uber is matching the rider and driver.
no_drivers_available	The request was unfulfilled because no drivers were available.
accepted	The driver accepted the request and is enroute to the start location.
arriving	The driver arrived or will shortly.
in_progress	The trip is in progress from the start location to the end location.
driver_canceled	The driver cancelled the request.
rider_canceled	The rider cancelled the request.
completed	The trip is completed by the driver.

Check out our best practices guide for implementing ride requests.