cluster
Group stops into balanced geographic clusters, so a day too large for one optimisation can be optimised one cluster at a time. This is the front half of the recipe for a thousand-stop day: cluster here, then call optimise_routes per cluster, where the routing engine's own matrix decides the visiting order. IMPORTANT — this is STRAIGHT-LINE clustering. Distances are measured between coordinates, not along the road network: no road, river, motorway junction or one-way system is consulted, and two stops either side of an estuary look adjacent. That makes it the right tool for deciding which stops belong TOGETHER and the wrong one for deciding what ORDER to visit them in. The answer carries a basis sentence saying exactly this; show it, so a centroid is never read as a plan. Provide locations ([{id, lat, lon, load?}], ids unique, at most 5,000) and EXACTLY ONE of clusters (how many groups, balanced by stop count), max_cluster_locations or max_cluster_load (a per-cluster ceiling the count is derived from). Optional territories keep a cluster from straddling a round: each is clustered on its own, and so are the stops inside none of them. Optional seed (default 42) drives the seeding — the same request with the same seed always returns the same clusters, on every deployment, so a re-run is a re-run. Returns each cluster's member ids, count, summed load, centroid and territory, plus a balance block naming the constraint applied and whether it had to be relaxed to place every stop: a load ceiling with lumpy loads is a bin-packing problem and may have no solution at the derived count. Requires the MapMap gateway.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| seed | No | Seed for the k-means++ seeding (default 42). The same request with the same seed always returns the same clusters, on every deployment. | |
| clusters | No | How many clusters to produce, balanced by stop count. Give exactly one of `clusters`, `max_cluster_locations` or `max_cluster_load`. | |
| locations | Yes | The stops to group. Ids must be unique; at most 5,000. | |
| territories | No | Optional territories. Given, no cluster straddles one: each territory is clustered on its own, and so are the stops inside none of them. | |
| max_cluster_load | No | At most this much summed `load` per cluster; the cluster count is derived from it. A load ceiling with lumpy loads is a bin-packing problem and may have no solution at the derived count — the response says so rather than pretending. | |
| max_cluster_locations | No | At most this many stops per cluster; the cluster count is derived from it. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| basis | Yes | The method statement: this is STRAIGHT-LINE clustering. Distances are between coordinates, not along roads — two stops either side of an estuary look adjacent. Show it. It is the sentence that stops a centroid being read as a plan. | |
| balance | Yes | The constraint applied, the largest cluster produced, and whether the ceiling had to be relaxed to place every stop. | |
| clusters | Yes | The clusters: each with its `id`, member `locations` (your ids), `count`, summed `load`, `centroid` and the `territory` it belongs to. | |
| parameters | Yes | The seed, the cluster count, the locations seen, how many territories were used, the iterations run and whether it converged. |