This tutorial walks you through the steps to implement the Ride Request API in your app using curl.

Watch for the Try It tags, so you can try the examples as you read along!

We recommend using jq to pipe curl commands through so you can view JSON responses in a clean format. After installing, append | jq '.' to the following cURL examples to get JSON formatted bliss.

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

Try It Execute the following command to see the Uber products available in San Francisco. Replace <TOKEN> with your application’s server token.

Request

curl -H "Authorization: Token <TOKEN>" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: en_US" \
     'https://api.uber.com/v1.2/products?latitude=37.7752315&longitude=-122.418075'

Authorize a rider for your application

To request a ride for a rider or to view a rider’s trip history, the rider needs to authenticate with Uber and authorize your application. Uber’s API complies with the OAuth 2.0 specification, so you can use a library in your favorite language to navigate this flow.

The key things you need to know about OAuth can all be found in your application dashboard in the Auth tab:

client_id
client_secret
redirect_uri
scope (select from the list)

It may help to read our in-depth guide on navigating the OAuth 2.0 flow.

OAuth2.0 Connection

The following endpoints require a rider access token:

GET /me
GET /history
GET /requests

Step 1

Try It Have the rider sign in and authorize your app to access their Uber account.

https://login.uber.com/oauth/v2/authorize?response_type=code&client_id=<CLIENT_ID>&scope=request%20profile%20history&redirect_uri=<REDIRECT_URI>

Step 2

Try It After authorization is complete, the authorization code is exchanged for an access token. This token is required for calling different parts of the API.

Request

curl -F 'client_id=<CLIENT_ID>' \
     -F 'client_secret=<CLIENT_SECRET>' \
     -F 'grant_type=authorization_code' \
     -F 'redirect_uri=<REDIRECT_URI>' \
     -F 'code=<AUTHORIZATION_CODE>' \
     https://login.uber.com/oauth/v2/token

Response

{
   "access_token": "xxx",
   "expires_in": 2592000,
   "token_type": "Bearer",
   "scope": "request profile history all_trips",
   "refresh_token": "xxx"
 }

The access token lets you make requests for the rider. You should store this token securely, so the rider doesn’t have to go through the authorization process again.

Step 3

Now that you have an access token, you can make requests to the Uber API.

Try It The following example calls the GET /me endpoint and returns the rider’s profile information.

Request

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: en_US" \
     'https://api.uber.com/v1.2/me'

Response

{
  "first_name": "Uber",
  "last_name": "Developer",
  "uuid": "f4a416e3-6016-4623-8ec9-d5ee105a6e27",
  "picture": "https://d1w2poirtb3as9.cloudfront.net/f3be498cb0bbf570aa3d.jpeg",
  "rider_id": "8OlTlUG1TyeAQf1JiBZZdkKxuSSOUwu2IkO0Hf9d2HV52Pm25A0NvsbmbnZr85tLVi-s8CckpBK8Eq0Nke4X-no3AcSHfeVh6J5O6LiQt5LsBZDSi4qyVUdSLeYDnTtirw==",
  "email": "uberdevelopers@gmail.com",
  "mobile_verified": true,
  "promo_code": "uberd340ue"
}

Get a list of available products

Try It

Request

curl -H "Authorization: Bearer <ACCESS_TOKEN>" \
     -H "Content-Type: application/json" \
     -H "Accept-Language: en_US" \
     'https://api.uber.com/v1.2/products?latitude=37.7752315&longitude=-122.418075'

Response

{
  "products": [
    {
      "upfront_fare_enabled": true,
      "capacity": 2,
      "product_id": "26546650-e557-4a7b-86e7-6a3942445247",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-uberx.png",
      "cash_enabled": false,
      "shared": true,
      "short_description": "POOL",
      "display_name": "POOL",
      "product_group": "rideshare",
      "description": "Share the ride, split the cost."
    },
    {
      "upfront_fare_enabled": true,
      "capacity": 4,
      "product_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-uberx.png",
      "cash_enabled": false,
      "shared": false,
      "short_description": "uberX",
      "display_name": "uberX",
      "product_group": "uberx",
      "description": "THE LOW-COST UBER"
    },
    {
      "upfront_fare_enabled": true,
      "capacity": 6,
      "product_id": "821415d8-3bd5-4e27-9604-194e4359a449",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-uberxl2.png",
      "cash_enabled": false,
      "shared": false,
      "short_description": "uberXL",
      "display_name": "uberXL",
      "product_group": "uberxl",
      "description": "LOW-COST RIDES FOR LARGE GROUPS"
    },
    {
      "upfront_fare_enabled": true,
      "capacity": 4,
      "product_id": "57c0ff4e-1493-4ef9-a4df-6b961525cf92",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-uberselect.png",
      "cash_enabled": false,
      "shared": false,
      "short_description": "SELECT",
      "display_name": "SELECT",
      "product_group": "uberx",
      "description": "A STEP ABOVE THE EVERY DAY"
    },
    {
      "upfront_fare_enabled": true,
      "capacity": 4,
      "product_id": "d4abaae7-f4d6-4152-91cc-77523e8165a4",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-black.png",
      "cash_enabled": false,
      "shared": false,
      "short_description": "BLACK",
      "display_name": "BLACK",
      "product_group": "uberblack",
      "description": "THE ORIGINAL UBER"
    },
    {
      "upfront_fare_enabled": true,
      "capacity": 6,
      "product_id": "8920cb5e-51a4-4fa4-acdf-dd86c5e18ae0",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-suv.png",
      "cash_enabled": false,
      "shared": false,
      "short_description": "SUV",
      "display_name": "SUV",
      "product_group": "suv",
      "description": "ROOM FOR EVERYONE"
    },
    {
      "upfront_fare_enabled": true,
      "capacity": 4,
      "product_id": "ff5ed8fe-6585-4803-be13-3ca541235de3",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-uberx.png",
      "cash_enabled": false,
      "shared": false,
      "short_description": "ASSIST",
      "display_name": "ASSIST",
      "product_group": "uberx",
      "description": "uberX with extra assistance"
    },
    {
      "upfront_fare_enabled": true,
      "capacity": 4,
      "product_id": "2832a1f5-cfc0-48bb-ab76-7ea7a62060e7",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-wheelchair.png",
      "cash_enabled": false,
      "shared": false,
      "short_description": "WAV",
      "display_name": "WAV",
      "product_group": "uberx",
      "description": "WHEELCHAIR ACCESSIBLE VEHICLES"
    },
    {
      "upfront_fare_enabled": false,
      "capacity": 4,
      "product_id": "3ab64887-4842-4c8e-9780-ccecd3a0391d",
      "image": "http://d1a3f4spazzrp4.cloudfront.net/car-types/mono/mono-taxi.png",
      "cash_enabled": false,
      "shared": false,
      "short_description": "TAXI",
      "display_name": "TAXI",
      "product_group": "taxi",
      "description": "TAXI WITHOUT THE HASSLE"
    }
  ]
}

Ride Requests

Privileged Scope This endpoint requires a privileged scope to be used in production by all Uber riders. You can use this endpoint immediately when authenticated as yourself or any of your 5 registered developers. When you are ready to distribute your application broadly for use by all Uber riders, you may request FULL ACCESS. For more information read about scopes.

These endpoints affect active drivers on the Uber platform. They direct drivers to riders and charge riders for all trip activity.

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.

In the products endpoint GET /products, products have the upfront_fare_enabled field set to true.
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.
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 Estimate

Try It Request a ride estimate for the rider by calling the Requests Estimate endpoint.

Request

curl -X POST -H "Authorization: Bearer <TOKEN>" \
     -H "Content-Type: application/json" -d \
     '{"product_id": "821415d8-3bd5-4e27-9604-194e4359a449", "start_latitude":"37.775232", "start_longitude": "-122.4197513", "end_latitude":"37.7899886", "end_longitude": "-122.4021253","seat_count": "2"}' \
      https://api.uber.com/v1.2/requests/estimate

Response

{
  "fare": {
    "value": 4.32,
    "fare_id": "d67b07577b3c86fd23e483d50c84e5152e550b6abb03cece4fc3793c0c068f2e",
    "expires_at": 1477285210,
    "display": "$4.32",
    "currency_code": "USD"
  },
  "trip": {
    "distance_unit": "mile",
    "duration_estimate": 600,
    "distance_estimate": 2.39
  },
  "pickup_estimate": 4
}

Request a ride

Now that you know the rider’s starting and ending locations, and the product they want, you can request a ride for them.

Try It Request a ride by making a POST request to the Request endpoint.

Request

curl -X POST -H "Authorization: Bearer <TOKEN>" \
     -H "Content-Type: application/json" -d \
     '{"product_id": "821415d8-3bd5-4e27-9604-194e4359a449", "start_latitude":"37.775232", "start_longitude": "-122.4197513", "end_latitude":"37.7899886", "end_longitude": "-122.4021253", "seat_count": "2", "fare_id":"d67b07577b3c86fd23e483d50c84e5152e550b6abb03cece4fc3793c0c068f2e"}' \
      https://api.uber.com/v1.2/requests

There are three possible responses for this request:

202 Accepted - Your request is being processed.
409 Conflict - An error occurred, possibly because no drivers are available.
422 Unprocessable Entity - An error occurred, most likely due to an issue with the rider’s Uber account.

In most cases, if a valid product, start location, and end location are provided, a 202 Accepted response is returned.

Response

Status-code 202 Accepted

{
  "status": "processing",
  "product_id": "821415d8-3bd5-4e27-9604-194e4359a449",
  "destination": {
    "latitude": 37.7899886,
    "longitude": -122.4021253
  },
  "driver": null,
  "pickup": {
    "latitude": 37.775232,
    "longitude": -122.4197513
  },
  "request_id": "0aec0061-1e20-4239-a0b7-78328e9afec8",
  "eta": null,
  "location": null,
  "vehicle": null,
  "shared": false
}

Get trip status

Requests can go through multiple states during a trip. States are provided in the status attribute returned by the Request endpoint.

Try It Get the request details for a ride.

Request

curl -H 'Authorization: Bearer <TOKEN>' \
'https://api.uber.com/v1.2/requests/current'

Response

Status-Code: 200 OK

{
  "product_id": "17cb78a7-b672-4d34-a288-a6c6e44d5315",
  "request_id": "a1111c8c-c720-46c3-8534-2fcdd730040d",
  "status": "accepted",
  "surge_multiplier": 1.0,
  "shared": true,
  "driver": {
    "phone_number": "(415)555-1212",
    "sms_number": "(415)555-1212",
    "rating": 5,
    "picture_url": "https:\/\/d1w2poirtb3as9.cloudfront.net\/img.jpeg",
    "name": "Bob"
  },
  "vehicle": {
    "make": "Bugatti",
    "model": "Veyron",
    "license_plate": "I<3Uber",
    "picture_url": "https:\/\/d1w2poirtb3as9.cloudfront.net\/car.jpeg"
  },
  "location": {
    "latitude": 37.3382129093,
    "longitude": -121.8863287568,
    "bearing": 328
  },
  "pickup": {
    "latitude": 37.3303463,
    "longitude": -121.8890484,
    "eta": 5
  },
  "destination": {
    "latitude": 37.6213129,
    "longitude": -122.3789554,
    "eta": 19
  },
  "waypoints": [
    {
       "rider_id":null,
       "latitude":37.77508531,
       "type":"pickup",
       "longitude":-122.3976683872
    },
    {
       "rider_id":null,
       "latitude":37.773133,
       "type":"dropoff",
       "longitude":-122.415069
    },
    {
       "rider_id":"8KwsIO_YG6Y2jijSMf",
       "latitude":37.7752423,
       "type":"dropoff",
       "longitude":-122.4175658
    }
  ],
  "riders": [
    {
       "rider_id":"8KwsIO_YG6Y2jijSMf",
       "first_name":"Alec",
       "me": true
    },
    {
       "rider_id":null,
       "first_name":"Kevin",
       "me": false
    }
  ]
}

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.

Congratulations! You finished the Ride Requests tutorial and can request rides!