Skip to main content

On-demand route optimization and a custom passenger application

SWAT APIs support building custom passenger or driver applications fpr mobile devices along with web applications for operators to manage bookings and passenger data. There are two typical scenarios that are available out of the box with SWAT APIs and components:

  • On demand vehicle sharing (vehicles are moving inside the area in real time and passengers needed to be picked up in realtime, aka on demand, typical use case for car sharing, or bus pooling)
  • Just in time passenger delivery (passenger are prebooked, and then pooled by a certain time and are moved to a single location, typical use case include employee transport)

Additionally, the SWAT APIs optionally encompass more intricate workflow functionalities, including:

  • Estimating a requested booking, incorporating the estimated arrival time of the vehicle and its fare for the passenger
  • Offer-based workflows that empower the passenger to accept or reject a ride offer

Prerequisites

The SWAT team (see for details) typically performs the initial project configuration to ensure high-quality and practical workflows for the client. In addition to a regular setup, an integrator may request SWAT to enable waypoint-based setup of the project, which would restrict passengers from being picked up at arbitrary locations and instead allow pickups and drop-offs to occur only at a predefined set of locations, such as bus stops or other places. THis is achieved by using transit stop objects that can be also retrieved by using API.

To enhance the passenger experience, SWAT APIs support providing walking instructions to transit stops when enabled. When multiple stops are available within a specified proximity, SWAT APIs employ optimization criteria to choose the stop with the shortest walking time for the passenger.

The configuration of operations and the optimization engine is performed at a template level, which is typically configured by the SWAT team.

To facilitate real-time communication between applications and support on-demand services, websockets or webhooks can be utilized.

SWAT APIs also support dynamic driver and passenger registration with the system.

Additionally, if the integrator opts in with the SWAT-provided payment model, the integration can support billing and charging the passenger.

For this workflow to function correctly, the following prerequisites must be met:

  • A project has been configured with the appropriate credentials.
  • (Optionally) A set of transit stops has been assigned to that project.
  • Simulation template and service area geofences have been configured.

Principles and authentication

SWAT APIs support two approaches for building end-customer applications: with an intermediary backend or without. Each approach has its advantages and disadvantages. We recommend that integrators have their own backend, as it allows for finer control over workflows and ensures sensitive data remains within the integrator's system.

Approach with the integrators having their own backend​

Approach with the integrators using no dedicated backend​

Driver application and combinations​

SWAT API's support mixed mode while working with the APIs such as the integrator may choose to build their own Web application, driver and passenger applications, or use those in any combination with SWAT provided driver, passenger or web applications. For example:

Alternatively, for integrators willing to build their own operator management application:

Workflow definition

Depending on the desired outcome, the workflow may vary. The following diagram demonstrates the example comprehensive workflow possible with SWAT APIs:

Comprehensive PA flow

Additionally, a simplified workflow may look like this:

Simplified PA flow

(Optional) Managing transit stops​

Transit stops serve as waypoints for passenger pickup and drop-off. SWAT teams typically configure these stops. However, integrators can retrieve or update information using the following methods:

POST {{base_url}}/api/v2/transitstop api

The consuming application can also request stops that are available in a near proximity:

GET {{base_url}}/api/v2/transitstop/nearest api

(Optional) Setting up simulation template (Service template)​

Simulation template (service template) is used to store all settings for on demand operations. Typically, it is configured by SWAT, if there is a need to configure it or retrieve current settings, the simulation api can be used.

(Optional) Creating, modifying and deleting vehicles​

warning

Vehicles can be created at a simulation (service) template level and at a simulation (service) instance for the day level. When a simulation (service) is over or is deleted, vehicles created directly in a simulation will not be saved and will not be available for the next service. Additionally, if a vehicle has been updated (enabled, disabled, modified) in a simulation instance, the changes will not automatically propagate to the simulation template and therefore will not be applied to the other simulation instances.

Vehicle templates (services) can contain vehicles that are available for each day of operations. To create vehicles, the POST vehicle API can be used. api This API request can be used for vehicle creation either at the template level or service level by setting the appropriate simulation_id that the new vehicle should belong to.

To enable and disable vehicle (for the optimization and booking assignment purposes), a field in_use can be use in vehicle model.

Vehicles also support soft deletion by using is_invalidated flag.

(Optional) Creating drivers​

Drivers are optionally can be created and managed via API requests Created drivers can be linked to a corresponding vehicle using driver field on a vehicle model API. This step is optional and is only needed if SWAT Driver Application is used in a project, otherwise service can be implemented without using assigned drivers.