Booking (order) data model

Data model representing a booking (or order) in the system. A booking consists of at least two nodes: one for drop-off and one for pickup.

Setting the Time Window

There are three options to specify applicable time windows (for either pickup or drop-off; the following example is for pickup windows) for a booking:

• Set a single time window explicitly through the min_pickup_time and max_pickup_time fields.
• Set multiple time windows in the pickup_time_windows property.
• Infer multiple time windows from a referenced operations location for a pickup via pickup_operations_location.

A booking must have at least one pickup window set with one of these options. If the booking model does not have any time window set, the request to modify or upload the booking will fail.

If time windows are set with min_pickup_time and max_pickup_time or with pickup_time_windows, then pickup_operations_location time windows are ignored.

Note that time windows in pickup_operations_location are nullable fields.

If pickup_operations_location time windows are not set, then min_pickup_time and max_pickup_time or pickup_time_windows are applied following the rules of the pickup_time_windows property.

This logic is often used when fixed time windows are commonly used from the master location (operations locations list), but for operational reasons, those values need to be overridden by setting explicit time windows at the booking level.

Setting Locations

There are three options to specify locations for the booking. In the following example, the pickup location will be used:

• Set latitude and longitude in pickup_location_lat and pickup_location_lon.
• Set an address for automatic geocoding in the data.pickup_address field.
• Use pickup_operations_location with the set coordinates of the location. If Operations location has external_id then booking.pickup_operations_location_external_id and\or booking.dropoff_operations_location_external_id will automatically apply information such as location, timewindows and metada from the related Operations Location. This happens only once on booking creation.

The booking must have at least one location set; if none of the options are used, the booking upload or modification request will fail.

If multiple locations are specified, they are applied in the following priority order (highest priority overrides lower priority):

• Explicitly set latitude and longitude from the pickup_location_lat and pickup_location_lon properties.
• Address for automatic geocoding in the data.pickup_address field.
• pickup_operations_location with the set coordinates of the location.

uidstring

Unique identifier for the booking. It can be an arbitrary string, however we recommend using UUID instead. It has to be unique for a simulation.

pickup_location_namestring

Name of the pickup location. In SWAT Routes, it is mapped to pickup address

pickup_location_latnumber<double>

Latitude of the pickup location.

pickup_location_lonnumber<double>

Longitude of the pickup location.

min_pickup_timestring<date-time>

Earliest possible pickup time.

max_pickup_timestring<date-time>

Latest possible pickup time.

pickup_service_timeinteger

Duration of service at the pickup location (in seconds).

dropoff_location_namestring

Name of the dropoff location. In SWAT routes, it is mapped to drop off address

dropoff_location_latnumber<double>

Latitude of the dropoff location.

dropoff_location_lonnumber<double>

Longitude of the dropoff location.

min_dropoff_timestring<date-time>

Earliest possible dropoff time.

max_dropoff_timestring<date-time>

Latest possible dropoff time.

dropoff_service_timeinteger

Duration of service at the dropoff location (in seconds).

data object

Additional data associated with the booking. If coordinates of the pickup and drop off locations are not known, postal address has to be specispecified in this property.

external_idstring

Aribtrary identifier that can be used for tracking by the consumer

customer_namestring

customer_phonestring

pickup_customer_namestring

Mapped in SWAT Route to name of the pickup customer

dropoff_customer_namestring

Mapped in SWAT Route to name of the dropoff customer

dropoff_addressstring

If geographical coordinates are unknown, the address must be provided here. It will be geocoded automatically.

remarksstring

Remarks for the driver

pickup_addressstring

If geographical coordinates are unknown, the address must be provided here. It will be geocoded automatically.

dropoff_countrystring

Optional pickup country to improve quality of geocoding

dropoff_citystring

Optional pickup city to improve quality of geocoding

pickup_countrystring

Optional drop off country to improve quality of geocoding

pickup_citystring

Optional drop off country to improve quality of geocoding

pickup_postal_codestring

Postal code of the pickup address, can be used for automatic geocoding

dropoff_postal_codestring

Postal code of the dropoff address, can be used for automatic geocoding

dropoff_customer_name2string

Second part for drop off customer name (i.e. last name)

pickup_customer_name2string

Second part of the pickup customer name (i.e. last name)

pickup_customer_phonestring

Phone for pickup location.

dropoff_customer_phonestring

Phone for dropoff location.

vehicle_characteristics object

Required characteristics of the vehicle for this booking.

property name* object

anyOf

number

number

Value of the characteristic, for example:

{
    "manpower": 3
}

Ranged characteristic

minnumber

Minimum value of the characteristic

maxnumber

Maximum value of the characteristic

boolean

boolean

vehicle_labelsobject | nullnullable

Vehicle labels contain constraints, represented as dicts, that may contain string labels or sub-constraints. A constraint is a dict, containing only one entry with keys: "and", "or" or "not". Keys "and" and "or" define the AND or OR logic functions. Values for these keys should be a list of either string labels or dicts, containing sub-constraints. The key "not" defines the NOT logic function. Value for this key can be a single string or single sub-constraint. Example of vehicle labels constraints: '1' AND ('2' OR '3') AND NOT ('4' AND '5') as

{"and": [{"or: ["2", "3"]}, {"not": {"and": ["4", "5"]}}]}

groupsstring[]

Groups that this booking belongs to

geofence_definition_strategy object

oneOf

By Dropoff

By dropoff location. Both pickup and dropoff nodes will be labeled with same geofence Defined by dropoff point

Constant value: by_dropoff

By Pickup

By pickup location. Both pickup and dropoff nodes will be labeled with same geofence Defined by pickup point

Constant value: by_pickup

Independent

Both pickup and dropoff nodes may be labeled with different geofences Defined by corresponding locations

Constant value: independent

Mixed

Works like independent but if geofences are different, then Nodes are labeled with both geofences.

Constant value: mixed

lifo_order_checkboolean

Enables or disables the LIFO order logic for this booking. LIFO logic is a soft constraint that forces pickups and drop-offs to happen in a LIFO sequence relative to the vehicles (the last picked-up order is prioritized for drop-off).

lifo_order_penaltyinteger | nullnullable

Penalty for the broken LIFO order. If not present, the LIFO order is required as lifo_order_check is true

trip_costinteger | nullnullable

Booking-level trip cost parameter

Default value: 0

demand object

Demand associated with the booking.

property name*integer

pickup_operations_locationstring,null<uri-reference>nullable

Reference to a pickup location derived from a static list of Operations Locations

dropoff_operations_locationstring,null<uri-reference>nullable

Reference to a dropoff location derived from a static list of Operations Locations

stateBooking states (string)

Current state of the booking. Supported states include:

• new: The booking has been created but is not yet ready for optimization.
• prepared: The booking has been created with all required nodes and settings and is ready to be optimized. This is the default state for a booking created via the logistics or passenger pipeline.
• queued: The booking is queued for calculation.
• calculation: The booking is being optimized. Once optimization is triggered, the booking can remain in this state for an extended period.
• cancelled_in_calc: The booking has been canceled by the calculation pipeline.
• assigned: The booking has been successfully optimized and has a vehicle assigned to it.
• rejected_by_system: The optimization engine was not able to allocate a vehicle to fulfill the booking.
• enroute: The booking is currently being serviced by the vehicle (a vehicle has completed pickup for the booking).
• sent_offer: In the case of on-demand operations, this indicates that an offer to accept the booking has been sent to the passenger.
• cancelled_by_user: In the case of passenger service, this indicates that a passenger has canceled the booking.
• pooling: In the case of JIT service, this indicates that the booking is awaiting passenger pooling to be completed.
• fail_to_board: Indicates that a vehicle was not able to pick up goods or a passenger failed to board. This usually means the booking is ignored during subsequent calculations.
• fail_to_deliver: Indicates that the booking has been picked up, but the vehicle couldn't deliver the goods or passengers. The booking is not ignored in subsequent calculations since the vehicle still carries the goods or passengers.

Possible values: [new, prepared, queued, calculation, cancelled_in_calc, assigned, rejected_by_system, enroute, completed, sent_offer, cancelled_by_user, pooling, fail_to_board, fail_to deliver, linked]

booking_handoverstring<uri-reference>

Reference the booking handover object if the booking was used to create a new booking through the driver handover process.

air_distancenumber<double>

Calculated air distance between drop off and pick up nodes in a booking

is_invalidatedboolean

Soft deletion flag for the booking. This flag cannot be set by a PATCH or POST request.

Default value: false

service_timeinteger

simulationstring<uri-reference>

URI of the simulation this booking belongs to

max_trip_durationinteger | nullnullable

Constraint limiting allowed maximum trip duration for the booking

min_trip_durationinteger | nullnullable

penaltyinteger

Penalty as a cost function for this booking for not providing an offer during optimization. The higher the bigger the penalty is.

Default value: 10000000

actual_dropoff_timestring | nullnullable

actual_journey_durationstring | nullnullable

actual_pickup_timestring | nullnullable

cancellation_timestring | nullnullable

fail_to_board_timestring | nullnullable

failed_to_deliver_at_tsstring,null<uuid>nullable

group_uidstring | nullnullable

Group UID this booking belongs to

offer_should_be_auto_acceptedboolean | nullnullable

Default value: false

planned_dropoff_timestring,null<date-time>nullable

planned_journey_durationstring | nullnullable

planned_pickup_timestring | nullnullable

projectstring<uri-reference>

Project ID this booking belongs to

requested_atstring<date-time>

sim_tierinteger

user_accepted_offer_atstring | nullnullable

customer_idstring

completed_bystring | nullnullable

created_bystring | nullnullable

group_booking_idinteger | nullnullable

passenger_payment_method_idstring | nullnullable

payment_method_typestring | nullnullable

transfer_typestring

Used to set the operations mode for JIT route optimization. depart_at forces the algorithm to ensure an accurate departure time for the passenger in this booking, while arrive_by ensures an accurate arrival time.

Possible values: [depart_at, arrive_by]

Default value: depart_at

booking_typestring | nullnullable

Default value: customer

fixed_journey_durationstring | nullnullable

fixed_route_typestring | nullnullable

fixed_waiting_timestring | nullnullable

journey_duration_differencestring | nullnullable

odbs_waiting_timestring | nullnullable

public_transit_transportstring | nullnullable

ready_to_board_atstring | nullnullable

requested_ticketsobject

ticketstring | nullnullable

ticketsstring<uri-reference>[]

waiting_time_differencestring | nullnullable

dropoff_stops object

pointsobject[]

pickup_stops object

pointsobject[]

pickup_time_windows object[]

Allows setting multiple time windows for a booking at a pickup location. If both this field and max_pickup_time along with min_pickup_time are set, the resulting set of time windows will be a combination of all time windows. For example, if there is one additional time window set in this field, the resulting time window will have two elements: one from the booking itself and the other from this field. This field can be thought of as an "additional" time window. If time windows are set in this field, as well as with min/max_pickup/dropoff_time, the algorithm will consider all time windows (as a combination of all fields with merging logic for overlapping time windows applied). Set time windows may overlap; however, this may result in less efficient routes.

Array [

open_time_tsstring<date-time>

close_time_tsstring<date-time>

clost_time_ts_dynamicstring<date-time>

]

dropoff_time_windows object[]

Allows setting multiple time windows for a booking at a drop-off location. If both this field and min_dropoff_time along with max_dropoff_time are set, the resulting set of time windows will be a combination of all time windows. For example, if there is one additional time window set in this field, the resulting time window will have two elements: one from the booking itself and the other from this field. Time windows may overlap; however, this may result in less efficient routes. This field can be thought of as an "additional" time window. If time windows are set in this field, as well as with min/max_pickup/dropoff_time, the algorithm will consider all time windows (as a combination of all fields with merging logic for overlapping time windows applied).

Array [

open_time_tsstring<date-time>

close_time_tsstring<date-time>

close_time_ts_dynamicstring<date-time>

]

pickup_postal_codestring

In the case of a Singapore location, this postal code can uniquely identify the address for pickup.

dropoff_postal_codestring

In the case of a Singapore location, this postal code can uniquely identify the address for drop-off.

pickup_operations_location_external_idstring

Instead of using the pickup_operations_location URI, you can conveniently specify the Operations Location for a new booking by providing its external_id. This allows you to use your own identifier, and the system will automatically populate the booking with the corresponding location data during creation.

Important: Once the booking is created, changes to the original Operations Location record will not automatically update the booking details.

dropoff_operations_location_external_idstring

Instead of using the dropoff_operations_location URI, you can conveniently specify the Operations Location for a new booking by providing its external_id. This allows you to use your own identifier, and the system will automatically populate the booking with the corresponding location data during creation.

Important: Once the booking is created, changes to the original Operations Location record will not automatically update the booking details.

has_linked_bookingsboolean

Flag indicating if the booking has any other bookings associated with it.

Default value: false

order_positionstring

Enables prioritization of thie booking during the optimization. first_in_trip means that the booking has to be the first one to drop, last_in_trip means that the bookings has to be the

Possible values: [null, last_in_trip, first_in_trip]

product_kindstring | nullnullable

Describes the type or category of the product associated with the booking (e.g., "AMBIENT"). This field is used to calculate the dynamic service time for the order in case the drop-off location is an operations location.

shipmentstring | nullnullable

If the booking has a shipment model associated with it, this contains a URI link to it.

shipment_external_idstring

If the booking has a shipment model assoviated with it, contains an extenarl_id of the shipment.

failed_to_pay_atstring | nullnullable

Timestamp indicating when payment failed for the booking.

created_atstring<date-time>

Creation timestamp of an object

id object

Identifier of the object

anyOf

integer

integer

Can be integer

uuid

string

Can be UUID

modified_atstring<date-time>

Last modification timestampo of the object

resource_uristring<uri-reference>

URI of the object instance

Booking (order) data model

{
  "uid": "string",
  "pickup_location_name": "string",
  "pickup_location_lat": 0,
  "pickup_location_lon": 0,
  "min_pickup_time": "2024-07-29T15:51:28.071Z",
  "max_pickup_time": "2024-07-29T15:51:28.071Z",
  "pickup_service_time": 0,
  "dropoff_location_name": "string",
  "dropoff_location_lat": 0,
  "dropoff_location_lon": 0,
  "min_dropoff_time": "2024-07-29T15:51:28.071Z",
  "max_dropoff_time": "2024-07-29T15:51:28.071Z",
  "dropoff_service_time": 0,
  "data": {
    "external_id": "string",
    "customer_name": "string",
    "customer_phone": "string",
    "pickup_customer_name": "string",
    "dropoff_customer_name": "string",
    "dropoff_address": "string",
    "remarks": "string",
    "pickup_address": "string",
    "dropoff_country": "string",
    "dropoff_city": "string",
    "pickup_country": "string",
    "pickup_city": "string",
    "pickup_postal_code": "string",
    "dropoff_postal_code": "string",
    "dropoff_customer_name2": "string",
    "pickup_customer_name2": "string",
    "pickup_customer_phone": "string",
    "dropoff_customer_phone": "string"
  },
  "vehicle_characteristics": {},
  "vehicle_labels": "Unknown Type: object,null",
  "groups": [
    "string"
  ],
  "lifo_order_check": true,
  "lifo_order_penalty": 0,
  "trip_cost": 0,
  "demand": {},
  "pickup_operations_location": "string",
  "dropoff_operations_location": "string",
  "state": "new",
  "booking_handover": "string",
  "air_distance": 0,
  "is_invalidated": false,
  "service_time": 0,
  "simulation": "string",
  "max_trip_duration": 0,
  "min_trip_duration": 0,
  "penalty": 10000000,
  "actual_dropoff_time": "string",
  "actual_journey_duration": "string",
  "actual_pickup_time": "string",
  "cancellation_time": "string",
  "fail_to_board_time": "string",
  "failed_to_deliver_at_ts": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "group_uid": "string",
  "offer_should_be_auto_accepted": false,
  "planned_dropoff_time": "2024-07-29T15:51:28.071Z",
  "planned_journey_duration": "string",
  "planned_pickup_time": "string",
  "project": "string",
  "requested_at": "2024-07-29T15:51:28.071Z",
  "sim_tier": 0,
  "user_accepted_offer_at": "string",
  "customer_id": "string",
  "completed_by": "string",
  "created_by": "string",
  "group_booking_id": 0,
  "passenger_payment_method_id": "string",
  "payment_method_type": "string",
  "transfer_type": "depart_at",
  "booking_type": "customer",
  "fixed_journey_duration": "string",
  "fixed_route_type": "string",
  "fixed_waiting_time": "string",
  "journey_duration_difference": "string",
  "odbs_waiting_time": "string",
  "public_transit_transport": "string",
  "ready_to_board_at": "string",
  "requested_tickets": {},
  "ticket": "string",
  "tickets": [
    "string"
  ],
  "waiting_time_difference": "string",
  "dropoff_stops": {
    "points": [
      {}
    ]
  },
  "pickup_stops": {
    "points": [
      {}
    ]
  },
  "pickup_time_windows": [
    {
      "open_time_ts": "2024-07-29T15:51:28.071Z",
      "close_time_ts": "2024-07-29T15:51:28.071Z",
      "clost_time_ts_dynamic": "2024-07-29T15:51:28.071Z"
    }
  ],
  "dropoff_time_windows": [
    {
      "open_time_ts": "2024-07-29T15:51:28.071Z",
      "close_time_ts": "2024-07-29T15:51:28.071Z",
      "close_time_ts_dynamic": "2024-07-29T15:51:28.071Z"
    }
  ],
  "pickup_postal_code": "string",
  "dropoff_postal_code": "string",
  "pickup_operations_location_external_id": "string",
  "dropoff_operations_location_external_id": "string",
  "has_linked_bookings": false,
  "order_position": "null",
  "product_kind": "string",
  "shipment": "string",
  "shipment_external_id": "string",
  "failed_to_pay_at": "string",
  "created_at": "2024-07-29T15:51:28.071Z",
  "id": 0,
  "modified_at": "2024-07-29T15:51:28.071Z",
  "resource_uri": "string"
}