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.

¶ Health Sandbox API Overview

The Sandbox API provides a way to test the endpoints and user flows without actually requesting a real trip.

All requests made to the Sandbox environment are ephemeral.

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

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

¶ Mocking trips

¶ Getting started

¶ 1. Create a run

First call /v1/health/sandbox/run to create a run.

This will setup temporary test riders and drivers that will 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/health/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 driver_locations array is required to show that a driver needs to be created.

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/health/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 used 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/health/trips/estimates if you plan on using up front pricing (fare_id)
/v1/health/trips

¶ 3. Obtain the test `driver_ids`

After waiting a minute, call v1/health/sandbox/run/:run_id.

This will return the test driver_ids that you will need for /v1/health/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 the 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/health/trips/estimates to get a product_id that corresponds to the parent_product_type_id you chose in /v1/health/sandbox/run.

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

If all product_id have "no_cars_available": true, the drivers may have gone offline and you will need to use /v1/health/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/health/trips/estimates response to then pass into /v1/health/trips.

¶ 5. Create a trip requests

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

¶ 6. Change the driver state

Call /v1/health/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/health/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/health/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. Please set the driver state to GO_ONLINE near the pickup location within a minute of the scheduled pickup time.

Flexible trips are similar in that the driver state must 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/health/trips/{trip_id} API.

¶ Available Endpoints

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

Uber

Developers