V3

Version 3 of the Binacle.Net API provides endpoints for fitting and packing items into bins, using either predefined presets or custom bin dimensions.

Every endpoint takes an algorithm parameter, and the packing endpoints can return the result encoded with the ViPaq protocol.

V3 is stable and is the recommended version. It is unchanged in v3.0.0 apart from the ViPaq payload, which uses the new format - see the warning under ViPaq Data.

🔍 Learn more:

📜 Presets

GET /api/v3/presets
Returns all configured bin presets.

Response Example

          {
  "result": "Success",
  "data": {
    "preset1": [
      { "id": "preset1_bin1", "length": 10, "width": 10, "height": 10 },
      { "id": "preset1_bin2", "length": 20, "width": 20, "height": 20 },
      { "id": "preset1_bin3", "length": 30, "width": 30, "height": 30 }
    ],
    "preset2": [
      { "id": "preset2_bin1", "length": 10, "width": 20, "height": 30 },
      { "id": "preset2_bin2", "length": 30, "width": 60, "height": 60 }
    ]
  }
}

        

🧩 Fit by Preset

POST /api/v3/fit/by-preset/{preset}
Returns fitting results for all bins in the specified preset indicating which bins fit all items.

Request Example

          {
  "parameters": {
    "algorithm": "FFD"
  },
  "items": [
    { "id": "box_1", "quantity": 2, "length": 2, "width": 5, "height": 10 },
    { "id": "box_2", "quantity": 1, "length": 12, "width": 15, "height": 10 },
    { "id": "box_3", "quantity": 1, "length": 12, "width": 10, "height": 15 }
  ]
}

        

Response Example

          {
  "result": "Success",
  "data": [
    {
      "result": "AllItemsFit",
      "bin": { "id": "preset_bin_1", "length": 10, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 15.83,
      "fittedItemsVolumePercentage": 100
    },
    {
      "result": "AllItemsFit",
      "bin": { "id": "preset_bin_2", "length": 20, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 7.92,
      "fittedItemsVolumePercentage": 100
    }
  ]
}

        

🧩 Fit by Custom

POST /api/v3/fit/by-custom
Returns fitting results for provided custom bins.

Request Example

          {
  "parameters": {
    "algorithm": "FFD"
  },
  "bins": [
    { "id": "custom_bin_1", "length": 10, "width": 40, "height": 60 },
    { "id": "custom_bin_2", "length": 20, "width": 40, "height": 60 }
  ],
  "items": [
    { "id": "box_1", "quantity": 2, "length": 2, "width": 5, "height": 10 },
    { "id": "box_2", "quantity": 1, "length": 12, "width": 15, "height": 10 },
    { "id": "box_3", "quantity": 1, "length": 12, "width": 10, "height": 15 }
  ]
}

        

Response Example

          {
  "result": "Success",
  "data": [
    {
      "result": "AllItemsFit",
      "bin": { "id": "custom_bin_1", "length": 10, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 15.83,
      "fittedItemsVolumePercentage": 100
    },
    {
      "result": "AllItemsFit",
      "bin": { "id": "custom_bin_2", "length": 20, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 7.92,
      "fittedItemsVolumePercentage": 100
    }
  ]
}

        

A bin that fails looks like this - the envelope’s result is Failure:

          {
  "result": "Failure",
  "data": [
    {
      "result": "NotAllItemsFit",
      "bin": { "id": "custom_bin", "length": 10, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15 }
      ],
      "unfittedItems": [ { "id": "box_1", "quantity": 2 } ],
      "fittedBinVolumePercentage": 15.0,
      "fittedItemsVolumePercentage": 94.74
    }
  ]
}

        

📦 Pack by Preset

POST /api/v3/pack/by-preset/{preset}
Returns packing results with item placement details for all bins in the preset.

Request Example

          {
  "parameters": {
    "algorithm": "FFD",
    "includeViPaqData": true
  },
  "items": [
    { "id": "box_1", "quantity": 2, "length": 2, "width": 5, "height": 10 },
    { "id": "box_2", "quantity": 1, "length": 12, "width": 15, "height": 10 },
    { "id": "box_3", "quantity": 1, "length": 12, "width": 10, "height": 15 }
  ]
}

        

Response Example

          {
  "result": "Success",
  "data": [
    {
      "result": "FullyPacked",
      "bin": { "id": "preset_bin_1", "length": 10, "width": 40, "height": 60 },
      "packedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15, "x": 0, "y": 0, "z": 0 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15, "x": 0, "y": 12, "z": 0 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 0, "z": 15 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 24, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 15.83,
      "viPaqData": "AAAEAAooPAoMDwAAAAoMDwAMAAIFCgAADwIFCgAYAA=="
    },
    {
      "result": "FullyPacked",
      "bin": { "id": "preset_bin_2", "length": 20, "width": 40, "height": 60 },
      "packedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15, "x": 0, "y": 0, "z": 0 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15, "x": 0, "y": 12, "z": 0 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 0, "z": 15 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 24, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 7.92,
      "viPaqData": "AAAEABQoPAoMDwAAAAoMDwAMAAIFCgAADwIFCgAYAA=="
    }
  ]
}

        

📦 Pack by Custom

POST /api/v3/pack/by-custom
Returns packing results with item placement for custom bins.

Request Example

          {
  "parameters": {
    "algorithm": "FFD",
    "includeViPaqData": true
  },
  "bins": [
    { "id": "custom_bin_1", "length": 10, "width": 40, "height": 60 },
    { "id": "custom_bin_2", "length": 20, "width": 40, "height": 60 }
  ],
  "items": [
    { "id": "box_1", "quantity": 2, "length": 2, "width": 5, "height": 10 },
    { "id": "box_2", "quantity": 1, "length": 12, "width": 15, "height": 10 },
    { "id": "box_3", "quantity": 1, "length": 12, "width": 10, "height": 15 }
  ]
}

        

Response Example

          {
  "result": "Success",
  "data": [
    {
      "result": "FullyPacked",
      "bin": { "id": "custom_bin_1", "length": 10, "width": 40, "height": 60 },
      "packedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15, "x": 0, "y": 0, "z": 0 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15, "x": 0, "y": 12, "z": 0 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 0, "z": 15 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 24, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 15.83,
      "viPaqData": "AAAEAAooPAoMDwAAAAoMDwAMAAIFCgAADwIFCgAYAA=="
    },
    {
      "result": "FullyPacked",
      "bin": { "id": "custom_bin_2", "length": 20, "width": 40, "height": 60 },
      "packedItems": [
        { "id": "box_2", "length": 10, "width": 12, "height": 15, "x": 0, "y": 0, "z": 0 },
        { "id": "box_3", "length": 10, "width": 12, "height": 15, "x": 0, "y": 12, "z": 0 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 0, "z": 15 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 24, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 7.92,
      "viPaqData": "AAAEABQoPAoMDwAAAAoMDwAMAAIFCgAADwIFCgAYAA=="
    }
  ]
}

        

🧠 Algorithm

Both the fitting and the packing endpoints take a mandatory algorithm parameter, which selects the algorithm used for the operation.

Available algorithms:

FFD: First Fit Decreasing
BFD: Best Fit Decreasing
WFD: Worst Fit Decreasing

Best is a Version 4 parameter and is not accepted here.

🗜️ ViPaq Data

The packing endpoints take the optional includeViPaqData parameter. When it is true, each result carries a viPaqData field holding the packing arrangement encoded with the ViPaq protocol.

🚨 The ViPaq format changed in v3.0.0. Strings produced by v2.1.1 and earlier do not decode here, and there is no fallback reader. Regenerate any string you have stored - a saved link or a bookmarked result. See ViPaq Protocol.

🚦 Result Values

The envelope’s result is Success or Failure. Each entry in data carries its own result.

Fitting

AllItemsFit: every item fits in the bin.
NotAllItemsFit: at least one item was left over.
EarlyFail_TotalVolumeExceeded: the items are bigger than the bin, so nothing was attempted.
EarlyFail_ItemDimensionExceeded: an item is longer than the bin in some dimension.

Packing

FullyPacked: every item was placed.
PartiallyPacked: some items were placed, some were not.
NotPacked: nothing was placed.
EarlyFail_ContainerVolumeExceeded, EarlyFail_ContainerDimensionExceeded: as above, before packing began.