Uber Developers

Overview

Privileged and Confidential This endpoint design has been confidentially shared with you. It is still under development and is subject to change without notice. Please do not share this document or API endpoint details with anyone who is not authorized to have access. For more information read about scopes.

¶ Guest Rides Sandbox Overview

The Guest Rides Sandbox API provides development endpoints for testing the functionality of an application without making calls to the production Uber platform.

To use the Sandbox, make calls to https://sandbox-api.uber.com.

Environment	URL
Production	https://api.uber.com
Sandbox	https://sandbox-api.uber.com

All requests made to the Sandbox environment are ephemeral.

Please contact support to be whitelisted if you get an “Unauthorized” response when calling the Sandbox API.

The Sandbox environment relies on the concept of “runs” to create interactive test trips and mock driver behavior. A run will create temporary riders and drivers that will disappear after 8 hours.

Look for Try It tags throughout the documentation for sandbox examples.

¶ Available Endpoints

Method	Endpoint	Description
POST	/v1/guests/sandbox/run	Creates a new run to setup interactive sandbox trips.
GET	v1/guests/sandbox/run/:run_id	Retrieves the run’s test `driver_ids` to use in /v1/guests/sandbox/driver-state.
POST	/v1/guests/sandbox/driver-state	Changes the driver state during a run.

¶ Mocking trips

Because mocking a trip requires the use of “Sandbox runs”, it may be difficult to mock a trip using your application code.

Often an independent script or test app is easier to use.

One of the best tools to use is Postman. Uber has a Guest Rides Postman API collection to help you get started. Follow the “Importing and exporting data” guide from Postman to import the collection. Make sure to update the placeholders with your real values, such as <client_id>, <client_secret>, and <request_id>.

This animated gif provides an example of a mock trip being executed using Postman.

¶ Getting started

¶ 1. Create a run

First, call /v1/guests/sandbox/run to create a run.

This will setup test riders and drivers that will temporarily exist for 8 hours.

The run_id will be re-usable as long as you want to make test trips in the same city for the duration of the run.

Ensure that the pickup_location and dropoff_location are in a city that Uber operates in. This can be verified using /v1/guests/trips/estimates.

Driver latitude and longitude are optional fields; if they are empty, the driver will be placed randomly near the pickup location.

Each {} in the driver_locations array is required to show that a driver needs to be created. Example:

curl -X POST \
  -H 'authorization: Bearer REPLACETOKEN' \
  -H 'content-type: application/json' \
  -d '{
      "driver_locations": [{}],
      "pickup_location": {
        "latitude": 40.7517665,
        "longitude": -73.98786252
      },
      "dropoff_location": {
        "latitude": 40.75279,
        "longitude": -74.00465
      },
      "parent_product_type_id": "b8e5c464-5de2-4539-a35a-986d6e58f186"
  }' \
  'https://sandbox-api.uber.com/v1/guests/sandbox/run'

When this call is made, it may take up to a minute for the mock setup to complete.

¶ 2. Obtain the `run_id`

The POST /run call will return a run_id, which will then be needed in the header in subsequent calls. (e.g, -H "x-uber-sandbox-runuuid:4c11a40a-950a-4486-baf4-59858300190b")

The following endpoints will accept this header:

/v1/guests/trips/estimates if you plan on using up front pricing (fare_id)
/v1/guests/trips

¶ 3. Obtain the test `driver_ids`

After waiting one minute, call v1/guests/sandbox/run/:run_id.

This will return the test driver_ids that you will need for /v1/guests/sandbox/driver-state.

If the GET /run call failed, it means that the inputs for POST /run were probably invalid.

The driver is automatically changed to a GO_ONLINE state but will GO_OFFLINE after 5 minutes if there is no driver activity.

¶ 4. Obtain the `product_id`

You will need to query /v1/guests/trips/estimates to get a product_id that corresponds to the parent_product_type_id you chose in /v1/guests/sandbox/run.

Make sure that the product_id does NOT have "no_cars_available": true.

If the product_id shows "no_cars_available": true, then drivers may have gone offline, and you will need to use /v1/guests/sandbox/driver-state to change the driver’s state to GO_ONLINE.

If you want to create a trip with upfront fare enforced, you can also use the fareID in the /v1/guests/trips/estimates response to then pass into /v1/guests/trips.

¶ 5. Create a trip request

Call /v1/guests/trips to create a trip request.

¶ 6. Change the driver state

Call /v1/guests/sandbox/driver-state to change the driver’s state.

In order to complete a trip, the states to call are (ACCEPT, ARRIVED, BEGIN_TRIP, DROPOFF).

The driver can CANCEL after the ACCEPT or ARRIVED state.

¶ 7. Fetch trip details

Call GET /v1/guests/trips/ to fetch details of the trip any time after creation.

¶ 8. Fetch trip receipt

Receipts for test trips are generally available a minute after the trip is complete. Call GET /v1/guests/trips/receipt to fetch the receipt for a trip that you just created.

Note: The receipt webhooks are not available in Sandbox environment at the moment.

¶ Multiple trips

To make multiple subsequent trips in the same city, you can re-use the run_id.

If you want to change the driver’s location between trips, you have to change the driver’s state to GO_OFFLINE and then change the driver’s state to GO_ONLINE with driver_location.

The driver_location should be near the new pickup location in order for the driver to ACCEPT the next trip request.

Then you can request a trip and complete the trip by changing the driver’s state using the same steps as above.

¶ Scheduled and Flexible Trips

If you are making a scheduled trip, the driver may GO_OFFLINE before the trip is dispatched.

Set the driver state to GO_ONLINE near the pickup location within a minute of the scheduled pickup time.

Flexible trips requires that the driver state be set to GO_ONLINE before the passenger redeems the trip via text message.

¶ Uber Reserve and Hourly Trips

The Sandbox environment doesn’t provide full support for simulating Uber Reserve and Hourly Rides.

It is not possible to set the driver state to ACCEPT, and this prevents updating the destination and intermediate stops for these trips using the PUT /v1/guests/trips/{trip_id} API.

Uber

Developers