Trip#
Trip#
A Trip is the transportation of Rider(s) in a vehicle, from an origin to a destination. A Trip is ordered by a Customer, and it happens within a Service Area and within Service Hours.
A Trip can be:
cancelled by Customer or by Integrator
State#
At any point in time, a Trip is in a specific state. A Trip transitions between states depending on many factors. This is what we call the lifecycle of a Trip.
The Trip state is modeled as a single state with four main categories:
Ordered
When a Trip is ordered, it is instantiated in the system with state Ordered.
InFulfillment
When a Trip is expected to take place, it transitions to InFulfillment. This state transitions through different phases, depending on the type of vehicle that fulfills the Trip.
Trips served by vehicles that require authentication via the BoardingAuthenticationService transition through four phases:
Accepted: The Trip has been accepted by the system and is scheduled to take place.ReadyForBoardingAuthentication: The vehicle has reached the pickup stop location and is ready for boarding authentication.BoardingAuthenticationCompleted: The authentication process for boarding the vehicle has been completed.PickedUp: The Rider has been picked up by the vehicle.
Trips served by vehicles that do not require authentication via the BoardingAuthenticationService transition through two phases:
Accepted: The Trip has been accepted by the system and is scheduled to take place.PickedUp: The Rider has been picked up by the vehicle.
Fulfilled
When the Rider is successfully dropped off at the destination, the Trip becomes Fulfilled.
NotFulfilled
If the Trip cannot be completed successfully, it transitions to NotFulfilled with one of the following reasons:
Rejected: The Trip was rejected by the system before fulfillment could begin.Terminated: The Trip was terminated due to an internal service problem during fulfillment.NoShow: The Customer did not show up at the pickup location in time.CancelledAsCustomer: The Trip was cancelled by the Customer.CancelledAsIntegrator: The Trip was cancelled by the Integrator due to technical reasons.
The happy path for a Trip follows: Ordered → InFulfillment (Accepted) → InFulfillment (PickedUp) → Fulfilled.
All these states and transitions are shown in the following diagram:
stateDiagram-v2
direction TB
classDef sad_path fill:#ffe6e6
classDef happy_path fill:#e6ffe6
class Rejected,CancelledAsCustomer,CancelledAsIntegrator,NoShow,Terminated sad_path
class Fulfilled happy_path
[*] --> Ordered
Ordered --> InFulfillment : Trip expected to take place
Ordered --> NotFulfilled : Trip rejected/cancelled
state InFulfillment {
Accepted --> PickedUp : Rider picked up (no boarding authentication)
Accepted --> ReadyForBoardingAuthentication : vehicle arrived and ready for boarding authentication
ReadyForBoardingAuthentication --> BoardingAuthenticationCompleted : boarding authentication completed
BoardingAuthenticationCompleted --> PickedUp : Rider picked up after boarding authentication
Accepted --> [*] : cancelled/no show/terminated
ReadyForBoardingAuthentication --> [*] : cancelled/terminated
BoardingAuthenticationCompleted --> [*] : cancelled/terminated
PickedUp --> [*] : completed/terminated
}
InFulfillment --> Fulfilled : Trip completed successfully
InFulfillment --> NotFulfilled : cancelled/no show/terminated
state NotFulfilled {
Rejected
CancelledAsCustomer
CancelledAsIntegrator
NoShow
Terminated
}
Fulfilled --> [*]
NotFulfilled --> [*]
Trip lifecycle#
Load#
A Load represents a single Rider with all large physical objects that should be transported in the vehicle when taking the Trip. A vehicle is matched based on the specified Load, ensuring it meets all the necessary requirements for transport.
When requesting Offers, a list of Load must be provided in the request.
Each Load can be classified as either an Adult or a Child.
Adult: may include a
Wheelchair.Child: may include a
ChildSeatorWheelchair.
Examples#
Two Adults without the need of a Wheelchair accessible vehicle.
{
...
"load": [
{
"adult":
{
"wheelchair": "WHEELCHAIR_NOT_NEEDED"
}
},
{
"adult":
{
"wheelchair": "WHEELCHAIR_NOT_NEEDED"
}
}
]
}
One Adult that requires a Wheelchair assessible vehicle, one Child that requires a ChildSeat of booster type.
{
...
"load": [
{
"adult":
{
"wheelchair": "WHEELCHAIR_NEEDED"
}
},
{
"child":
{
"child_seat": "CHILD_SEAT_BOOSTER",
"wheelchair": "WHEELCHAIR_NOT_NEEDED"
}
}
]
}
One Adult, one Child that requires a Wheelchair accessible vehicle.
{
...
"load": [
{
"adult":
{
"wheelchair": "WHEELCHAIR_NOT_NEEDED"
}
},
{
"child":
{
"wheelchair": "WHEELCHAIR_NEEDED",
"child_seat": "CHILD_SEAT_NOT_NEEDED"
}
}
]
}
Service Class#
Every Offer and Trip is assigned to a Service Class indicated by the attribute service_class_id in an Offer or Trip. The Service Class defines which type of service is offered to the Customer and has an impact on the following aspects of an Offer and Trip:
comfort level (times, stops),
price,
vehicle.
The Service Classes available to a Customer depend on the Service Areas in which they want to take a Trip. It is up to the Customers to choose a Service Class by ordering a corresponding Offer. The Service Classes available to an Integrator depend on the Service Areas they are assigned to.
Note
To receive more information about the Service Classes and their characteristics, please reach out to your Service Configuration Manager.
Price Parts#
The price parts enable Integrators to display a meaningful price breakdown to Customers. Each price is accompanied by a list of price parts, which can be presented to Customers in applications and on invoices.
All price parts represent gross amounts, including taxes and other regulatory fees.
Note
For more information about the available price parts, please reach out to your Service Configuration Manager.