Load planning

A load plan packs cargo into spaces: cartons, pallets, a truck's deck. It weighs stacking rules, weight limits and axle loads, and searches for a while to do it well, so it runs in the background like a nest: POST /v1/loads queues it, you poll the job, then read the plan and its exports. Free plans 5 single-stage loads a month; Bench and above plan loads within their monthly pool. The sixth load in a month on Free is refused with 403 (Plans and limits has the answer).

Start a load

curl https://api.nestsolver.com/v1/loads \
  -H "Authorization: Bearer $NESTSOLVER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "unit": "mm",
    "mode": "stacked",
    "stages": "one",
    "target": "fewest",
    "strict": false,
    "cargo": [{ "label": "Carton A", "length": "600", "width": "400", "height": "300", "weight": "12", "quantity": "48", "turning": "upright", "carries": true }],
    "cartons": [],
    "pallets": [],
    "vehicles": [],
    "spaces": [{ "kind": "pallet", "label": "EUR", "length": "1200", "width": "800", "height": "1800", "weight_limit": "1000", "quantity": "" }]
  }'

Field	Meaning
unit	The unit lengths are typed in. Weights follow it: pounds for in, kilograms for mm, cm and m.
mode	stacked for cargo stacked in layers, or free for cargo placed anywhere.
stages	one loads cargo straight into the spaces; three loads cargo into cartons, cartons onto pallets, pallets into vehicles. Three linked stages need the Works plan.
target	fewest spaces, or cost. The cost target needs the Works plan.
strict	true fails the job when an item cannot be placed.
cargo[]	The items to load: label, length, width, height, weight, quantity, how each may turn (turning: upright or any), whether it carries weight, most_in_stack, most_above, nesting, keep_apart, and the delivery stop.
spaces[], cartons[], pallets[], vehicles[]	The spaces to load into, each with its kind (carton, pallet or vehicle), label, size, own_weight, weight_limit, quantity (blank for as many as needed), and for a vehicle how it is loaded and its axles. spaces holds a one-stage load's spaces; the three named lists hold a three-stage load's.
deep	true asks for the deep lane once the month's pool is spent. Works plan only.

The exact shapes of each row are in the API reference under LoadRequest, LoadCargo (a row of cargo) and LoadSpace.

Use saved spaces

GET /v1/spaces lists the workspace's saved cartons, pallets and vehicles, each as a space row a load takes, with its id. It is a free call; give unit to have the rows typed in it, or leave it out for the unit picked on the web. Weights are in weight_unit: kilograms, or pounds for inches.

curl "https://api.nestsolver.com/v1/spaces?unit=mm" -H "Authorization: Bearer $NESTSOLVER_KEY"

{
  "unit": "mm",
  "weight_unit": "kg",
  "spaces": [
    { "id": "0192f0c2-1a2b-7c3d-8e4f-5a6b7c8d9e0f", "kind": "pallet", "label": "EUR", "length": "1200", "width": "800", "height": "1800", "own_weight": "25", "weight_limit": "1000" }
  ]
}

Send a row as it is in spaces[] (or cartons[], pallets[], vehicles[]) of a load with the same unit; the load ignores id. Fields left blank on the web are left out. On MCP this is the list_spaces tool.

The answer

202 with the job, as for a nest:

{ "id": "0192f0c5-2e3f-7a4b-8c5d-6e7f8a9b0c1d", "kind": "load", "status": "queued", "links": { "status": "https://api.nestsolver.com/v1/jobs/0192f0c5-2e3f-7a4b-8c5d-6e7f8a9b0c1d" } }

The plan

A finished load's report lists its stages[], each with its metrics, the spaces used and the items placed in them in loading order (LoadItem: its loading step, item_row, position and placed size, weight and delivery stop), the weight on each space and its centre of gravity, and axle loads for a vehicle; and the unit and weight_unit the figures are in.

Row numbers count from 0 among the rows the job kept. A row with no length, width or height is blank and dropped before planning, so a space's space_row and an item's item_row (in spaces[] and in unplaced[]) can be lower than the row's place in your request body. Leave blank rows out of the body and the numbers match it. In a later linked stage the items are the stage before's cartons or pallets, numbered in that stage's order.

Loading steps

Each space's loading_steps[] is the order to load it so the plan can be built: the last stop's items go in first, then from the far end toward the doors, bottom to top, and never an item before what it rests on. Items of one cargo row loaded together, like one stack or one wall, share a step:

{ "step": 1, "stop": 2, "item_row": 0, "label": "Carton A", "count": 6, "items": [0, 1, 2, 3, 4, 5] }

items are the step's places in the space's items[], from 0, bottom first, and each of those items carries the same step.

Centre of gravity

centre_of_gravity is where the space's loaded cargo balances: x along the length, y across the width and z up, from the space's front-left floor corner, in the request's unit. offset_along and offset_across are its distance from the middle of the floor: positive toward the back (where back doors are) and toward the right. The space's weight is the cargo's total. It is null for an empty space. It is a readout, not a pass or fail.

Not loaded, and why

unplaced[] lists what a stage left out: the item_row, its label, how many (count), the reason (too_big, too_heavy, spaces_used_up or no_spot), why in plain words, and fix, the nearest fix with the numbers that show it:

{ "item_row": 2, "label": "Crate", "count": 2, "reason": "too_big", "why": "Too big for every space.", "fix": "2600 mm long; the longest space is 2400 mm. Add a longer space.", "over": { "by": "length", "needed": 2600, "most": 2400 } }

over is set when one side or the weight is to blame: by names it (length, width or height for upright items; longest_side, middle_side or shortest_side for items that may turn any way; or weight), needed is what the item needs and most is the most any space gives, in the request's unit or the weight unit. It is null otherwise.

Exports: the print packet (each stage's not-loaded list, each space drawn with its centre of gravity, and step sheets per stop showing the load as it stands after each step), CSV and Excel (every item with its loading step and stop, each space's centre of gravity and axle loads, and what didn't fit with why and the fix), and on the Works plan pallet labels whose codes open the pallet on the portal. Exports has the formats.

What load planning is not

It is not a transport management system. It plans what goes where and in which order; it books no carriers and routes no trucks.