Booking API

The Bestmile orchestration platform handles the demand side of an on-demand, reservation-based service through the Booking API

Requesting a quote

A quote represents an offer that the Bestmile platform returns to a client. The client asks for quotes when he wants to see the different transportation service offers from an origin to a destination location.

If the client is satisfied with one of the provided quotes, he can select it and make a booking from it.

A quote is not a reservation yet - it represents the possible services to the transportation problem provided by the user, with the most accurate estimates that the Bestmile orchestration platform can provide.

Lets request a quote:

   curl --location --request POST 'https://api.sandbox.bestmile.com/booking/v5/quotes' \
   --header 'Content-Type: application/json' \
   --header 'apikey: <apikey provided by Bestmile>' \
   --data-raw '{
       "origin": {
           "location": {
               "lat": 93643733.54825944,
               "lon": 69174811.62391126
           },
           "address": "tempor",
           "label": "sunt aliquip minim velit"
       },
       "destination": {
           "location": {
               "lat": -68700752.29210624,
               "lon": -9253413.49126336
           },
           "address": "sit nostrud",
           "label": "ut officia labore"
       },
       "numberOfTravelers": "<integer>",
       "desiredJourneyStartTime": "<dateTime>",
       "maximumWalkingDistance": "<double>",
       "maximumJourneyStartTimeDeviation": "<duration>",
       "serviceOptions": [
           {
               "id": "<uuid>",
               "origin": {
                   "stopID": "<uuid>"
               },
               "destination": {
                   "stopID": "<uuid>"
               }
           },
           {
               "id": "<uuid>",
               "origin": {
                   "stopID": "<uuid>"
               },
               "destination": {
                   "stopID": "<uuid>"
               }
           }
       ]
   }'

Creating a Booking from a quote

A booking is created as the result of the traveler selecting a Quote, and creating the booking. The booking is the reservation itself, holding the metadata linked to the traveler and the context of the reservation.

   curl --location --request POST 'https://api.sandbox.bestmile.com/booking/v5/bookings' \
   --header 'Content-Type: application/json' \
   --header 'apikey: <apikey provided by Bestmile>' \
   --data-raw '{
       "quoteID": "<uuid from the quote requested previously> ",
       "traveler": {
           "id": "<an ID representing the traveler>",
           "firstName": "proident mollit in",
           "lastName": "sed voluptate incididunt",
           "phoneNumber": "dolore c",
           "email": "aliqua commodo veniam ullamco"
       },
       "source": "<string>",
       "paymentMethods": [
           "<string>",
           "<string>"
       ],
       "customProperties": {},
       "bookerProfile": {},
       "billToParty": {}
   }'

Booking statuses and lifecycle

graph LR A[Created] --> B(Accepted) B --> C[Completed] B --> F[Canceled] A --> E[Rejected] A --> F A --> D[Error] B --> D
Status Description
Created Booking is created in the system. The resulting ride(s) will be processed.
Accepted The booking is accepted by the system (valid), and the ride is most likely matched to a vehicle
Completed The booking and its rides completed their lifecycle
Rejected The booking could not be accepted by the system
Canceled Booking was canceled (the source is most likely attached)
Error Something unexpected happened

Ride Statuses and lifecycle

A ride represents the act of traveling in a vehicle from one location to another location.

graph TB A[Matching] -->B(Scheduled) B --> C(ApproachingPickup) C -->D(WaitingForBoarding) D -->E(Boarding) E -->F(WaitingForDeparture) F --> G(Traveling) G --> H(WaitingForAlighting) H --> I(Alighting) I --> J(PassengerDroppedOff) J --> L(Completed) D --> |NoShow|L
Status Description
Matching The orchestration platform is searching for an available resource that can fulfill the demand
Rejected No availability found for the booking respecting the service constrains.
Scheduled The ride is scheduled. At this stage, the physical vehicle might not yet be known.
Rescheduling The orchestration platform is searching for a better resource that can fulfill the demand.
ApproachingPickup The vehicles started the mission and the passenger can now be informed as she should get prepared to reach the meeting point (pickup).
WaitingForBoarding, Boarding, WaitingForDeparture These states describe the passenger flow at the pickup location
Traveling The vehicle is transporting the passengers.
WaitingForAlighting, Alighting, PassengersDroppedOff These states describe the passenger flow at the dropoff location.
Completed The ride is completed and the traveler can be charged.
NoShow The traveler did not show up at the pickup location.
2.0.0*