Optimize Cluster

POST 
/optimize/cluster

Optimize Cluster

Request

Query Parameters

synchronous Synchronous

Default value: true

application/json

Body

required

wave_id Wave Idnullable

The id of the wave.

site_name Site Namerequired

The name of the site.

start_points arraynullable

Single or list of starting locations.

end_points arraynullable

Single or list of ending locations.

parameters object

allow_interpolation Allow Interpolation

Default value: false

Allow interpolation of missing input locations

location_regex arraynullable

How a location name should be processed before looking it up in the warehouseAn example could be that locations are stored as 'A1-24-006A', but the last character is irrelevant.In this case, the matching regex would be r'^(A1-[0-9]{2}-[0-9]{3})([A-Z])$'and the replacement regex would be r'\1'.Multiple regexes can be provided. If two or more regexes match, the first match is used.

allow_regex_default Allow Regex Default

Default value: true

If false, a location that does not match any of the provided regexes will be considered invalid.If true, the location will be used as-is if no regex matches.

routing_policy RoutingPolicy

Possible values: [ASIS, OPTIMIZED, AUTOSTORE]

Default value: OPTIMIZED

The routing policy to use when generating the route. Options are: RoutingPolicy.ASIS (do not optimize the route), RoutingPolicy.OPTIMIZED (optimize the route using the default optimization algorithm), RoutingPolicy.AUTOSTORE (use an autostore specific algorithm, this also removes a lot of input restrictions).

asis_routing Asis Routingnullabledeprecated

[DEPRECATED] Whether or not to use the asis routing when "optimizing" the route or cluster. Use "routing_policy" instead. If set, this will override "routing_policy" to ASIS for backward compatibility.

pick_violation_handling PickViolationHandling

Possible values: [IGNORE, REMOVE_PICKS, REMOVE_ORDERS]

Default value: IGNORE

How to handle pick violations. Options are: PickViolationHandling.IGNORE, any pick violation will throw a validation exception. PickViolationHandling.REMOVE_PICKS, any pick violation will be removed from the input. PickViolationHandling.REMOVE_ORDERS, any order with a pick violation will be removed from the input.

max_runtime Max Runtime

Default value: 60

The target runtime for the clustering algorithm in seconds, only relevant if the clustering policy is OPTIMIZED_BALANCED.

clustering_policy ClusteringPolicy

Possible values: [ASIS, OPTIMIZED_MAX, OPTIMIZED_BALANCED, OPTIMIZED_FAST, OPTIMIZED_FULL_CLUSTERS]

Default value: OPTIMIZED_BALANCED

The clustering policy to use when generating the clusters. Options are: ClusteringPolicy.ASIS (do not optimize the clustering), ClusteringPolicy.OPTIMIZED_MAX (optimize the clustering using most expensive clustering algorithm for the best distance), ClusteringPolicy.OPTIMIZED_BALANCED (optimize the clustering using a balanced clustering algorithm), ClusteringPolicy.OPTIMIZED_FAST (optimize the clustering using a faster clustering algorithm), ClusteringPolicy.OPTIMIZED_FULL_CLUSTERS (optimize the clustering emphasizing the cluster fill rate).

custom_stop_condition Custom Stop Conditionnullable

A custom stop condition for the clustering algorithm.

custom_stop_condition_parameters object

The parameters values for the custom stop condition.

property name* any

Default value: [object Object]

The parameters values for the custom stop condition.

max_orders Max Ordersnullable

The maximum number of orders that can be assigned to a single cluster.

max_locations Max Locationsnullable

The maximum number of locations that can be visited in a single cluster.

max_volume Max Volumenullable

The maximum volume that can be transported in a single cluster. (1D packing)

max_weight Max Weightnullable

The maximum weight that can be transported in a single cluster.

asis_clustering Asis Clustering

Default value: false

Whether or not to actually optimize the clustering. If False, the clustering will only be done as-is.

max_clusters Max Clustersnullable

The maximum number of clusters returned by our API. This implies that some picks in the provided input may not be clustered.

extra objectnullable

Extra pass-through data. This is not used by the algorithm, but will be passed to the output.

timestamp date-time

The timestamp of the response.

picks object[]required
Possible values: >= 1
A list of picks that need to be clustered.
Array [
pick_id Pick Idrequired
ID to unique identify this pick
location_id string[]required
The location(s) of the pick in the warehouse.
asis_sequence Asis Sequencenullable
The sequence number of the pick in the as-is route.Required for calculating as-is distances.
priority Prioritynullable
Higher priority picks are picked first.
sku_id Sku Idnullable
The id of the SKU on the location.
quantity Quantitynullable
The quantity of the SKU to pick from the location.
order_id Order Idrequired
For clustering, the order id of the pick.
hu_id Hu Idnullable
The handling unit id of the pick.
hu_type Hu Typenullable
The handling unit type of the pick.
location_id_processed arraynullable
list_id List Idnullable
For clustering, the as-is list/cluster the pick belongs to.Required for calculating as-is clusters.
optim_sequence Optim Sequencenullable
The sequence of the pick in the optimized cluster using the routing policy defined in the cluster parameters. (Only used in the optimized cluster output).
sku_width Sku Widthnullable
For clustering, The width of the SKU.
sku_height Sku Heightnullable
For clustering, The height of the SKU.
sku_depth Sku Depthnullable
For clustering, The depth of the SKU.
sku_weight Sku Weightnullable
For clustering, The weight of the SKU.
]
handling_units arraynullable

A list containing information for every Handling Unit Type

Responses

200

Successful Response

application/json

Schema

Schema

type Type

Default value: CLUSTER

site_name Site Namenullable

The site name of the site.

wave_id Wave Idnullable

The id of the wave.

request_id Request Idnullable

The ObjectId of the corresponding request.

timestamp date-time

The timestamp of the response.

computation_time Computation Time

Time our algorithm spent calculating.

error Errornullable

An error message, if an error occurred.

invalid_picks object[]
Invalid picks that were not included in the output route, because they were not valid.
Array [
pick_id Pick Idrequired
ID to unique identify this pick
location_id string[]required
The location(s) of the pick in the warehouse.
asis_sequence Asis Sequencenullable
The sequence number of the pick in the as-is route.Required for calculating as-is distances.
priority Prioritynullable
Higher priority picks are picked first.
sku_id Sku Idnullable
The id of the SKU on the location.
quantity Quantitynullable
The quantity of the SKU to pick from the location.
order_id Order Idnullable
The order id of the pick.
hu_id Hu Idnullable
The handling unit id of the pick.
hu_type Hu Typenullable
The handling unit type of the pick.
location_id_processed arraynullable
reason InvalidPickReason
Possible values: [Location not found, No matching regex, Order contains invalid pick]
The reason why the pick is invalid.
]
unit Unitnullable

Default value: cm

The unit of the distance values

extra objectnullable

Data passed through from the input.

asis_clusters object[]
The as-is clusters. Only calculated if the provided input picks respects the provided stop conditions
Array [
list_id List Idrequired
The list_id of the cluster. This is assigned by the clustering algorithm in the case of optimal clusters.In the case of as-is clusters, this is the list_id of the as-is cluster.
picks object[]
The picks in the cluster.
Array [
pick_id Pick Idrequired
ID to unique identify this pick
location_id string[]required
The location(s) of the pick in the warehouse.
asis_sequence Asis Sequencenullable
The sequence number of the pick in the as-is route.Required for calculating as-is distances.
priority Prioritynullable
Higher priority picks are picked first.
sku_id Sku Idnullable
The id of the SKU on the location.
quantity Quantitynullable
The quantity of the SKU to pick from the location.
order_id Order Idrequired
For clustering, the order id of the pick.
hu_id Hu Idnullable
The handling unit id of the pick.
hu_type Hu Typenullable
The handling unit type of the pick.
location_id_processed arraynullable
list_id List Idnullable
For clustering, the as-is list/cluster the pick belongs to.Required for calculating as-is clusters.
optim_sequence Optim Sequencenullable
The sequence of the pick in the optimized cluster using the routing policy defined in the cluster parameters. (Only used in the optimized cluster output).
sku_width Sku Widthnullable
For clustering, The width of the SKU.
sku_height Sku Heightnullable
For clustering, The height of the SKU.
sku_depth Sku Depthnullable
For clustering, The depth of the SKU.
sku_weight Sku Weightnullable
For clustering, The weight of the SKU.
]
order_ids string[]
Default value: ``
All the order_ids of the picks in the cluster.
estimated_distance Estimated Distance
The estimated distance of the cluster.
]
asis_respected Asis Respected

Default value: true

Whether the as-is clusters respect the provided stop conditions.

optimal_clusters object[]
The optimal clusters.
Array [
list_id List Idrequired
The list_id of the cluster. This is assigned by the clustering algorithm in the case of optimal clusters.In the case of as-is clusters, this is the list_id of the as-is cluster.
picks object[]
The picks in the cluster.
Array [
pick_id Pick Idrequired
ID to unique identify this pick
location_id string[]required
The location(s) of the pick in the warehouse.
asis_sequence Asis Sequencenullable
The sequence number of the pick in the as-is route.Required for calculating as-is distances.
priority Prioritynullable
Higher priority picks are picked first.
sku_id Sku Idnullable
The id of the SKU on the location.
quantity Quantitynullable
The quantity of the SKU to pick from the location.
order_id Order Idrequired
For clustering, the order id of the pick.
hu_id Hu Idnullable
The handling unit id of the pick.
hu_type Hu Typenullable
The handling unit type of the pick.
location_id_processed arraynullable
list_id List Idnullable
For clustering, the as-is list/cluster the pick belongs to.Required for calculating as-is clusters.
optim_sequence Optim Sequencenullable
The sequence of the pick in the optimized cluster using the routing policy defined in the cluster parameters. (Only used in the optimized cluster output).
sku_width Sku Widthnullable
For clustering, The width of the SKU.
sku_height Sku Heightnullable
For clustering, The height of the SKU.
sku_depth Sku Depthnullable
For clustering, The depth of the SKU.
sku_weight Sku Weightnullable
For clustering, The weight of the SKU.
]
order_ids string[]
Default value: ``
All the order_ids of the picks in the cluster.
estimated_distance Estimated Distance
The estimated distance of the cluster.
]
asis_distance Asis Distancenullablerequired
optimal_distance Optimal Distancerequired

Example (from schema)

{
  "type": "CLUSTER",
  "site_name": "string",
  "wave_id": "string",
  "request_id": "string",
  "timestamp": "2025-08-05T23:45:09.401Z",
  "computation_time": 0,
  "error": "string",
  "invalid_picks": [
    {
      "pick_id": "string",
      "location_id": [
        "string"
      ],
      "asis_sequence": 0,
      "priority": 0,
      "sku_id": "string",
      "quantity": 0,
      "order_id": "string",
      "hu_id": "string",
      "hu_type": "string",
      "location_id_processed": [
        null
      ],
      "reason": "Location not found"
    }
  ],
  "unit": "cm",
  "extra": {},
  "asis_clusters": [
    {
      "list_id": "string",
      "picks": [
        {
          "pick_id": "string",
          "location_id": [
            "string"
          ],
          "asis_sequence": 0,
          "priority": 0,
          "sku_id": "string",
          "quantity": 0,
          "order_id": "string",
          "hu_id": "string",
          "hu_type": "string",
          "location_id_processed": [
            null
          ],
          "list_id": "string",
          "optim_sequence": 0,
          "sku_width": 0,
          "sku_height": 0,
          "sku_depth": 0,
          "sku_weight": 0
        }
      ],
      "order_ids": [
        "string"
      ],
      "estimated_distance": 0
    }
  ],
  "asis_respected": true,
  "optimal_clusters": [
    {
      "list_id": "string",
      "picks": [
        {
          "pick_id": "string",
          "location_id": [
            "string"
          ],
          "asis_sequence": 0,
          "priority": 0,
          "sku_id": "string",
          "quantity": 0,
          "order_id": "string",
          "hu_id": "string",
          "hu_type": "string",
          "location_id_processed": [
            null
          ],
          "list_id": "string",
          "optim_sequence": 0,
          "sku_width": 0,
          "sku_height": 0,
          "sku_depth": 0,
          "sku_weight": 0
        }
      ],
      "order_ids": [
        "string"
      ],
      "estimated_distance": 0
    }
  ],
  "asis_distance": 0,
  "optimal_distance": 0
}

422

Validation Error

application/json

Schema

Schema

detail object[]
Array [
loc object[]required
Array [
anyOf
MOD2
string
integer
]
msg Messagerequired
type Error Typerequired
]

Example (from schema)

{
  "detail": [
    {
      "loc": [
        "string",
        0
      ],
      "msg": "string",
      "type": "string"
    }
  ]
}

Loading...