Project setup
Project and initial simulation templates are typically configured by the SWAT team, as they require an in-depth understanding of customer operations and can be an involved process.
Sequence diagram
Configuring a project and a simulation
Configure a project by specifying its name, location, and time zone. Optionally, a project can include vehicles with their capacities and selection labels. Projects can also contain other configuration settings that apply at the project level or are used by clients. For example, vehicle definitions can be included in a project but are not used in API-based workflows 
. Instead, clients typically use these definitions for representational purposes. The primary purpose of a project is to store project-wide metadata and establish tenancy for customers or projects. A recommended approach is to create a project for each end customer or customer division.
POST /api/v2/project
{
// Required project settings
// Set coordinates of the project
"lat": 13.7563,
"lon": 100.5018,
"name": "My test project",
"timezone": "Asia/Bangkok"
}
The response will include projectid of the project created, as well as other submitted metadata.
Creating geofences for a project
To ensure the correct map and routing engine settings, the project must have an associated geofence. The geofence should encompass the areas where the service is expected to be used by operations (for example, city boundaries).
Data associated with a project includes:
- Holidays (for simulation creation)
- Users and their access rights
- Operation locations and their groups (also known as consignee master list)
- Passengers for passenger services
See JSON payload
POST /api/v2/geofence
{
"description": "Test geofence",
//Geojson for geofence boundaries
"geometry": {
"features": [
{
"geometry": {
"coordinates": [
[
[
-180,
-90
],
[
180,
-90
],
[
180,
90
],
[
-180,
90
],
[
-180,
-90
]
]
],
"type": "Polygon"
},
"properties": {},
"type": "Feature"
}
],
"type": "FeatureCollection"
},
"name": "Default geofence for project testing",
// Project the geofence will be created for
"project": "/api/v2/project/<project_id>"
}
The response will include the geofence object created.
Creating default simulation
Default simulation
contains configuration settings that will be cloned each time a new simulation is created for a project during operations. In addition, the template contains all data that will be carried over to other simulations created from that template, including:
- Vehicles and their configuration
- Optimization parameters
- Simulation settings
- Mapping and routing settings
- Operations locations
- Predefined routes or bookings
- Simulation processors
- Geofences associated with a simulation are
- Rules for instantiating simulations (for example, selecting a template based on time/date recurrence)
- Bus stops
POST /api/v2/microservices/simulation_template
The response includes the simulation_id created, or the existing simulation if there is one already in the project. Once the default template has been created, it needs to be configured to reflect the operational needs of the end customer. This step needs to be executed for each simulation template, after which the following operational periods (such as days) inherit these settings.
Creating vehicles for the default simulation
The default simulation template will be used to create simulations for each day of operations. Therefore, it can also include a list of vehicles that will be cloned for each simulation. In the example below, a vehicle with minimal configuration is created.
To enable time window constrain for a vehicle (operating hours the vehicle) please set start_time and end_time in the payload. When a vehicle is copied over from simulation template, working hours will be copied over to the new simulation. Repeat this step for each vehicle in the template, or, alternatively, vehicle bulk upload function can be used.
See JSON payload
POST /api/v2/vehicles
{
// Capacity refers to a vehicle's ability to transport goods. It specifies the maximum quantity, in arbitrary units of measurement, that the vehicle can hold.
"capacity": {
"weight": 2000,
"cbcm": 10000
},
"bearing": 0,
"lat": 0,
"lon": 0,
"speed": 0,
"simulation": "/api/v2/simulation/112910",
"in_use": "enabled",
"service_number": "TEST_VEHICLE_NUMBER_1",
"start_time": "2022-11-14T00:00:00.340667+00:00",
"end_time": "2022-11-14T06:00:00.340667+00:00",
"geofence_ids": [],
"driver": null
}
Updating the default simulation template or vehicles attached to that simulation template will not retrospectively change any simulation created prior to this change.
Patching default template for simulation as needed
The simulation template object supports modifying fields and data using a PATCH request. For example:
PATCH https://<base_url>/api/v2/simulation/<simulation_id>
When updating objects, exercise caution, particularly with the data field, as it's an arbitrary JSON that's not associated with any model. Sending requests like the one below will erase all other values in the data property. To add a new value to the data property, retrieve the current value, update or add the required field, then PATCH it with the complete payload (i.e., a merger of the existing value with the new values).
{
"data": {
"messaging_webhook_url" : "https://<webhook_url>",
"messaging_webhook_message_types" : ["<message filter>"]
}
}
All simulations created based on this template would have all properties of the patched simulation copied.