mml-route-planner-lite

A free-tier vehicle routing problem solver for delivery fleets. Plans up to 20 stops per run using a local Clarke-Wright + 2-opt solver. No external API calls. Suitable for small dispatchers, evaluation, and proof-of-concept integrations.

For larger plans or production-grade features, see mml-route-planner.

Installation

npm install mml-route-planner-lite

Requires Node.js 18 or later.

Quick start

import { planRoutes } from "mml-route-planner-lite";

const plan = planRoutes({
  depot: { lat: 50.6856, lng: -120.2835 },
  stops: [
    { id: 1, lat: 50.65, lng: -120.35 },
    { id: 2, lat: 50.71, lng: -120.22 },
    { id: 3, lat: 50.68, lng: -120.20 },
    // up to 20 stops
  ],
  constraints: {
    maxShiftMinutes: 8 * 60,
    maxRangeKm: 400,
    maxStops: 20,
    defaultServiceTimeMin: 10,
  },
  driverCount: 2,
});

for (const route of plan.routes) {
  console.log(`${route.stopIds.length} stops, ${route.distanceKm.toFixed(1)} km`);
}

Submitting more than 20 stops throws:

mml-route-planner-lite: plan exceeds the free-tier limit of 20 stops (25 submitted).
Upgrade to mml-route-planner for unlimited capacity and additional features.

What the free tier includes

• Clarke-Wright savings with 2-opt local search
• Haversine distance matrix (no API calls)
• Multi-driver bin-packing with split-largest / merge-smallest
• Hard time windows (earliest / latest arrival per stop)
• Priority stops and pickup-before-delivery
• Up to 20 stops per plan run
• Duplicate stop-id detection

What requires the full version

• Stops beyond the 20-per-run cap
• Google Directions refinement (real road polylines and accurate ETAs per route)
• Mid-route EV charging via Google Places (New)
• Commercial EV vehicle presets
• Service-time estimator based on weight, size, package count, and address features
• Soft time windows (lateness as a penalty instead of a hard reject)
• Driver breaks (ELD-compliant rest windows)
• Skills and compatibility constraints
• Cost-based objective with fixed, per-km, and per-minute vehicle costs
• Workload balancing
• zod input schema, GeoJSON export, and CLI

API

planRoutes(input)

Synchronous. Returns { routes, unassigned, reasons, totalDistanceKm, totalDurationMin, stops, points }.

| Field | Required | Description | |---|---|---| | depot | yes | { lat, lng } — start and end for every route. | | stops | yes | Array of { id, lat, lng, ... }. Maximum 20. IDs must be unique. | | constraints.maxShiftMinutes | yes | Maximum drive + service minutes per driver. | | constraints.maxRangeKm | yes | Maximum route distance. | | constraints.maxStops | yes | Maximum stops per driver. | | constraints.defaultServiceTimeMin | no | Default 10. | | constraints.shiftStartMin | no | Shift start in minutes from midnight. Default 480 (8 AM). | | driverCount | no | Force K drivers. Omit to use as few as the solver naturally produces. | | matrixOptions.roadFactor | no | Haversine-to-road multiplier. Default 1.3. | | matrixOptions.avgSpeedKmh | no | Default 60. |

Per-stop optional fields: serviceTimeMin, windowEarliestMin, windowLatestMin, priority, label, pickupIdx.

getFreeTierLimit()

Returns the current stop limit (20). Useful for UI that displays "x of 20 stops remaining."

Upgrading

The full version of mml-route-planner removes the 20-stop cap and adds Google Directions refinement, mid-route EV charging, commercial vehicle presets, soft time windows, driver breaks, skills constraints, a cost-based objective, a zod input schema, GeoJSON export, and a command-line interface.

Contact github.com/deepanshh786 for access.

License

MIT. See LICENSE.