You are reading the documentation for v2.1.1, which is not the current version. It describes that release and is kept for reference. It is not updated.Go to v3.1.0 →

V2

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

Unlike version 3 the algorithm used (FFD) is fixed and cannot be changed.

🔍 Learn more: Core Concepts

📜 Presets

GET /api/v2/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/v2/fit/by-preset/{preset}
Returns fitting results for all bins in the specified preset indicating which bins fit all items.

Request Example

          {
  "parameters": {
    "reportFittedItems": true,
    "reportUnfittedItems": true,
    "findSmallestBinOnly": false
  },
  "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_1", "dimensions": { "length": 2, "width": 5, "height": 10 } },
        { "id": "box_2", "dimensions": { "length": 12, "width": 15, "height": 10 } }
      ],
      "unfittedItems": [],
      "fittedItemsVolumePercentage": 100,
      "fittedBinVolumePercentage": 8.33
    },
    {
      "result": "AllItemsFit",
      "bin": { "id": "preset_bin_2", "length": 20, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_1", "dimensions": { "length": 2, "width": 5, "height": 10 } },
        { "id": "box_2", "dimensions": { "length": 12, "width": 15, "height": 10 } }
      ],
      "unfittedItems": [],
      "fittedItemsVolumePercentage": 100,
      "fittedBinVolumePercentage": 4.17
    }
  ]
}

        

🧩 Fit by Custom

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

Request Example

          {
  "parameters": {
    "reportFittedItems": true,
    "reportUnfittedItems": true,
    "findSmallestBinOnly": false
  },
  "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_1", "dimensions": { "length": 2, "width": 5, "height": 10 } },
        { "id": "box_2", "dimensions": { "length": 12, "width": 15, "height": 10 } }
      ],
      "unfittedItems": [],
      "fittedItemsVolumePercentage": 100,
      "fittedBinVolumePercentage": 8.33
    },
    {
      "result": "AllItemsFit",
      "bin": { "id": "custom_bin_2", "length": 20, "width": 40, "height": 60 },
      "fittedItems": [
        { "id": "box_1", "dimensions": { "length": 2, "width": 5, "height": 10 } },
        { "id": "box_2", "dimensions": { "length": 12, "width": 15, "height": 10 } }
      ],
      "unfittedItems": [],
      "fittedItemsVolumePercentage": 100,
      "fittedBinVolumePercentage": 4.17
    }
  ]
}

        

📦 Pack by Preset

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

Request Example

          {
  "parameters": {
    "optInToEarlyFails": false,
    "reportPackedItemsOnlyWhenFullyPacked": false,
    "neverReportUnpackedItems": false,
    "stopAtSmallestBin": false
  },
  "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", 
          "dimensions": { "length": 10, "width": 12, "height": 15 },
          "coordinates": { "x": 0, "y": 0, "z": 0 }
        },
        {
          "id": "box_1",
          "dimensions": { "length": 2, "width": 5, "height": 10 },
          "coordinates": { "x": 0, "y": 12, "z": 0 }
        }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 7.92
    },
    {
      "result": "FullyPacked",
      "bin": { "id": "preset_bin_1", "length": 20, "width": 40, "height": 60 },
      "packedItems": [
        {
          "id": "box_2",
          "dimensions": { "length": 12, "width": 15, "height": 10 },
          "coordinates": { "x": 0, "y": 0, "z": 0 }
        },
        {
          "id": "box_1",
          "dimensions": { "length": 2, "width": 5, "height": 10 },
          "coordinates": { "x": 12, "y": 0, "z": 0 }
        }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 3.96
    }
  ]
}

        

📦 Pack by Custom

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

Request Example

          {
  "parameters": {
    "optInToEarlyFails": false,
    "reportPackedItemsOnlyWhenFullyPacked": false,
    "neverReportUnpackedItems": false,
    "stopAtSmallestBin": false
  },
  "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",
          "dimensions": { "length": 10, "width": 12, "height": 15 },
          "coordinates": { "x": 0, "y": 0, "z": 0 }
        },
        {
          "id": "box_1",
          "dimensions": { "length": 2, "width": 5, "height": 10 },
          "coordinates": { "x": 0, "y": 12, "z": 0 }
        }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 7.92
    },
    {
      "result": "FullyPacked",
      "bin": { "id": "custom_bin_2", "length": 20, "width": 40, "height": 60 },
      "packedItems": [
        {
          "id": "box_2",
          "dimensions": { "length": 12, "width": 15, "height": 10 },
          "coordinates": { "x": 0, "y": 0, "z": 0 }
        },
        {
          "id": "box_1",
          "dimensions": { "length": 2, "width": 5, "height": 10 },
          "coordinates": { "x": 12, "y": 0, "z": 0 }
        }
      ],
      "unpackedItems": [],
      "packedItemsVolumePercentage": 100,
      "packedBinVolumePercentage": 3.96
    }
  ]
}

        

📐 Fitting Parameters

The Fit endpoints support the following optional parameters.

All are disabled (false) by default

reportFittedItems (bool): Include items that fit.
reportUnfittedItems (bool): Include items that do not fit.
findSmallestBinOnly (bool): Return only the smallest fitting bin.

📦 Packing Parameters

The Pack endpoints accepts the following optional parameters.

All are disabled (false) by default

optInToEarlyFails (bool): Stop processing early if packing fails.
reportPackedItemsOnlyWhenFullyPacked (bool): Return results only if all items were packed.
neverReportUnpackedItems (bool): Exclude details of unpacked items.
stopAtSmallestBin (bool): Stop after smallest valid bin is found.