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.

Version 3 introduces the algorithm choice and the ViPaq protocol for Packing endpoint while it removed the other parameters.

🔍 Learn more:

📑 Contents

📜 Presets
🧩 Fit by Preset
🧩 Fit by Custom
📦 Pack by Preset
📦 Pack by Custom
🧠 Algorithm
🗜️ ViPaq Data

📜 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_1", "length": 2, "width": 5, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 8.33,
      "fittedItemsVolumePercentage": 100
    },
    {
      "result": "AllItemsFit",
      "bin": { "id": "preset_bin_2", "length": 20, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_2", "length": 12, "width": 15, "height": 10 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 3.96,
      "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_1", "length": 2, "width": 5, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 8.33,
      "fittedItemsVolumePercentage": 100
    },
    {
      "result": "AllItemsFit",
      "bin": { "id": "custom_bin_2", "length": 20, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_2", "length": 12, "width": 15, "height": 10 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 3.96,
      "fittedItemsVolumePercentage": 100
    }
  ]
}

        

📦 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_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 12, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 7.92,
      "viPaqData": "AAQACig8CgwPAAAACgwPAAwAAgUKAAAPAgUKABgA"
    },
    {
      "result": "FullyPacked",
      "bin": { "id": "preset_bin_1", "length": 20, "width": 40, "height": 60 },
      "packedItems": [
        { "id": "box_2", "length": 12, "width": 15, "height": 10, "x": 0, "y": 0, "z": 0 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 12, "y": 0, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 3.96,
      "viPaqData": "AAQAFCg8DA8KAAAADAoPAA8AAgUKDAAAAgUKAAAK"
    }
  ]
}

        

📦 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_1", "length": 2, "width": 5, "height": 10, "x": 0, "y": 12, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 7.92,
      "viPaqData": "AAQACig8CgwPAAAACgwPAAwAAgUKAAAPAgUKABgA"
    },
    {
      "result": "FullyPacked",
      "bin": { "id": "custom_bin_2", "length": 20, "width": 40, "height": 60 },
      "packedItems": [
        { "id": "box_2", "length": 12, "width": 15, "height": 10, "x": 0, "y": 0, "z": 0 },
        { "id": "box_1", "length": 2, "width": 5, "height": 10, "x": 12, "y": 0, "z": 0 }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 3.96,
      "viPaqData": "AAQAFCg8DA8KAAAADAoPAA8AAgUKDAAAAgUKAAAK"
    }
  ]
}

        

🧠 Algorithm

Both Fitting and Packing Endpoints introduct the mandatory algorithm parameter to select the algorithm used for the operation.

Available algorithms:

FFD — First Fit Decreasing (default)
BFD — Best Fit Decreasing
WFD — Worst Fit Decreasing

🗜️ ViPaq Data

The packing endpoint introduct the optional includeViPaqData parameter. If set to true, the response will include a viPaqData field containing the packing information encoded in the ViPaq protocol.