packToBin

Pack your items into a specific type of bin.

The PackToBin endpoint packs your items into the bin provided, creating as many bins as needed to fulfill the complete packing request. The packing result provides detailed information per item in each bin, such as how to rotate the item and where to place it.

Just getting started?

Take a look at our quick start page.

Not sure which endpoint to use?

Take a look at our features for more information.

Establishing Connection

Connectivity
Base url
https://www.packing-optimizer.com
Path
/api/packToBin
Method
POST

All API requests must be made over HTTPS.

Headers
Authorization
Basic-Auth
Content-Type
application/json

Your credentials can be retrieved (and reset) from your account settings.

curl --user username:password -d @input.json -H "Content-Type: application/json" https://www.packing-optimizer.com/api/packToBin

The Request

The Bin object

Information about the bin that will be used for packing.

A bin is a shipping unit which will contain items. Think of a box, pallet, or container.

Mandatory attributes

bin.type string

Type of bin used for packing.
Example: pallet

bin.width numeric

Width of the bin.
Example: 1.2

bin.depth numeric

Depth of the bin.
Example: 0.8

bin.height numeric

Height of the bin.
Example: 1.65

bin.maxWeight numeric

Max weight that a single bin can carry.
Example: 1500

Other attributes

The number of times this bin can be used.
Default: unlimited
Example: 3

Maximum number of items that a bin is allowed to fit.
Default: unlimited
Example: 100

Maximum value that a bin is allowed to contain.
Default: unlimited
Example: 1000

Allows you to control the order in which the items are evaluated for packing.

Option Description
weight The heaviest items are evaluated first.
volume The biggest items are evaluated first.
optimized A custom order is used to increase bin utilization.

Default: optimized


Default: optimized

Allows you to enforce that a certain bottom surface area percentage of an item must be resting on top of another surface in order to be a valid position. For example, a gravityStrength of 75 would mean that atleast three quarters of an item must be resting on top of another surface.
Options: 0 to 100
Default: 0

Sets the packing direction of the bin. For example, boxes on a pallet are usually placed bottom first, stacking upwards when needed. A container with a closed top, however, would be stacked back to front.
Options: bottomUp, backToFront
Default: bottomUp

The Item object

Information about the items that have to be packed.

The request takes an array of item objects as input.

Mandatory attributes

items[].id string

Id to identify this individual item.
Example: ITEM001

items[].width numeric

The width of the item.
Example: 0.20

items[].depth numeric

The depth of the item.
Example: 0.20

items[].height numeric

The height of the item.
Example: 0.20

items[].weight numeric

The weight of the item.
Example: 10

Other attributes

The value of the item.
Default: 0
Example: 10

Items with the same consolidation key will be separated from the other items and grouped in their own bin(s). Items with different consolidation key values will never be grouped in the same bin. Items with no key will group together by default.
Default: none
Example: customerX

Same as bin.gravityStrength; item level gravityStrength takes precedence over bin level gravityStrength.
Options: 0 to 100
Default: 0

Indicates the way that an item is allowed to rotate while packing.

Option Description
0 No rotation.
1 Allowed to rotate around the z-axis by 90°.
2 Allowed to rotate around the x-axis by 90°.
3 Allowed to rotate around the x-axis by 90° and then around the z-axis by 90°.
4 Allowed to rotate around the y-axis by 90°.
5 Allowed to rotate around the z-axis by 90° and then around the x-axis by 90°.

Default: 012345
Example: 015

Enforce a particular stacking style for this item.

Option Description
allowAll No particular stacking style is being taken into account while placing this item.
bottomNoItemsOnTop The item will be placed at the bottom of the bin and cannot be placed on top of another item. It is not allowed to place any other item(partly) on top of this item. This item will always be the first to be evaluated when packing, meaning that this setting takes precedence over the order determined by bin.sortMethod.
stackByKey The item will either be placed on the ground, or on top of an item with the same stackingKey . This item will always be the first to be evaluated when packing(only bottomNoItemsOnTop items take precedence), meaning that this setting takes precedence over the order determined by bin.sortMethod.

Default: allowAll
Example: bottomNoItemsOnTop

Only items with the same stacking key are allowed to be stacked on top of each other.
Default: none
Example: productTypeA

Query String Options

Parameters which provide some control over the data being transmitted in the response, such as specifying the quantity or format of the data.

If false, the individual bins will not be included in the response and only header information will be transmitted.
Options: true or false
Default: true
Example: /api/packToBin?includeBins=false

If false, the individual item information per bin will not be included in the response.
Options: true or false
Default: true
Example: /api/packToBin?includeItems=false

Sets the decimal precision of the response body.
Default: 3
Example: /api/packToBin?responsePrecision=5

If rotated, the item dimensions in the response message will be adjusted according to the rotation type.
Options: orginal, rotated
Default: original
Example: /api/packToBin?itemDimensionsAfter=rotated

Example

          
{
    "bin": {
        "type": "Pallet",
        "width": 1.2,
        "depth": 0.8,
        "height": 1.65,
        "maxWeight": 1500
    },
    "items": [{
            "id": "DTM001",
            "width": 0.1,
            "height": 1.62,
            "depth": 0.2,
            "weight": 1000,
            "consolidationKey": "X123",
            "allowedRotations": "01"
        },
        {
            "id": "DTM002",
            "width": 0.29,
            "height": 0.32,
            "depth": 0.49,
            "weight": 500
        },
        {
            "id": "DTM003",
            "width": 0.29,
            "height": 0.32,
            "depth": 0.49,
            "weight": 10,
            "consolidationKey": "X123",
            "allowedRotations": "01"
        },
        {
            "id": "DTM004",
            "width": 0.29,
            "height": 0.32,
            "depth": 0.49,
            "weight": 10
        },
        {
            "id": "DTM006",
            "width": 0.29,
            "height": 0.32,
            "depth": 0.49,
            "weight": 10,
            "allowedRotations": "012345"
        },
        {
            "id": "DTM007",
            "width": 0.29,
            "height": 0.32,
            "depth": 0.49,
            "weight": 10
        },
        {
            "id": "DTM008",
            "width": 0.19,
            "height": 0.22,
            "depth": 0.29,
            "weight": 10,
            "consolidationKey": "X123",
            "allowedRotations": "01"
        }
    ]
}

The Response

The response layout

The packing response body follows a certain hierarchy, this hierarchy can be categorized in 3 sections.

Header information
These details reason across all the bins that have been packed.
Bin information
These details are about a particular bin that has been packed.
Item information
These are details about a particular item. Items are nested inside bins.

Header

Contains header information about the complete packing request.

requiredNrOfBins numeric

The total number of bins it requires to pack all items.

totalVolumeUtil numeric

The total volume utilization in percentage points.

totalWeightUtil numeric

The total weight utilization in percentage points

packedBins array

Contains the bins that have been packed.

unfittedItems array

Array of items that did not fit. Items in this array have the same attributes as items where packed successfully.

PackedBins

Contains information about each bin that has been packed.

packedBins[].id numeric

Incrementing counter starting from 1. Generated by Packing Optimizer.

packedBins[].type string

The type of bin as provided by the caller in the request body.

packedBins[].width numeric

The maximum width of the bin as provided by the caller in the request body.

packedBins[].depth numeric

The maximum depth of the bin as provided by the caller in the request body.

packedBins[].height numeric

The maximum height of the bin as provided by the caller in the request body.

packedBins[].maxVolume numeric

The maximum volume of the bin.

packedBins[].actualVolume numeric

Total volume of the items packed in the bin.

packedBins[].actualVolumeUtil numeric

actualVolume expressed in percentage points relative to the maxVolume attribute.

packedBins[].maxWeight numeric

The maximum weight of the bin as provided by the caller in the request body.

packedBins[].actualWeight numeric

Total weight of the items packed in the bin.

packedBins[].actualWeightUtil numeric

actualWeight expressed in percentage points relative to the maxWeight attribute.

packedBins[].value numeric

Total value of the items packed in the bin.

packedBins[].maxValue numeric

The maximum value of the bin as provided by the caller in the request body.

packedBins[].furthestPointWidth numeric

The furthest point alongside the x axis that any item is reaching.

packedBins[].furthestPointDepth numeric

The furthest point alongside the y axis that any item is reaching.

packedBins[].furthestPointHeight numeric

The furthest point alongside the z axis that any item is reaching.

packedBins[].nrOfItems numeric

The total number of items packed inside the bin.

packedBins[].fittedItems array

Contains the items inside the bin.

FittedItems

Contains information about each item that has been packed in the bin.

packedBins[].fittedItems[].id numeric

Item identifier as provided by the caller in the request body.

packedBins[].fittedItems[].stackingStyle string

The stacking style used during packing.

packedBins[].fittedItems[].consolidationKey string

Item consolidation key used during packing.

packedBins[].fittedItems[].allowedRotations string

Rotations that were allowed during packing.

packedBins[].fittedItems[].xCoordinate numeric

X coordinate of the item inside the bin.

packedBins[].fittedItems[].yCoordinate numeric

Y coordinate of the item inside the bin.

packedBins[].fittedItems[].zCoordinate numeric

Z coordinate of the item inside the bin.

packedBins[].fittedItems[].rotationType numeric

Type of rotation that has been used to pack this item.

Example

          
{
    "requiredNrOfBins": 2,
    "totalVolumeUtil": 45.9,
    "totalWeightUtil": 81.7,
    "packedBins": [
        {
            "id": 1,
            "type": "Pallet",
            "width": 1.2,
            "depth": 0.8,
            "height": 1.65,
            "maxVolume": 1.584,
            "actualVolume": 0.42101,
            "actualVolumeUtil": 26.6,
            "maxWeight": 1500.0,
            "actualWeight": 1200.0,
            "actualWeightUtil": 80.0,
            "furthestPointWidth": 0.79,
            "furthestPointDepth": 0.59,
            "furthestPointHeight": 1.14,
            "nrOfItems": 2,
            "fittedItems": [
                {
                    "id": "DTM002",
                    "width": 0.79,
                    "depth": 0.49,
                    "height": 0.62,
                    "weight": 500.0,
                    "volume": 0.2,
                    "xCoordinate": 0,
                    "yCoordinate": 0,
                    "zCoordinate": 0,
                    "allowedRotations": "012345",
                    "rotationType": 0,
                    "rotationTypeDescription": "No rotation",
                    "stackingStyle": "allowAll"
                },
                {
                    "id": "DTM004",
                    "width": 0.59,
                    "depth": 0.59,
                    "height": 0.52,
                    "weight": 700.0,
                    "volume": 0.18101,
                    "xCoordinate": 0,
                    "yCoordinate": 0,
                    "zCoordinate": 0.62,
                    "allowedRotations": "012345",
                    "rotationType": 0,
                    "rotationTypeDescription": "No rotation",
                    "stackingStyle": "allowAll"
                }
            ]
        },
        {
            "id": 2,
            "type": "Pallet",
            "width": 1.2,
            "depth": 0.8,
            "height": 1.65,
            "maxVolume": 1.584,
            "actualVolume": 1.03237,
            "actualVolumeUtil": 65.2,
            "maxWeight": 1500.0,
            "actualWeight": 1250.0,
            "actualWeightUtil": 83.3,
            "furthestPointWidth": 0.99,
            "furthestPointDepth": 0.79,
            "furthestPointHeight": 1.32,
            "nrOfItems": 1,
            "fittedItems": [
                {
                    "id": "DTM003",
                    "width": 0.99,
                    "depth": 0.79,
                    "height": 1.32,
                    "weight": 1250.0,
                    "volume": 1.03237,
                    "consolidationKey": "X123",
                    "xCoordinate": 0,
                    "yCoordinate": 0,
                    "zCoordinate": 0,
                    "allowedRotations": "01",
                    "rotationType": 0,
                    "rotationTypeDescription": "No rotation.",
                    "stackingStyle": "allowAll"
                }
            ]
        }
    ]
}