Will it fit in the box?

Binacle.Net answers which box an order goes in, in milliseconds. Give it your box sizes and a list of items and it returns the smallest box that holds them, and where every item sits. It is a free and open source 3D bin packing API that you host yourself.

Built for checkout: your customer picks a locker or a box, and Binacle.Net says whether the order fits before they pay.

Run it Try the demo

Read the source on GitHub

POST /api/v3/fit/by-custom

                    {
  "parameters": { "algorithm": "FFD" },
  "bins": [
    { "id": "locker-S", "length": 30, "width": 20, "height": 15 },
    { "id": "locker-M", "length": 40, "width": 30, "height": 20 }
  ],
  "items": [
    { "id": "box-a", "quantity": 2, "length": 10, "width": 10, "height": 10 },
    { "id": "box-b", "quantity": 1, "length": 25, "width": 18, "height": 12 }
  ]
}

                  

RESPONSE

                    {
  "result": "Success",
  "data": [
    {
      "result": "NotAllItemsFit",
      "bin": { "id": "locker-S", "length": 30, "width": 20, "height": 15 },
      "fittedItems": [ { "id": "box-b", "length": 25, "width": 18, "height": 12 } ],
      "unfittedItems": [ { "id": "box-a", "quantity": 2 } ],
      "fittedBinVolumePercentage": 60.0,
      "fittedItemsVolumePercentage": 72.97
    },
    {
      "result": "AllItemsFit",
      "bin": { "id": "locker-M", "length": 40, "width": 30, "height": 20 },
      "fittedItems": [
        { "id": "box-b", "length": 25, "width": 18, "height": 12 },
        { "id": "box-a", "length": 10, "width": 10, "height": 10 },
        { "id": "box-a", "length": 10, "width": 10, "height": 10 }
      ],
      "unfittedItems": [],
      "fittedBinVolumePercentage": 30.83,
      "fittedItemsVolumePercentage": 100
    }
  ]
}

                  

The medium locker holds all three items. The small one takes only one of them.

The problem

Checkout has to answer before the customer pays.

Your customer picks a locker size or a box, and something has to say yes or no while they are still on the page. Not in a warehouse an hour later.

Get it wrong and someone repacks the order, prints a second label, or sends a parcel to a locker that will not take it. The customer has already paid.

Working out whether the items go in is a 3D packing problem, and checkout does not have long to wait.

Scope

What it answers

Binacle.Net works one box at a time.

It answers	It does not answer
Does this order fit in this box?	How do I split an order across boxes?
Which of my boxes is the smallest that holds it?	How many boxes do I need?
Where does every item sit?	Which carrier or rate is cheapest?

Trade-offs

What you get, and what it costs

You run it yourself

Does: Your customers' dimensions never leave your network
Costs: Uptime is yours

A yes is reliable

Does: If it says the items fit, they fit, and the pack routes show you how
Costs: A no is not a proof - there may be an arrangement it did not find

Free and open source

Does: GPL-3.0, no signup, no tier
Costs: Support is a GitHub discussion, not an SLA

Strictly, that makes this the single-container case - a 3D knapsack rather than bin packing, and the word the logistics trade uses is cartonization. Most people looking for it search for 3D bin packing, so that is the term used here.

The API

What you can ask it

Two functions. Fit checks whether a set of items goes into a box. Pack works out where each one sits.

Either takes your boxes in the request - by-custom - or by the name of a preset you configured once - by-preset/{preset}.

The pack endpoints run the same algorithms and also return the position of every item. A fit response tells you what went in and what did not; it has no coordinates in it.

Use cases

Where people use it

The same 3D bin packing API answers three different questions, depending on who is asking.

Warehouse and shipping teams call it picking the right box for an order.

If your customers collect from a locker, the question is whether an order fits a parcel compartment before they choose one.

If you are deciding whether to integrate it, read how the packing itself works - the two functions, the three algorithms, and what a yes and a no each mean.

The maintainer

Who makes this

Chris Mavrommatis builds Binacle.Net. Every commit since February 2023 is his. Questions go to GitHub Discussions.

Get started

Run it

One image, one port.

docker run -d --name binacle-net -p 8080:8080 -e SWAGGER_UI=True -e SCALAR_UI=True -e UI_MODULE=True binacle/binacle-net:3.0

The three flags turn on three optional pages, and the API needs none of them.

UI_MODULE - the packing demo, at /
SWAGGER_UI - Swagger UI, at /swagger/
SCALAR_UI - Scalar, at /scalar/

The API itself is under /api/v3. Everything else is optional, and the quick start has the rest.

Try it out.