xload
XLoad Operations
SOAP/JSON
Synchronous API
since 2.3
Operation Name | Request Type | Response Type | Since | Description |
---|---|---|---|---|
packBins | PackBinsRequest | PackedBinsResponse | 2.3 | Performs a bin packing operation as described by the request. |
packPositionedBins | PackPositionedBinsRequest | PackedPositionedBinsResponse | (2.22) | Performs a positioned bin packing operation as described by the request.
This SOAP/JSON operation is experimental. Before using it, make sure you understand the implications of Experimental features. |
SOAP/JSON
Asynchronous API
since 2.3
Operation Name | Request Type | Response Type | Since | Description |
---|---|---|---|---|
startPackBins | PackBinsRequest | Job | 2.3 |
This is the asynchronous version of packBins. Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchPackedBinsResponse. If the job ended with status FAILED, fetchPackedBinsResponse throws the exception that occurred during calculation. |
startPackPositionedBins | PackPositionedBinsRequest | Job | (2.22) |
This is the asynchronous version of packPositionedBins. Calling this operation will not block until the result has been calculated. Instead of a result object, a Job object is returned which identifies the started calculation. To get status updates on a running job, use the operation watchJob. If it changes to SUCCEEDED, the calculation was successful and the result can be obtained using fetchPackedPositionedBinsResponse. If the job ended with status FAILED, fetchPackedPositionedBinsResponse throws the exception that occurred during calculation. This SOAP/JSON operation is experimental. Before using it, make sure you understand the implications of Experimental features. |
fetchPackedBinsResponse | JobRequest | PackedBinsResponse | 2.3 |
Fetches results of type PackedBinsResponse for the given job. If the calculation ended with an exception, fetchPackedBinsResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown. |
fetchPackedPositionedBinsResponse | JobRequest | PackedPositionedBinsResponse | (2.22) |
Fetches results of type PackedPositionedBinsResponse for the given job. If the calculation ended with an exception, fetchPackedPositionedBinsResponse will rethrow it. If the id of the job is unknown, a XServerException with message 'unknown id' is thrown. |
watchJob | WatchRequest | Job | 2.3 |
Returns the status of the given job. This operation behaves exactly like the watchJob operation of the xRuntime service. |
stopJob | JobRequest | Job | 2.3 |
Attempts to stop a running job. If the status of the job changes to SUCCEEDED, preliminary results can be fetched, if available. This operation behaves exactly like the stopJob operation of the xRuntime service. |
deleteJob | JobRequest | Job | 2.3 |
Attempts to delete a running job. If successful, the returned job will have state DELETED. This operation behaves exactly like the deleteJob operation of the xRuntime service. |
Types
Describes the allowed orientations for items. Depending on how an item is oriented, load will be applied on a different axis of the item if something is stacked on top of it. See ItemOrientation.
Defines the parameters along the axes.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
x | Dimension (Double) | no | 0.0 | (2.22) | Along the x-axis.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
y | Dimension (Double) | no | 0.0 | (2.22) | Along the y-axis.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
z | Dimension (Double) | no | 0.0 | (2.22) | Along the z-axis.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Specifies the maximum allowed overhang in centimeters, in each directions of the bin.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
front | Dimension (Double) | no | 0.0 | (2.22) | Overhang in front direction ; i.e. along in z-axis, in the front of the bin.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
rear | Dimension (Double) | no | 0.0 | (2.22) | Overhang in rear direction ; i.e. along in z-axis, in the rear of the bin.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
minimumFractionOfItemLengthInBin | Percent (Double) | no | 50.0 | (2.24) | Specifies the minimum fraction of the item length that should be in the bin if rear overhang is allowed. It influences the placement of the center of mass. By default it is located at the middle.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
minimumRearMarginForCenterOfMass | Dimension (Double) | no | 0.0 | (2.24) | Specifies the minimum margin to the rear of the bin by which the center of mass should not exceed. Rounded to nearest full centimeter internally.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Describes the position of a bin in a loading space. The coordinate system is right-handed with x extending to the right, y pointing up and z pointing towards you. In terms of a truck (0,0,0) would be at the lower-left-corner of the opposing wall when looking through the back doors.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
x | Dimension (double) | yes | - | (2.22) | Offset along x-axis. Equal to the shift along the width of the loading space from left to right. Rounded to nearest full centimeter internally.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
y | Dimension (double) | yes | - | (2.22) | Offset along y-axis. Equal to the height from the floor of the loading space. Rounded to nearest full centimeter internally.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
z | Dimension (double) | yes | - | (2.22) | Offset along z-axis. Equal to the shift along the length of the loading space from back to front. Rounded to nearest full centimeter internally.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Describes a cuboid bin type into which items can be packed.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
id | String | yes | - | 2.3 | User provided ID for this type of bin. Must be unique. |
numberOfBins | PositiveInteger (Integer) | no | 1 | 2.3 | Number of bins of this type available for packing. Maximum is 1000. |
dimensions | BoxDimensions | yes | - | 2.3 | Inner dimensions of a single bin of this type. Along each axis the dimension should be between 1 and 5750 cm. The maximum volume of a bin is 425.385 m³ . |
maximumVolumeCapacity | Volume (Double) | no | - | 2.3 | Maximum accumulated volume of items that can be packed into a single bin of this type irrespective of bin dimensions. This value must never exceed the natural inner volume specified by dimensions. If not given, defaults to the natural inner volume specified by dimensions. Internally rounded to nearest full cubic centimeter. |
maximumWeightCapacity | Kilograms (Double) | no | - | 2.3 | Maximum accumulated weight of items that can be packed into a single bin of this type. If not given the weight capacity is assumed to be infinite. Internally rounded to nearest full gram. The maximum allowed weight capacity is 80 t. |
Size of an item or bin. See ItemPosition for a description of the coordinate system.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
x | Dimension (double) | yes | - | 2.3 | Extent along x-axis (width). Rounded to nearest full centimeter internally. |
y | Dimension (double) | yes | - | 2.3 | Extent along y-axis (height). Rounded to nearest full centimeter internally. |
z | Dimension (double) | yes | - | 2.3 | Extent along z-axis (length). Rounded to nearest full centimeter internally. |
Describes the position of an object in the global space. The coordinate system is right-handed with x extending to the right, y pointing up and z pointing towards you. In this coordinate system, it is possible to have negative coordinates.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
x | double | yes | - | (2.22) | Offset along x-axis. Rounded to nearest full centimeter internally.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
y | double | yes | - | (2.22) | Offset along y-axis. Rounded to nearest full centimeter internally.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
z | double | yes | - | (2.22) | Offset along z-axis. Rounded to nearest full centimeter internally.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Describes a cuboid item which is to be packed into a bin.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
id | String | yes | - | (2.22) | User provided ID for this item. Must be unique.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
dimensions | BoxDimensions | yes | - | (2.22) | Outer dimensions of this item.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
priority | NonNegativeInteger (Integer) | no | 0 | (2.22) | Priority of this item compared to the others. The higher the priority is, the earlier the item is unloaded.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Describes the position of an item in a bin. The coordinate system is right-handed with x extending to the right, y pointing up and z pointing towards you. In terms of a truck (0,0,0) would be at the lower-left-corner of the opposing wall when looking through the back doors. An item, for example a palette, placed there would be on the ground. It would also touch the left wall as well as the wall towards the drivers cabin.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
x | Dimension (double) | yes | - | 2.3 | Offset along x-axis. Equal to the shift along the width of the bin from left to right. Rounded to nearest full centimeter internally. |
y | Dimension (double) | yes | - | 2.3 | Offset along y-axis. Equal to the height from the floor of the bin. Rounded to nearest full centimeter internally. |
z | Dimension (double) | yes | - | 2.3 | Offset along z-axis. Equal to the shift along the length of the bin from back to front. Rounded to nearest full centimeter internally. |
Describes the surface loads in kg/m² on an item acting on each of its axis. If an axis is not provided it is assumed to be irrelevant and/or non-restrictive.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
x | SurfaceLoad (Double) | no | - | 2.3 | Surface load acting on the x-axis (width) of the item. Internally rounded to nearest full g/cm² . |
y | SurfaceLoad (Double) | no | - | 2.3 | Surface load acting on the y-axis (height) of the item. Internally rounded to nearest full g/cm² . |
z | SurfaceLoad (Double) | no | - | 2.3 | Surface load acting on the z-axis (length) of the item. Internally rounded to nearest full g/cm² . |
Describes a cuboid item which is to be packed into a bin. If there are many identical items that do not have to be differentiated by individual ItemType.id you should use the ItemType.numberOfItems field. This provides better performance and packing than specifying each item on its own when this is not needed.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
id | String | yes | - | 2.3 | User provided ID for this item type. Must be unique. |
dimensions | BoxDimensions | yes | - | 2.3 | Outer dimensions of this item. Please note that the sum of each dimension (i.e. x+y+z) should be greater than 50 cm, and the maximum length of an item is 5000 cm. |
weight | Kilograms (double) | yes | - | 2.3 | Weight of this item. Internally rounded to nearest full gram. |
maximumSurfaceLoads | ItemSurfaceLoads | no | - | 2.3 | Maximum allowable load on this item. An item experiences load when other items are stacked on top of it. The load limit is defined for each axis as the item might be re-oriented. If not given no limitation based on surface load is made. |
allowedOrientations | AllowedItemOrientations | no | - | 2.3 | Allowed ways to orient this item when packing it into a bin. If not given all orientations will be allowed. |
numberOfItems | PositiveInteger (Integer) | no | 1 | 2.3 | Number of items of this type that should be packed. Maximum number is 10000. |
Defines the amount of items to unload.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
itemTypeId | String | yes | - | 2.15 | ID of the ItemType. |
numberOfItems | PositiveInteger (Integer) | no | 1 | 2.15 | The amount of items to unload. |
Allows customization of packBins operations.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
focus | PackBinsFocus | no | PackBinsFocus.BUI ... | 2.3 | Specifies the focus for this request. Can be used to guide algorithm behavior. |
unloadingSequence | Stop[] | 0..* | - | 2.15 | Specifies the sequence of Stop to unload. The first group will be unloaded first (and loaded last). By default items of a stop will not be stacked on top of items of the subsequent stop. This may be useful when unloading all items of a stop with a hand truck. To change this behavior specify 'stackOnTopOfNextStops' Please note that this option can be used if only one bin is defined. |
stackingOptions | StackingOptions | no | - | 2.15 | Specifies the stacking options to be considered during the packing algorithm. |
Specifies a packing problem consisting of a number of items of various types that get packed into a number of bins of various types. Items as well as bins are always of cuboid shape.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
items | ItemType[] | 1..1000 | - | 2.3 | List of item types that are to be packed into the given bins. |
bins | BinType[] | 1..100 | - | 2.3 | List of available bin types into which items can be packed. |
options | PackBinsOptions | no | - | 2.3 | Request specific options. |
Allows customization of packPositionedBins operations.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
spaceBetweenItems | AxesParameters | no | - | (2.22) | Specifies the space between the items in the bin.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
loadBalancingCriteria | LoadBalancingCriteria | no | LoadBalancingCrit ... | (2.22) | Enables the load balancing of items, depending of the criteria. By default, load balancing is not enabled.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Specifies a packing problem consisting of a number of items that get packed into a number of bins positioned at some locations in the space. Items as well as bins are always of cuboid shape.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
items | Item[] | 1..1000 | - | (2.22) | List of items that are to be packed into the given bins.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
bins | PositionedBin[] | 1..100 | - | (2.22) | List of available bins into which items can be packed.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
options | PackPositionedBinsOptions | no | - | (2.22) | Request specific options.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Describes a bin packed with items. If BinType.numberOfBins is greater than one, multiple packed bins with the same PackedBin.binTypeId might be part of a response.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
binTypeId | String | yes | - | 2.3 | ID of the BinType |
packedItems | PackedItem[] | 1..* | - | 2.3 | List of items that were packed into this bin. |
totalItemsVolume | Volume (double) | yes | - | 2.3 | Accumulated volume of the items packed into the bin. This is the raw sum and does not try to capture wasted volume (e.g. gaps). |
totalItemsWeight | Kilograms (double) | yes | - | 2.3 | Accumulated weight of items packed into this bin. |
usedWeightCapacity | Percent (Double) | no | - | 2.3 | Percent of BinType.maximumWeightCapacity used by PackedBin.totalItemsWeight. Not returned if no maximumWeightCapacity was given for bin. |
usedVolumeCapacity | Percent (double) | yes | - | 2.3 | Percent of BinType.maximumVolumeCapacity used by PackedBin.totalItemsVolume. If no explicit maximum volume is given it is calculated from the container dimensions. |
loadingMeters | LoadingMeter (double) | yes | - | 2.3 | Item extent along the z-axis (length) from the back wall of the bin. When looking through the back doors of a truck this is the distance from the opposing wall to the end of the load closest to the doors. |
Describes a packing solution.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
packedBins | PackedBin[] | 0..* | - | 2.3 | List with one entry for each bin that was used for packing items in this solution. |
itemsNotPacked | ItemType[] | 0..* | - | 2.3 | If some or part of the quantity of an item type specified in the PackBinsRequest could not be placed into a bin they are returned here. For example if you have 20 items of a type and only 15 could be packed you will find an ItemType in this list that has the same ID as the input type but with the number of items reduced to 5. Note that ItemType is the same type used for input in PackBinsRequest so remaining items can easily be used in further packing operations. |
Describes one item of a type that was packed into a PackedBin. If ItemType.numberOfItems is greater than one, multiple packed items with the same PackedItem.itemTypeId might be in a PackedBin.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
itemTypeId | String | yes | - | 2.3 | ID of the ItemType. |
position | ItemPosition | yes | - | 2.3 | ItemPosition of the item in the bin. |
dimensions | BoxDimensions | yes | - | 2.3 | Packed item dimensions after orientation. |
orientation | ItemOrientation | yes | - | 2.3 | ItemOrientation with which the item was placed in the bin. |
Describes a positioned bin packed with items.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
binId | String | yes | - | (2.22) | ID of the bin
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
packedItems | PackedPositionedItem[] | 1..* | - | (2.22) | List of items that were packed into this bin.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Describes a packing solution.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
packedBins | PackedPositionedBin[] | 0..* | - | (2.22) | List with one entry for each bin that was used for packing items in this solution.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
itemsNotPacked | String[] | 0..* | - | (2.22) | List of items that could not be packed in the bins.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Describes one item of a type that was packed into a PackedPositionedBin.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
itemId | String | yes | - | (2.22) | ID of the Item.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
position | GlobalPosition | yes | - | (2.22) | Position of the item in the global space. Please note that coordinates can be negative due to an overhang constraint.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Describes a bin of a specific type at a position in the loading space.
This type is experimental. Before using it, make sure you understand the implications of Experimental features.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
id | String | yes | - | (2.22) | User provided ID for this type of bin. Must be unique.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
position | BinPosition | yes | - | (2.22) | Specifies the absolute position of the bin.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
dimensions | BoxDimensions | yes | - | (2.22) | Inner dimensions of a single bin of this type. Along each axis the dimension should be between 1 and 5000 cm. The maximum volume of a bin is 425.385 m³ .
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
overhang | BinOverhang | no | - | (2.22) | Specifies the maximum allowed overhang in centimeters of the bin.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
minimumItemLengths | AxesParameters | no | - | (2.22) | Specifies the minimum length in centimeters the item has to respect to be loaded in the bin.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
loadingSide | LoadingSideType | no | LoadingSideType.B ... | (2.22) | Specifies the loading side of the items in the bin. By default the items can be loaded on both sides of the bin.
This field is experimental. Before using it, make sure you understand the implications of Experimental features. |
Defines all stacking options to be considered during the packing algorithm.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
stackingRestrictions | StackingRestrictions[] | 0..* | - | 2.15 | Defines all the stacking restrictions between ItemType. |
stackOnTopOfNextStops | Boolean | no | false | 2.31 | Specifies if it is allowed to stack items of a stop above items of the next stops. Only relevant if unloadingSequence is used. |
Define the stacking restriction for one ItemType. Specifies which ItemType are allowed or prohibited to be stacked on the current ItemType.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
itemTypeId | String | yes | - | 2.15 | ID of the ItemType. |
restrictionType | StackingRestrictionType | no | StackingRestricti ... | 2.15 | The type of restriction. Defines the restriction between StackingRestrictions.itemTypeId and StackingRestrictions.itemTypeIds. By default, every ItemType can be stacked on the current ItemType. |
itemTypeIds | String[] | 0..* | - | 2.15 | Specifies the list of ItemType.id to which the restriction applies. |
Defines the list of items to be unloaded at this point.
Field Name | Type | Required | Default | Since | Description |
---|---|---|---|---|---|
itemsToUnload | ItemsToUnload[] | 1..* | - | 2.15 | Defines the list of items to unload. |
Enumerates possible orientations. This is the full set of orientations that can lead to a unique shape of a cuboid object. Note that as only the shape is considered, things like whether an item is upside down have no influence on its orientation in this model. While we named the orientations, it might be simpler thinking of them as discrete orientations with no deeper meaning.
Defines the load balancing criteria.
This enumeration is experimental. Before using it, make sure you understand the implications of Experimental features.
Enumeration Value | Since | Description |
---|---|---|
NONE | (2.22) | No load balancing.
This enumeration value is experimental. Before using it, make sure you understand the implications of Experimental features. |
HEIGHT | (2.22) | The height of the items inside a bin is the criteria for the load balancing.
This enumeration value is experimental. Before using it, make sure you understand the implications of Experimental features. |
Defines the loading side of the items.
This enumeration is experimental. Before using it, make sure you understand the implications of Experimental features.
Enumeration Value | Since | Description |
---|---|---|
BOTH_SIDES | (2.22) | Each item can be loaded either by the left or right side.
This enumeration value is experimental. Before using it, make sure you understand the implications of Experimental features. |
LEFT_SIDE | (2.22) | Each item has to be loaded by the left side only.
This enumeration value is experimental. Before using it, make sure you understand the implications of Experimental features. |
RIGHT_SIDE | (2.22) | Each item has to be loaded by the right side only.
This enumeration value is experimental. Before using it, make sure you understand the implications of Experimental features. |
Algorithmic focus for the packBins function.
Defines the stacking restrictions.
Enumeration Value | Since | Description |
---|---|---|
ALL_ALLOWED | 2.15 | All ItemType can be stacked on top of the current one. Moreover, every items of the same ItemType can be stacked on top of the current one. |
ALL_PROHIBITED | 2.15 | All ItemType can not be stacked on top of the current one. Moreover, even items of the same ItemType can not be stacked on top of the current one. |
ALLOWED | 2.15 | Every listed ItemType can be stacked on top of the current one. |
PROHIBITED | 2.15 | Every listed ItemType can not be stacked on top of the current one. |