Skip to main content

Quick start

The Integration API offers extensive access to all features within the SWAT suite of applications, including:

  • SWAT Routes: for route planning, optimization, dispatch, and monitoring.
  • The SWAT Driver App: used by drivers for in-field operations.
  • SWAT Teams: for managing passenger services.
  • The underlying data structures and workflows.

This API is designed for the following primary uses:

  • Integration of the route planning capability into OMS or TMS
  • Building custom Driver and\or Passenger applications
  • Submitting orders and bookings to the SWAT backend
  • Executing plan optimization
  • Monitoring the real-time execution of plans
  • Managing vehicles, drivers, users, and simulations
  • Fine-tuning optimization models
  • Building custom business workflows
  • Building templates to support customer operations

All changes made through this API are reflected in SWAT applications, with data persistently stored in the backend. For applications that do not require data persistence, the Stateless API can be used. However, this alternative may involve a different implementation approach and potentially higher complexity due to its lack of support for operational templating.

When using the SWAT Integration API, SWAT is responsible for managing the data and optimization pipelines, which include tasks like configuring live order insertions, supporting wave planning, managing consignee master, handling proof of deliveries etc. Conversely, with the Stateless API, this responsibility lies with the API consumer.

The API Reference documentation is available in the OpenAPI format.

tip

Please refer to terminology for reference to learn about terms used by SWAT APIs

The data model consists of the following components:

  • Project is created per area, customer, department or else if there is a need to have unique setting to be established across multiple days of operation.

  • Project settings include project wide settings such as project location (latitude and longitude), timezone, and metadata. It way also include optional setting that are used by UI\consumers (such as locale or workflow settings).

  • Vehicle Type Setting (Optional) includes fleet definition for a project. Typically this is used by Web and Mobile consumers willing to retain data at a project level. These settings do not impact system behavior and are used as an optional storage.

  • Simulation template contains all simulation settings needed to create a new simulation

    for a project such as settings, fleet configuration, predefined routes etc. These settings are applied by default on each simulation creation for a project. Multiple templates are supported per project and can be used in recurring situations (i.e. one template for Sundays, another template for Mondays)

  • Simulation processors execute optimization requests within a simulation. A single simulation can utilize multiple processors, each with unique settings and vehicle/booking filters, enabling complex scenarios (e.g., combining static routes with live, on-demand insertions). These processors can be linked to simulation templates, automatically creating processors with pre-defined settings when a new simulation is generated. If a simulation lacks defined processors, a default processor handles any optimization requests.

  • Vehicles includes a list of vehicles and their relevant settings that will be applied to each simulation. This template defines fleet composition available for route optimization.

  • Bookings include orders (or bookings

    ) that represent pickups and dropoffs, including constraints that need to be respected. This is typically coming from the systems like %ERP|erp% or OMSs, but can be created via CVSs or passenger applications (in case of ride sharing services)

  • Geofences includes a list of geofences that can be used as a constraint during optimization session allowing for or prohibiting vehicles to enter the zones. Geofences within one simulation can overlap.

note

Some nested or linked objects may have overlapping properties; in this case properties of the object instance override top level object properties. For example, for vehicle models that don't specify the routing profile, a routing profile from the simulation will be used. So vehicle's routing profile takes precedent over simulation routing profile.

Typical API delivery process​

Project configuration and establishing simulation

templates is typically a demanding task that requires an in-depth understanding of the end customer's operations. This is because there are numerous parameters and configurations that need to be appropriately adjusted for the system to generate operationally feasible and efficient routes. This also includes setting up time-dependent and customer-editable maps, as well as (routing API)[/docs/manuals/routing.md]. While an API consumer can execute these actions through SWAT Integration APIs, we strongly advise that the SWAT team handle the initial configuration, while the API consumer can make the necessary adjustments.

In the diagram below, typical milestones are shown. Although not every step is implemented for each integration project, we aim to provide a smooth experience by dedicating attention to each partner.

Creating simulation from the template​

After creating a project with a simulation

template, new simulations can be easily instantiated based on that template for each day of operations, eliminating the need to configure each simulation from scratch.

For each simulation created using

POST /api/v2/microservices/simulation_template_instance

a new simulation will be populated with default settings from the simulation template object available for a project.

tip

A project may have many simulations with simulation_mode set to template which will be used as a template to instantiate simulations within the project thus saving time and effort.

Once the instance of simulation is created, new bookings

can be uploaded to that simulation. For simplicity, SWAT Integration APi provides capability to provision simulation instance automatically on bookings upload. Please refer our simple integration guide.

People moving data model

The diagram below represents relation between passengers, billing entities and projects to enable processing of bookings for passengers. The model has two types of projects that are linked to the customer's organization:

  • Main Project that contains all data specific to organization
  • Transportation project that contains data about some service and contains objects related to that service

One Organization must have only one main project, and can have multiple Transportation projects.

Data deletion​

Delete bookings -> booking's nodes are deleted
Delete vehicle -> assigned nodes are deleted , but bookings remain in unclear state