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