cylinderPack

Efficiently pack cylindrical items using multiple bin sizes.

The cylinderPack endpoint provides detailed information per item in each bin, such as where to place it. In contrast to packToMixedBins, cylinderPack only accepts cylindrical items. The cylinders will be packed using a combination of different bin sizes, aiming to reduce the total packing volume or the total required bins.

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/cylinderPack
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/cylinderPack

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.

Information: A bin can either be a cylinder, or a cube. If your bin is a cube, the diameter should be omitted. If your bin is a cylinder, the width and depth should be omitted.

The request takes an array of bin objects as input.

Mandatory attributes

bins[].type string

Type of bin used for packing.
Example: pallet

bins[].width numeric

Width of the bin.
Example: 1.2

bins[].depth numeric

Depth of the bin.
Example: 0.8

bins[].height numeric

Height of the bin.
Example: 1.65

bins[].diameter numeric

The diameter of the bin.
Example: 0.2

bins[].maxWeight numeric

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

Other attributes

The cost of using this bin.
Default: 0
Example: 100

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

The pattern that will be used to place items onto the bin.
Options: optimized, spiral, bottomUp, insideOut
Default: optimized

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[].diameter numeric

The diameter 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

A margin that must be between this item and another item. This can be used if items are not allowed to be too tightly packed.
Example: 0.05

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

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

The Distributor object

Provides options to indicate how items should be distributed over bins.

Optional attributes

Indicate based on which attribute the items should be distributed.

Option Description
itemCount The bin aims to meet or exceed the desired number of items as set by the threshold.

Example: itemCount

The threshold that is desired to be reached.
Example: 15

If true, the threshold is not just desired, but it is strictly enforced. Meaning that bins that do not meet the threshold will be considered invalid.
Default: false

The Config object

Additional configuration parameters that influence packing.

Optional attributes

Determines which value should be minimized during packing.

Option Description
bins The number of required bins will be minimized.
cost The total cost of the bins used will be minimized.
volume The total bin volume will be minimized.

Default: volume

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/cylinderPack?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/cylinderPack?includeItems=false

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

Example


{
    "bins": [{
            "type": "pallet-small",
            "width": 1,
            "depth": 1,
            "height": 0.3,
            "maxWeight": 1500
        },
        {
            "type": "cylinder-small",
            "diameter": 1,
            "height": 0.4,
            "maxWeight": 1500
        }
    ],
    "items": [{
            "id": "cylinder-XL",
            "diameter": 0.9,
            "height": 0.2,
            "weight": 10,
            "stackingKey": "productTypeA"
        },
        {
            "id": "cylinder-L",
            "diameter": 0.6,
            "height": 0.2,
            "weight": 10
        },
        {
            "id": "cylinder-M",
            "diameter": 0.4,
            "height": 0.2,
            "weight": 10,
            "stackingKey": "productTypeA"
        },
        {
            "id": "cylinder-S",
            "diameter": 0.2,
            "height": 0.2,
            "weight": 10
        }
    ],
    "config": {
        "minimizationStrategy": "volume"
    }
}

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

totalCost numeric

The total cost of the packed bins, only relevant if cost is used.

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[].diameter numeric

The diameter 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[].cost numeric

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

packedBins[].costPerPackedVolumeUnit numeric

The cost it takes to pack one volume unit. This is equal to cost divided by actualVolume.

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[].consolidationKey string

Item consolidation key used during packing.

packedBins[].fittedItems[].stackingKey string

The stacking key used 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[].margin numeric

The margin that was taken into account while placing the item.

Example


{
    "packedBins": [
        {
            "actualVolume": 0.1523672,
            "actualVolumeUtil": 48.5,
            "actualWeight": 20.0,
            "actualWeightUtil": 1.333333,
            "diameter": 1,
            "fittedItems": [
                {
                    "diameter": 0.9,
                    "height": 0.2,
                    "id": "cylinder-XL",
                    "margin": 0.0,
                    "stackingKey": "productTypeA",
                    "volume": 0.1272345,
                    "weight": 10.0,
                    "xCoordinate": 0.5,
                    "yCoordinate": 0.45,
                    "zCoordinate": 0.0
                },
                {
                    "diameter": 0.4,
                    "height": 0.2,
                    "id": "cylinder-M",
                    "margin": 0.0,
                    "stackingKey": "productTypeA",
                    "volume": 0.02513274,
                    "weight": 10.0,
                    "xCoordinate": 0.5,
                    "yCoordinate": 0.45,
                    "zCoordinate": 0.2
                }
            ],
            "height": 0.4,
            "id": 1,
            "maxVolume": 0.3141593,
            "maxWeight": 1500.0,
            "nrOfItems": 2,
            "type": "cylinder-small"
        },
        {
            "actualVolume": 0.06283185,
            "actualVolumeUtil": 20.94395,
            "actualWeight": 20.0,
            "actualWeightUtil": 1.333333,
            "depth": 1.0,
            "fittedItems": [
                {
                    "diameter": 0.6,
                    "height": 0.2,
                    "id": "cylinder-L",
                    "margin": 0.0,
                    "volume": 0.05654867,
                    "weight": 10.0,
                    "xCoordinate": 0.3,
                    "yCoordinate": 0.3,
                    "zCoordinate": 0.0
                },
                {
                    "diameter": 0.2,
                    "height": 0.2,
                    "id": "cylinder-S",
                    "margin": 0.0,
                    "volume": 0.006283185,
                    "weight": 10.0,
                    "xCoordinate": 0.6498479,
                    "yCoordinate": 0.1060762,
                    "zCoordinate": 0.0
                }
            ],
            "height": 0.3,
            "id": 2,
            "maxVolume": 0.3,
            "maxWeight": 1500.0,
            "nrOfItems": 2,
            "type": "pallet-small",
            "width": 1.0
        }
    ],
    "requiredNrOfBins": 2,
    "totalVolumeUtil": 35.03962,
    "totalWeightUtil": 1.333333
}