Load Calculator API

  • Version 1.1

Request

The request is made using the POST method at the link with API key in URL query:

The request header must contain:

The Load Calculator API request is generated in JSON format and consists of 5 main sections (articles):

JSON Title
JSON Parameters
Required
Description
options
Object
Y
groups
Array
Y
See Groups
containers
Array
N
autoContainers
Array
Y
images
Object
N
See Images

Options

Precision and weight units and length settings

JSON Title
JSON Parameters
Required
Description
lengthUnits
“m” or “inch”
N
Length units: meters (m) or inches (inch)
weightUnits
“kg” or “ft”
N
Weight units: kilograms (kg) or foot (ft)
lengthAccuracy
Float [0.0001…100]
Y
Length measurement accuracy. All dimensions are rounded to the specified precision. See Length Accuracy

Length Accuracy

How does rounded accuracy work? Sets the step size simplifies object placement.

Allows you to equalize the difference in height, width, length of different boxes.

Example calculations for lengthAccuracy = 4

Example of a box

Box size param
Default
Operation
Result
Length
90
Floor(90 / 4) * 4
88
Width
45.5
Floor(45.5 / 4) * 4
44
Height
32.3
Floor(32.3 / 4) * 4
32

Groups

Groups are an array of JSON objects arranged in a strict order, which is taken into account when stuffing containers. The closer to the beginning of the array the group, the earlier it will be stuffed.

A group can contain a pallet setting for a group.

JSON Title
JSON Parameters
Required
Description
uid
Unique String
N
Unique group identifier, allows you to identify the group in results of loading
pallets
Object
N
Pallet settings for a group. If the field is undefined || null, then the pallets will not be used when loading. See Pallets
items
Array
Y
List of metadata objects to stuff. See Items

Pallets

The quantity of pallets is infinite. You cannot limit the number of pallets. Only one type of pallet can be used per group. If no pallets are specified, the group will be loaded without using pallets.

JSON Title
JSON Parameters
Required
Description
size

length: Number

width: Number

height: Number

Y
Area (volume) of the pallet allowed for loading
weight
Number
Y
Pallet weight excluding cargo
maxWeight
Number
Y
Maximum permissible pallet load
depth
Number
Y
Pallet thickness. Length and width are taken from the size field
stacking

maxHeight

layers

fill

rollPlacement

loadType

order

N
Pallet stacking & stuffing settings. See below

Pallet stacking & stuffing settings

JSON Title
JSON Parameters
Required
Description
maxHeight
Number
N
Maximum pallet stack height
layers
Number [1…N]
N
Quantity of pallets stacked on top of each other
fill
Number [0…1]
N
The minimum stuffing level of the top layer of cargo on a pallet for placing the pallet on top. Indicated in fractions of one, i.e. 80% is 0.8, 90% is 0.9, etc.
rollPlacement
Number 4 or 6
N
Hexagonal or square rolls placement
loadType

“auto”

“wallLength”

“wallWidth”

“floor”

N
Type of loading cargo into a pallet. Auto - automatically. wallLength - along a long wall. wallWidth - along a short wall. Floor - along the floor.
order

“auto”

“volume_asc”

“volume_desc”

“square_asc”

“square_desc”

“mps_asc”

“mps_desc”

“vps_asc”

“vps_desc”

N

Priority of cargo placement order.

You can set volume, floor square, mps (mass per square) or vps (volume per square) in ascending or descending order priority.

Items

List of objects to load. The order of the object in the list does not matter. The algorithm will select objects based on stuffing options, container loading rules, and built-in algorithms.

The system uses 2 main types of supported objects: box and roll.

Box Object

BOX object. Describes the types of loadable objects such as box, big bag, and sacks.

JSON Title
JSON Parameters
Required
Description
uid
Unique String
N
The unique object identifier, allows you to identify the object in the results of loading
attr
Object
N
Any data, it will be copied for objects in the results
size

length: Number

width: Number

height: Number

Y

One box size.

Length*Width*Height

qty
Number
Y
Quantity of boxes, minimum 1. Maximum - 1,000,000.
weight
Number
N
Weight of one box
color
String
N
Box color in #FFFFFF format. If no color is specified, a random color will be used.
stacking

tiltLength

tiltWidth

topweight

layers

maxHeight

N
Stacking and stuffing options. See below

Box Stacking & Stuffing options

JSON Title
JSON Parameters
Required
Description
tiltLength
Boolean
N
Allow tilting the box along the length
tiltWidth
Boolean
N
Allow tilting the box along the width
topWeight
Number
N
Allowed weight on top
layers
Number
N
Allowable quantity of boxes in a vertical stack
maxHeight
Number
N
Maximum stacking height with boxes
Roll Object

ROLL object.

Describes the types of loadable objects such as barrel, pipe, and roll.

JSON Title
JSON Parameters
Required
Description
size

radius: Number

height: Number

Y

One roll size.

Radius*Height

attr
Object
N
Any data, it will be copied for objects in the results
qty
Number
Y
Quantity of rolls, minimum 1. Maximum - 100,000.
weight
Number
N
Weight of one roll
color
String
N
Roll color in #FFFFFF format. If no color is specified, a random color will be used.
stacking

tilt

topweight

layers

maxHeight

N
Stacking and stuffing options. See below

Box Stacking & Stuffing options

JSON Title
JSON Parameters
Required
Description
tilt
Boolean
N
Allow tilt roll
topWeight
Number
N
Allowed weight on top
layers
Number
N
Allowable quantity of boxes in a vertical stack
maxHeight
Number
N
Maximum stacking height with boxes

Containers

In this section, you can set a fixed quantity of containers that fill up earlier than auto containers.

It is also assumed that no containers will be specified. Then only the automatic container will be used.

JSON Title
JSON Parameters
Required
Description
uid
Unique String
N
The unique object identifier allows identifying the object in the results of loading
attr
Object
N
Any data, it will be copied for objects in the results
qty
Number [1…N]
Y
Quantity of such containers > 1 or = 1
spaces
Array [1...3] of Spaces
Y
An array of container spaces. Standard containers have only 1 section, but ULD containers can contain 2 or 3 sections.
loadType

“auto”

“wallLength”

“wallWidth”

“floor”

Y
Type of loading cargo into a container. Auto - automatically. wallLength - along a long wall. wallWidth - along a short wall. Floor - along the floor.
order

“auto”

“volume_asc”

“volume_desc”

“square_asc”

“square_desc”

“mps_asc”

“mps_desc”

“vps_asc”

“vps_desc”

N

Priority of cargo placement order.

You can set volume, floor square, mps (mass per square) or vps (volume per square) in ascending or descending order priority.

groups
Array
N
List of groups allowed for loading into this container. If null or [], then the loading of any cargo is allowed.

Container Space

JSON Title
JSON Parameters
Required
Description
length
Number
Y
Section length
width
Number
Y
Section width
height
Number
Y
Section height
maxWeight
Number
Y
The maximum weight that can be loaded

Auto Containers

The main difference between automatic containers and regular containers is that they are infinite. Only one type of container from the list will be used for stuffing. The algorithm determines which type will be used for loading automatically. Groups for loading such containers cannot be specified.

JSON Title
JSON Parameters
Required
Description
uid
Unique String
N
The unique object identifier allows identifying the object in the results of loading
attr
Object
N
Any data, it will be copied for objects in the results
spaces
Array [1...3] of Spaces
Y
An array of container spaces. Standard containers have only 1 section, but ULD containers can contain 2 or 3 sections.
loadType

“auto”

“wallLength”

“wallWidth”

“floor”

Y
Type of loading cargo into a container. Auto - automatically. wallLength - along a long wall. wallWidth - along a short wall. Floor - along the floor.

Container Space

JSON Title
JSON Parameters
Required
Description
length
Number
Y
Section length
width
Number
Y
Section width
height
Number
Y
Section height
maxWeight
Number
Y
The maximum weight that can be loaded

Images

Creation of 3D images of the container.

If the images field is not specified or is null. Then the generation will not be performed.

Generating images slow down the request processing speed by about 5-10 times.

Images are returned in png format encoded with base64 algorithm as text.

The maximum image size is 1000x800 pixels.

JSON Title
JSON Parameters
Required
Description
length
Number [20…1000]
Y
Section length
width
Number [20…800]
Y
Section width

Response

The response comes in JSON format.

Response generation time can take from 0 to 60 seconds.

In case the response takes a long time, try disabling image generation by setting images: null.

Result fields:

JSON Title
JSON Parameters
Description
result
Array
See Result
ignore
Array
See Ignore
errors
Array
See Errors
version
String
A version of the current API

Result

The result field contains a list of stuffed containers of the following format:

JSON Title
JSON Parameters
Description
uid
Unique String
Unique identifier of the container
meta
String
uid passed in the request
qty
Number
Quantity of such containers
spaces
Array of Spaces
Container spaces. See Container Spaces
weight
Number
Container weight
maxWeight
Number
Maximum permissible weight
volume
Number
Container volume
cargoVolume
Number
Stuffed container volume
palletVolume
Number
Pallet volume (without cargo)
volumeRatio
Number [0…1]
What percentage of the volume is occupied
weightRatio
Number [0…1]
What percentage of the weight is occupied
attr
Object
Copied attr parameters
category
“agg:container”
Object category
objectsQty
Number
Quantity of objects inside the container
objectsQtyByMeta
Object
Quantity of objects inside by Meta-UID

Objects categories

The "agg:" prefix indicates that this category is an aggregator and can contain objects.

Category
Description
agg:container
Container
agg:container-part
Container space
agg:pallet
Pallet
obj:cargo
Object - box or roll

Container Spaces

Container Spaces describes the spaces within a container. Regular containers have one such section. There can be 2 or 3 of them in ULD containers.

JSON Title
JSON Parameters
Description
uid
Unique String
Unique identifier of the container
meta
String
uid passed in the request
form
“box”
Form of space
size

x: Number

y: Number

z: Number

Size
complex

x: 1

y: 1

z: 1

Dimension. For space, it is always (1,1,1).
location

x: 0

y: 0

z: 0

Absolute location in space. Usually (0,0,0). May differ for ULD.
position

x: 0

y: 0

z: 0

Local position in space. Usually (0,0,0). May differ for ULD.
qty
1
Quantity of such spaces. Always = 1.
volume
Number
Total space volume
cargoVolume
Number
Stuffed container volume
palletVolume
Number
Pallet volume (without cargo)
volumeRatio
Number [0…1]
What percentage of the volume is occupied
weight
Number
Weight
maxWeight
Number
Maximum permissible weight
category
“agg:container-part”
Object category
fill
Number [0…1]
Top space stuffing from 0 to 1 (0-100%)
objectsQty
Number
Quantity of objects inside the container
objectsQtyByMeta
Object
Quantity of objects inside by Meta-UID

Children objects: pallets, boxes, and rolls

There are only 3 types of children objects: pallets, boxes, and rolls.

Only pallets can have children inside, consisting of boxes and rolls.

All 3 groups of objects have a complex characteristic, which shows how many such objects (copies) are located nearby - this can be called a cluster or a stack.

For example, if complex = {x: 2, y: 3, z: 4}, then this means that there are 2 such objects along the X-axis, 3 along the Y-axis, and 4 along the Z-axis. In total, such objects consist of a whole stack (cluster, large box), 2x3x4 in size, consisting of 12 objects.

If we consider the complex of rolls (barrels), then their X and Y are always equal to 1, but Z >= 1. That is, there can be several rolls (barrels) located on top of each other.

JSON Title
JSON Parameters
Description
uid
Unique String
Unique identifier of the container
meta
String
uid passed in the request
form

“box”

“roll”

Form of space
size

x: Number

y: Number

z: Number

The size of the entire cluster (if objects are greater than 1).
complex

x: Number [1…N]

y: Number [1…N]

z: Number [1…N]

The dimension of a cluster or stack of similar objects. How many similar objects are located along the axes.

qty = complex.x * complex.y * complex.z

location

x: Number

y: Number

z: Number

Absolute location in space.
position

x: Number

y: Number

z: Number

Local position in space.
qty
Number [1...N]
Quantity of such objects in the cluster
color
String
Color in #FFFFFF format. For pallet, the color is null.
volume
Number
Total space volume
cargoVolume
Number
Stuffed container volume
palletVolume
Number
Pallet volume (without cargo)
volumeRatio
Number [0…1]
What percentage of the volume is occupied
weight
Number
Weight
maxWeight
Number
Maximum permissible weight
category

“obj:cargo”

“agg:pallet”

Object category
fill
Number [0…1]
Top space stuffing from 0 to 1 (0-100%)
floorBox

x: Number

y: Number

z: Number

Pallet size for the lower layer complex. Possibly null if the pallet is not in use.
objectsQty
Number
Quantity of objects inside the container
objectsQtyByMeta
Object
Quantity of objects inside by Meta-UID

How read complex objects

Here we see the sample complex object, that contains 24 equal boxes (4*3*2 = 24).

Response contains only one instance of object. You may clone 23 objects manually.

Sample code for clone objects:

                    for (let x = 0; x < pallet.complex.x; ++x) {
                      for (let y = 0; y < pallet.complex.y; ++y) {
                        for (let z = 0; z < pallet.complex.z; ++z) {
                          for (let j in pallet.children) {
                            let obj = pallet.children[j];

                            let location = {
                              x: pallet.location.x + obj.location.x + x * palletSize.x,
                              y: pallet.location.y + obj.location.y + y * palletSize.y,
                              z: pallet.location.z + obj.location.z + z * palletSize.z,
                            };

                            switch (obj.form) {
                              case 'box':
                                let boxData = {
                                  size: obj.size,
                                  complex: obj.complex,
                                  location: location,
                                  uid: obj.uid,
                                };
                                createBox(scene, boxData);
                                break;

                              case 'roll':
                                let rollData = {
                                  height: obj.size.height,
                                  radius: obj.size.radius,
                                  complex: obj.complex,
                                  location: location,
                                  uid: obj.uid,
                                };
                                createCylinder(scene, rollData);
                                break;
                            }
                          }
                        }
                      }
                    }
                

Ignore

List of objects that were ignored during loading. Ignoring is either due to oversizing or because of overweight.

Field name
Field values
Description
free
Number
Quantity of objects that could not be placed
total
Number
The total number of such objects
category
“object” or “pallet”
Category: objects (boxes or barrels) or pallets
uid
String
Current object/pallet uid
group
Number
Object group uid

Errors

List of errors that occurred during loading.

There are 3 types of errors: warning (loading continues), ignore (setting is incorrect and ignored, loading continues) and break (as a result of which loading stops).

Error type
Reason
Loading status
“warning”
Warning
Loading continues
“ignore”
The setting is incorrect and ignored
Loading continues
“break”
Key parameters not specified
Loading stops