Units

Choose the units for your job (per kind, and mix systems where needed) and read results back in those same units. This guide covers the units block, the defaults, how mixed systems behave, and the precision you actually get back.

When to use this

  • You want to send dimensions in mm (or in, ft, cm) and weights in kg (or lb, t) instead of the defaults.
  • You're mixing systems (e.g. metric lengths with imperial weights) on one job.
  • You're deciding between metric and imperial input and want to know what that decision costs you in rounding precision.

The units block

A job carries a single, job-level units block that sets the unit per kind, not per value. Every input value is interpreted in these units, and the same block formats all output: the result echoes it, so nothing is ambiguous. A single value never carries its own unit tag.

{
  "units": { "length": "mm", "weight": "kg" },
  "carriers": [ … ],
  "cargo": [ … ]
}

Here every dimension (dimensionX/Y/Z on carriers and cargo) is in millimetres, and every weight (weight on cargo, tareWeight on carriers) is in kilograms.

Defaults

Omit units entirely, or omit any one kind inside it, and that kind's default applies:

Kind Default Accepted Applies to
length m mm, cm, m, in, ft all geometry, placement coordinates and sizes, carrier dimensions
weight kg g, kg, t, lb summary.totalWeight, kpis.loadedWeight, placement weight
volume m3 m3, cm3, l, ft3 kpis.loadedVolume
area m2 m2, cm2, ft2 no value in the response is expressed in this unit
ldm m m no value in the response is expressed in this unit

Each field is independent: it falls back to its own default no matter what the others are set to, so {"length": "mm"} alone leaves weight at kg. An explicit null for a field behaves exactly like omitting it; an empty string is rejected with a 400 rather than falling back to the default.

Note: if you omit units entirely, the defaults are m / kg / m³. Set units explicitly whenever your data is in other units.

Mixing systems

You can mix systems across kinds; what you can't do is mix within a kind (there's one length unit for the whole job, one weight unit, and so on). A perfectly valid block:

{ "units": { "length": "cm", "weight": "lb" } }

Now dimensions are centimetres and weights are pounds. The solver converts internally; you work entirely in the units you chose.

Results echo the units

A JobResult always includes the units block it used, fully populated (including the output-only kinds), so a consumer never has to guess:

{
  "jobId": "01975cba-67b9-7b7c-a2f1-3d29e4a01c44",
  "status": "succeeded",
  "units": { "length": "cm", "weight": "lb", "volume": "m3", "area": "m2", "ldm": "m" },
  "summary": { "carriersUsed": 1, "itemsPlaced": 112, "itemsUnplaced": 0, "totalWeight": 3900.5 },
  "carriers": [
    {
      "externalId": "TRAILER-13.6",
      "instance": 1,
      "category": "container",
      "kpis": { "volumeUtilization": 86.3, "loadedWeight": 3900.5, "loadedVolume": 41.2, "itemCount": 112 }
    }
  ]
}

sizeX/Y/Z, x/y/z and weight on each placement are in the job's length/weight units; kpis.loadedWeight is in weight, kpis.loadedVolume is in volume. Angles (orientationRx/Ry/Rz) are an exception: they are always degrees, with no unit choice.

Output-only kinds: volume, area, ldm

volume, area, and ldm are output-only: there is no place to submit a volume, an area or a loading-metre figure as input. Only volume actually formats something today: it controls the unit of kpis.loadedVolume (e.g. volume: "ft3" reports that KPI in cubic feet). volumeUtilization itself is a plain percentage and carries no unit.

Key fields

Field Where Notes
units.length job mm/cm/m/in/ft. Default m. All geometry, placement positions & sizes.
units.weight job g/kg/t/lb. Default kg.
units.volume job (output) m3/cm3/l/ft3. Default m3. Formats kpis.loadedVolume.
units.area job (output) m2/cm2/ft2. Default m2. Echoed on the result; no response value is expressed in it.
units.ldm job (output) m only. Echoed on the result; no response value is expressed in it.
orientationRx/Ry/Rz result placement Always degrees, no unit choice.

Notes & caveats

  • units is per-kind, not per-value. You can't tag an individual dimension with a unit; the block governs the whole job.
  • No mixing within a kind. One length unit, one weight unit per job. Mixing is only across kinds (cm + lb is fine).
  • Defaults are m / kg / m³ when units is omitted. Set units explicitly when your data is in other units.
  • You can't input a volume, an area or a loading-metre figure. volume/area/ldm only format output; supply dimensions instead.
  • kpis.volumeUtilization is a percentage (0 to 100), not a fraction, and is unit-free.
  • An unsupported unit value (e.g. an unrecognised length slug, or an empty string) returns a 400 naming the field and the accepted values. See Errors & troubleshooting.

Loading-instruction PDFs print lengths in the job's units.length, so a job submitted in in yields a document with lengths in inches. The PDF shows lengths only; no weights or volumes appear on it.