Route Plan Data API

The Route Plan Data API is a high-performance optimization engine designed to solve complex Vehicle Routing Problems (VRP). It calculates the most efficient sequence of stops for your fleet while strictly adhering to time windows, vehicle capacities, and operational constraints.

Terminology Mapping

In the context of waste management, the generic system entities are mapped to the following domain-specific terms:

System Term	Domain Mapping
`Site`	Sector
`Building`	Route
`Level`	Road
`Area`	Area

Base URL

All requests to the Route Plan Data API should be made to the following endpoint:

POST https://paas-uat.v3nity.com/resource/plan/data/routeplan

Authentication

This API uses API Key authentication. You must include your API key directly in the Authorization header of every request.

Authorization: <YOUR_API_KEY>

⏳

Processing Latency

Optimization is a resource-intensive process. Depending on the complexity of your request, processing typically takes between 30 seconds and 2 minutes. Please ensure your client-side timeout is configured to at least 180 seconds.

Request Headers

Header	Value	Description
`Content-Type`	`application/json`	Required for all POST requests.
`Authorization`	`<API_KEY>`	Your unique API access token.

Request Parameters

The request body must be a JSON object. All coordinates should be provided in decimal degrees (WGS84).

Field	Type	Status	Description
`name`	String	Mandatory	A descriptive name for the optimization run.
`route_date`	String	Mandatory	The target date for the routes (YYYY-MM-DD).
`route_request`	Object	Mandatory	The root container for optimization data.
`allocation_method`	String	Mandatory	Clustering logic: `courts`, `zone`, `balanced`, `greedy`.
`orders[]`	Array	Mandatory	List of orders to be optimized.
`order_id`	String	Mandatory	Unique identifier for the order.
`delivery`	Object	Mandatory	Delivery visit details.
`task_id`	String	Mandatory	Unique identifier for the task.
`postal_code`	String	Optional	6-digit Singapore postal code. Specify this if you want the system to auto populate the geographical coordinates.
`longitude`	Double	Mandatory	WGS84 Longitude. Set to 0.0 if postal code is specified.
`latitude`	Double	Mandatory	WGS84 Latitude. Set to 0.0 if postal code is specified.
`time_window_start`	String	Mandatory	Preferred start time (HH:mm). The customer time preference.
`time_window_end`	String	Mandatory	Preferred end time (HH:mm). The customer time preference.
`duration`	Integer	Mandatory	Service duration in minutes. This translates to the time taken from onsite arrival to departure to next location.
`load_required`	Object	Mandatory	Capacity requirements.
`units`	Double	Mandatory	Load amount. The quantity of items unit of measurement to specify for the delivery.
`resource_preferences`	Array	Mandatory	List of preferred resource IDs. If specified, planning will be strictly assigned to the resources. This is considered as hard constraints.
`resources[]`	Array	Mandatory	List of available vehicle/driver resources.
`resource_id`	String	Mandatory	Unique identifier for the resource. Can be used as vehicle plate number.
`start_location_longitude`	Double	Mandatory	Starting longitude.
`start_location_latitude`	Double	Mandatory	Starting latitude.
`start_time_window_start`	String	Mandatory	Earliest start time (HH:mm).
`start_time_window_end`	String	Mandatory	Latest start time (HH:mm).
`end_location_longitude`	Double	Mandatory	Ending longitude.
`end_location_latitude`	Double	Mandatory	Ending latitude.
`end_time_window_start`	String	Mandatory	Earliest end time (HH:mm).
`end_time_window_end`	String	Mandatory	Latest end time (HH:mm).
`load_capacity`	Object	Mandatory	Vehicle capacity limits.
`units`	Double	Mandatory	Total capacity units.
`schedules`	Array	Mandatory	Pre-defined assignments.

Request Example

{
  "name": "Waste Collection Optimization",
  "route_date": "2026-01-16",
  "route_request": {
    "allocation_method": "greedy",
    "orders": [
      {
        "order_id": "BIN-101",
        "delivery": {
          "task_id": "TASK-5562",
          "postal_code": "642674",
          "longitude": 103.6974,
          "latitude": 1.3448,
          "time_window_start": "10:00",
          "time_window_end": "14:00",
          "duration": 30
        },
        "load_required": { "units": 1.0 },
        "resource_preferences": []
      }
    ],
    "resources": [
      {
        "resource_id": "TRUCK-123",
        "start_location_longitude": 103.9338,
        "start_location_latitude": 1.3736,
        "start_time_window_start": "09:00",
        "start_time_window_end": "10:00",
        "end_location_longitude": 103.9338,
        "end_location_latitude": 1.3736,
        "end_time_window_start": "21:00",
        "end_time_window_end": "22:00",
        "load_capacity": { "units": 12.0 }      
      }
    ],
    "schedules": []
  }
}

cURL Example

curl -X POST https://paas-uat.v3nity.com/resource/plan/data/routeplan \
  -H "Content-Type: application/json" \
  -H "Authorization: <YOUR_API_KEY>" \
  -d '{
    "name": "Waste Collection Optimization",
    "route_date": "2026-01-16",
    "route_request": {
      "allocation_method": "greedy",
      "orders": [...],
      "resources": [...],
      "schedules": []
    }
  }'

Response Schema

The API returns an array of optimized route objects.

Field	Type	Description
`resource_id`	String	The ID of the assigned resource (e.g., Truck).
`total_travel_duration`	Long	Total travel time in seconds.
`total_travel_distance`	Double	Total distance in meters.
`start_time`	String	Actual start time of the route (HH:mm).
`end_time`	String	Actual end time of the route (HH:mm).
`orders[]`	Array	The optimized sequence of visits.
`order_id`	String	The ID of the order (e.g., Bin ID).
`task_id`	String	The ID of the task.
`is_pickup`	Boolean	Indicates if the visit is a pickup.
`arrival_time`	String	Estimated arrival time (HH:mm).
`transitions[]`	Array	Travel metrics between stops.
`travel_duration`	Long	Duration in seconds.
`travel_distance`	Double	Distance in meters.
`polyline_id`	String	UUID for the route geometry in the database.

Response Example

[
  {
    "resource_id": "TRUCK-123",
    "total_travel_duration": 39600,
    "total_travel_distance": 46620.0,
    "start_time": "10:00",
    "end_time": "21:00",
    "orders": [
      {
        "order_id": "BIN-101",
        "task_id": "TASK-5562",
        "is_pickup": false,
        "arrival_time": "11:00"
      }
    ],
    "transitions": [
      {
        "travel_duration": 3600,
        "travel_distance": 14617.0
      },
      {
        "travel_duration": 1782,
        "travel_distance": 6017.0
      }
    ],
    "polyline_id": "d3d2d101-a95c-4474-acf8-a391a88ad1d0"
  }
]

Status Codes

Code	Description
200 OK	Request processed successfully.
400 Bad Request	Invalid payload or missing mandatory fields.
401 Unauthorized	Missing or invalid API key.
500 Internal Server Error	An unexpected error occurred on the server.