[POST] Package best fit#
Calculates the best fit for one box across the container and pallet types you send. Use it to compare packaging and transport options before you create a shipment.
POST https://BASE_URL/api/v1/package-fit/
Note
In the examples, BASE_URL is the base URL of your environment, for
example https://api.alphaaugmented.com. See Base URLs for the
complete list.
Requires Authentication.
When to call#
Compare how well one box fills your containers and pallets, for example to choose a box size or check packaging before you create an order.
This endpoint does not plan a shipment. To optimize a real shipment, use [POST] Create an order.
Container and pallet types#
Container and pallet types are identified by short codes, for example 40HC
for a high-cube container or EUR1 for a Euro pallet. These codes are
provided by ALPHA for your account, based on your setup.
-
Codes are case-insensitive:
40hcand40HCgive the same result. -
If you list the same code more than once, it is calculated only once.
-
Only types that are currently available can be used.
-
An unknown code returns
400.
Limits#
|
Limit |
Value |
|---|---|
|
Container types per request |
2 |
|
Pallet types per request |
3 |
|
Boxes per container type |
2500 |
|
Boxes per pallet type |
500 |
ALPHA limits the number of types and boxes per request.
Request structure#
{
"package": {
"box_id": "<string>",
"length": "<number>",
"width": "<number>",
"height": "<number>",
"weight": "<number>",
"rotation": "L | W | H"
},
"container_types": ["<container code>"],
"pallet_types": ["<pallet code>"],
"pallet_max_height": "<number>",
"include_images": false
}
Send dimensions in cm and weight in kg. This endpoint always uses these
units, regardless of your lane’s Units of measure settings.
Example request#
{
"package": {
"box_id": "BOX-4711",
"length": 40,
"width": 30,
"height": 30,
"weight": 5,
"rotation": "L"
},
"container_types": ["20DC", "40HC"],
"pallet_types": ["EUR1", "GMA"],
"pallet_max_height": 150
}
cURL:
curl https://BASE_URL/api/v1/package-fit/ \
-H "Authorization: Api-Key YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"package": {
"box_id": "BOX-4711",
"length": 40,
"width": 30,
"height": 30,
"weight": 5,
"rotation": "L"
},
"container_types": ["20DC", "40HC"],
"pallet_types": ["EUR1", "GMA"],
"pallet_max_height": 150
}'
Parameters#
Top-level fields for the request body.
|
Field |
Type |
Description |
|---|---|---|
|
|
object |
Required. The box to test. |
|
|
array of strings |
Optional. Up to two container type codes. Leave out or send
|
|
|
array of strings |
Optional. Up to three pallet type codes. Leave out or send
|
|
|
number |
Required when you send |
|
|
boolean |
Optional, default |
Package fields#
Objects in package.
|
Field |
Type |
Description |
|---|---|---|
|
|
string |
Required. Your identifier for the box, up to 255 characters. Returned unchanged. |
|
|
number |
Required. Box dimensions in cm, at least 0.01 each. |
|
|
number |
Required. Box weight in kg, at least 0.01. |
|
|
string |
Optional. Rotations allowed while packing, written as |
Response#
200 OK. One result for each type you requested, in the order you sent them.
The containers and pallets arrays are empty when you skip that kind of
type.
{
"box_id": "BOX-4711",
"containers": [
{
"container": "20DC",
"box_count": 756,
"layer_count": 7,
"column_count": 19,
"orientation": "L",
"utilization": 81.99,
"square_utilization": 119700.0,
"image": null,
"packing_instructions": null
},
{
"container": "40HC",
"box_count": 1840,
"layer_count": 8,
"column_count": 30,
"orientation": "L",
"utilization": 86.76,
"square_utilization": 288000.0,
"image": null,
"packing_instructions": null
}
],
"pallets": [
{
"pallet": "EUR1",
"box_count": 32,
"layer_count": 4,
"column_count": 3,
"orientation": "L",
"utilization": 88.5,
"square_utilization": 14400.0,
"image": null,
"packing_instructions": null
},
{
"pallet": "GMA",
"box_count": 40,
"layer_count": 4,
"column_count": 3,
"orientation": "L",
"utilization": 85.81,
"square_utilization": 14400.0,
"image": null,
"packing_instructions": null
}
]
}
See Response fields.
Response fields#
|
Field |
Type |
Description |
|---|---|---|
|
|
string |
The identifier you sent. |
|
|
array |
Results for the container types you requested. |
|
|
array |
Results for the pallet types you requested. |
Each result has these fields:
|
Field |
Type |
Description |
|---|---|---|
|
|
string |
The type code as sent. |
|
|
integer |
How many boxes fit in this container or pallet type. |
|
|
integer |
Number of layers of boxes stacked on top of each other. |
|
|
integer |
Number of boxes in a row along the length. |
|
|
string |
The rotations used, written as |
|
|
number |
Percentage of the available volume filled by the boxes, from 0 to 100. On pallets, volume is measured above the deck. |
|
|
number |
Area the load covers when viewed from the side, in cm². See Square utilization. |
|
|
string or null |
Base64-encoded PNG of the load, without a |
|
|
string or null |
Reserved for future use. Always |
Note
When box_count is 0, the box does not fit in that type. The other
measurements are 0 and orientation is empty.
Errors#
|
HTTP status |
Description |
|---|---|
|
|
Invalid field, no types selected, unknown type code, too many types, or a box so small that the estimated box count would exceed the per-type limit. |
|
|
The API key is missing or invalid. |
|
|
ALPHA could not complete the calculation. Try again later. |
{ "container_types": ["Unknown type(s): 53HC."] }
{
"container_types": [
"The box is too small for these types: 20DC (up to 265567), 40HC (up to 265400). The limit is 2500 boxes per type."
],
"pallet_types": [
"The box is too small for these types: EUR1 (up to 10414), GMA (up to 12500). The limit is 500 boxes per type."
]
}
{ "pallet_types": ["Ensure this field has no more than 3 elements."] }
{
"package": {
"rotation": ["Use one or more of the letters L, W and H."]
}
}
{ "detail": "Authentication credentials were not provided." }
{ "detail": "The packing engine could not complete the request." }
See Troubleshooting if requests fail unexpectedly.