Bestmile

Not displayed (see CSS customizations)

Not displayed (see CSS customizations)

On-Demand Travel API

Introduction

Bestmile offers an API for software provider to handle traveler demands in the scope of on-demand services. The API also offers fleet monitoring functionalities. You can explore the API endpoints on the API reference page.

Swagger API Specification available for partners

On request, we can provide a Swagger 2.0 RESTful API Documentation Specification file. If you are interested, send us an e-mail at developersupport@bestmile.com.

Access to Bestmile Travel API is restricted

You need an API key to access Bestmile's API. Your private key will be provided to you by Bestmile. You can request an API key here.

The API key has to be included with every call to authenticate the requests. The only exceptions are the OPTION calls used for CORS, for which authentication is not mandatory.
The key is passed plain inside the apikey header of the HTTP request.

Bookings

A booking is a request of one or multiple travelers for a transportation service from an origin location to a destination location.

A booking consists of several fields:

Field Name
Example Value
Description

userID

"ac48d782-f9c4-11e6-bc64-92361f002671"

User who makes the booking.

siteID

"239cbcfc-78c6-11e6-8b77-86f30ca893d3"

Site where the on-demand service is located.

desiredPickupTime

"2016-09-12T08:59:49.809Z"

(Pre-booking only) If you set this field, it will create a pre-booking (booking made in advance). The value defines the desired pick-up time. Feasibility of the booking is answered in a few seconds following the booking creation, as for instant bookings.

itinerary

[
  {
    "start": {
      "position": {
        "srid": 3857,
        "coordinate": [1870113.35609, 597840.62631]
      },
      "stationID": 1, //optional
      "eta": "2016-09-12T08:59:49.809Z"
    },
    "end": { ... }
  }
]

Chronologically ordered list of trips used to fulfill the booking, with given start and end locations. For on-demand services, the list contains only one element. Start and end locations must be described using a station ID or with LatLong coordinates. The trip data contains the ETA (estimated time of arrival) at pick-up and dropoff locations.

seatCount

1

Number of seats requested.

status

"wait"

Current status of the booking. See below for the complete status list.

vehicleID

"ac48d782-f9c4-11e6-bc64-92361f002671"

Identifier of the vehicle that will be used for the booking.

createdAt

"2016-09-12T08:59:49.809Z"

Creation date and time.

timestamp

"2016-09-12T08:59:49.809Z"

Last update date and time.

Booking statuses

Status
Description

wait

The booking is queuing and has not been attributed to a vehicle's mission yet. No ETA available at this time.

vehicleassigned

The booking has been assigned to a vehicle and the vehicle is coming for pick-up. ETAs to pickup and drop-off locations are available.

arrived

The vehicle has arrived to the pick-up point and is waiting for departure.

inprogress

The vehicle is "en route" from the pick-up location to the drop-off location with the passengers.

arrivedatdestination

The vehicle has arrived to the dropoff point and is waiting for passenger to alight.

done

Booking has been completed and passenger(s) have been dropped off.

novehicleavailable

The booking was unfulfilled because no vehicle was available.

travelercanceled

The booking has been canceled by the traveler.

servicecanceled

The booking canceled by the service.

Booking creation

By POSTing Bookings description (see below) to the /v1/travel/users/:userID/bookings endpoint, you will create the bookings.

Estimated time of arrival to pickup and drop-off locations

Once a vehicle has been assigned to the booking, you will find the relevant ETAs in the itinerary part of the booking description:

  • ETA to pickup: itinerary[0].start.eta
  • ETA to drop-off: itinerary[0].end.eta
{
  "bookingID": "420b24d0-399f-11e8-baec-7a6cf22af4d6",
  "createdAt": "2018-04-06T13:34:40.541Z",
  "timestamp": "2018-04-06T13:34:40.541Z",
  "userID": "ac48d782-f9c4-11e6-bc64-92361f002671",
  "siteID": "239cbcfc-78c6-11e6-8b77-86f30ca893d3",
  "desiredPickupTime": "2018-04-06T16:34:40.541Z", // optional
  "seatCount": 1,
  "status": "vehicleassigned",
  "itinerary": [
    {
      "start": {
        "position": {
          "srid": 4326,
          "coordinate": [46.517518, 6.562985]
        },
        "eta": "2016-09-12T08:59:49.809Z"
      },
      "end": {
        "position": {
          "srid": 4326,
          "coordinate": [46.520504, 6.568416]
        },
        "eta": "2016-09-12T09:11:34.007Z"
      },
      "siteID": "19d80f6a-b1fe-4455-aa9c-193186bec620",
      "domainID": 0
    }
  ]
}
{
  "bookingID": "aecef730-39a0-11e8-b50f-7a6cf22af4d6",
  "createdAt": "2018-04-06T13:44:52.515Z",
  "timestamp": "2018-04-06T13:44:52.515Z",
  "userID": "ac48d782-f9c4-11e6-bc64-92361f002671",
  "siteID": "40cd2510-876f-4a2f-b7ae-7d8861217118",
  "desiredPickupTime": "2018-04-06T16:34:40.541Z", // optional
  "seatCount": 1,
  "status": "vehicleassigned",
  "itinerary": [
    {
      "start": {
        "position": {
          "srid": 4326,
          "coordinate": [ 37.3935451189, -122.08604694 ]
        },
        "stationID": 1,
        "eta": "2016-09-12T08:59:49.809Z"
      },
      "end": {
        "position": {
          "srid": 4326,
          "coordinate": [ 37.3881527127, -122.0885505351 ]
        },
        "stationID": 2,
        "eta": "2016-09-12T09:11:34.007Z"
      },
      "siteID": "40cd2510-876f-4a2f-b7ae-7d8861217118",
      "domainID": 0
    }
  ]
}

Booking cancellation

There are several ways to have a booking canceled:

  1. No vehicle available: Bestmile platform did not find any vehicle that could handle the booking.
  2. Traveler point of view: By sending a DELETE request to /travel/users/:userID/bookings/:bookingID, the booking status gets updated with TravelerCanceled.
  3. Operator point of view: By sending a DELETE request to /travel/sites/:siteID/bookings/:bookingID, the booking status gets updated with OperatorCanceled.
  4. During a failed booking rematching: When a rematch is triggered from Bestmile Operator Dashboard, there may be no other vehicle available. The booking status changes first to OperatorChangedVehicle and then to NoVehicleAvailable.
  5. Vehicle point of view: When the passenger doesn't show up at the pickup location, the vehicle may send MISSION_COMPLETE with PICKUP_STATUS set to PICKUP_NOSHOW.
  6. Bestmile Platform cancels: It may happen, due to some errors, that Bestmile Platform would cancel the booking.

Whenever a booking is cancelled, the Driver/Vehicle should receive either a new mission to the next destination planned (if several bookings were in the queue for this vehicle and the first one should be sent immediately) or to the nearest charging station (if it exists), or will just receive a MISSION_CANCEL with the cancelled booking IDs if the first two do not apply.

Travel API endpoints overview

Note: in all endpoints below, the parts beginning with a colon (:) are UUIDs that need to be replaced with the desired resource identifier.

Bookings endpoints

Full API reference documentation

The full API reference documentation is available on an interactive interface with code samples on the API Reference page.

Description
Endpoint

Make a booking

POST /travel/users/:userID/bookings

Make a pre-booking (booking in advance)

POST /travel/users/:userID/bookings
(with desiredPickupTime field set)

List all the bookings of a user

GET /travel/users/:userID/bookings

List all bookings on a site

GET /travel/sites/:siteID/bookings

Get a booking's details (for user)

GET /travel/users/:userID/bookings/:bookingID

Get a booking's details (for site admin)

GET /travel/sites/:siteID/bookings/:bookingID

Cancel a booking (for user)

DELETE /travel/users/:userID/bookings/:bookingID

Cancel a booking (for site admin)

DELETE /travel/sites/:siteID/bookings/:bookingID


What's Next

Vehicles API