Swarm Logistics PlanSim
REST API
Version 1.3.16
1 General
description of functionality
1.2 Definition
of tasks and execution of calculations
1.3 Execution
control and tracking
6.2.1 General
CSV data and format
6.2.2 Field
names of format type FREIGHTORDERS
6.2.3 Field
names of format type TRANSPORTS
Swarm Logistics PlanSim
REST API
Version 1.3.16
The PlanSim server
generates tour plans freight order given vehicles and freight orders.
In a first step the required base data has to be set up. These data consist of drivers
("Driver" resource), vehicles („Truck“ and
„car“ resources), optionally trailers („Trailer“ resource), and the freight
orders ("FreightOrder" resource). A vehicle
of some type, a driver and optionally a trailer in combination define a
transport („Transport“ resource). Freight orders
always get assigned to transports in the result („result“
resource) to be calculated.
In the second step a task („Task“
resource) has to be defined. It holds information on what transports are
available, and what freight orders need to get planned.
An important part of the base data consists of the
addresses („Address“ resource). The addresses are used
to define the pickup and delivery locations of the freight orders. Further they
are used to define the home base of individual vehicles. The location of a home
base is assumed to be the start and end of each tour of a transport that has
this vehicle assigned. Thus all tours always become
round trips.
After set up of the base data calculations can be
started by POST requests of the „Calculation“ resource.
Processing of calculations can take up to several minutes. Because of that the
POST immediately returns a structure containing an id. By this id subsequent
GET request of the „Calculation“ resource can be
issued in order to receive the current status of the calculation process. So the client has to execute some polling. Sensibly the
polling requests should have intervals of at least 10 seconds. As soon as the
calculation is done the GET request of the „Calculation“
resource delivers the id of a corresponding result instance („result“
resource). The result represents the result of the calculation and thus the
generated tour plan.
The client can trigger the execution of a
previously generated tour plan by a POST to the „Execution“
resource.
In order to support tracking of the execution state of previously generated
tour plans the API supports feedback means by the individual transports and a
possibility to query possible conflicts. A transport can report ‘beacon’ data
containing information on its current time and place and optionally ongoing
action, and additionally a full report on the execution state of its assigned
tour plan. This can either be done directly by the transport or by proxy of a
central client user.
Route
“/csv”
Example
https://localhost/AutoDispatcher/v1.3/csv
Invalid request type. The server rejects any such
request since uploaded csv data gets processed immediately after upload and
afterwards gets deleted. Thus it cannot get retrieved.
Results
405 - not allowed
Invalid request type. The server rejects any such
request since uploaded csv data gets processed immediately after upload and
afterwards gets deleted. Thus it cannot get changed.
Results
405 - not allowed
Upload CSV (‘comma separated values’) formatted data as file content. See the expected CSV data format in the annex (see 6.2 CSV upload format). The body is expected to contain form data (header “Content-Type: multipart/form-data;”) with the following fields.
·
(mandatory) reference to the file data which will
be resolved on send by the client
form-data; name="file";
filename="some-filename.csv"
Content-Type: text/csv
·
(mandatory) CSV content type - must be either
FREIGHTORDERS or TRANSPORTS
Content-Disposition: form-data; name="format"
·
(optional) a freetext
comment describing the import process
Content-Disposition: form-data; name="comment"
Results
The body of the response will contain JSON data describing the results
of the import (including possible errors). It will be an array containing one
object per imported object. This can be something like e. g.:
{
"id":
"0xho4jikjohh6jflj736nk5l8mk4lf4i8ffg6n4gj",
"format":
"FREIGHTORDERS",
"time":
"2022-03-29T14:20:39.665279Z",
"results": [{
"idImport":
"1",
"error": false,
"comment":
"Pickup",
"importedId":
"2lhh48jg75fi55h7j36j3k7ln8ffgfl74fkjfk84x",
"importedType":
"Address"”
}, {
"idImport":
"10",
"error": false,
"comment":
"Delivery",
"importedId":
"gahj8om84okij7mfjj5h33o35ll5ffgl6o6ggh8rz",
"importedType":
"Address"
}, {
"idImport":
"10",
"error": false,
"comment": "",
"importedId":
"7vhoff6i787jlf8lj443o85hmgg4nl5joffgkgomo",
"importedType":
"FreightOrder"
}],
“errors”: false
}
HTTP return codes can be these
201 – upon successful upload
422 – if the supplied data in the body cannot get processed
Invalid request type. The server rejects any such
request since uploaded csv data gets processed immediately after upload and
afterwards gets deleted automatically.
Results
405 - not allowed
Route
“/driver”
Example
https://localhost/AutoDispatcher/v1.3/driver/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing driver instances if the id in
the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved
"Driver" data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Changes the instance data of the given id. The
request body must supply a validly filled "Driver" data structure
that will be set if an entry by the supplied id can be found.
Results
200 - body carries a copy of the resulting /
changed entry, see "Driver" data structure below
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Creates a new instance. The request body must supply a validly filled "Driver" data structure that will be set onto the newly created entry.
Results
200 - body carries a copy of the resulting /
changed entry if an id was supplied, see "Driver" data structure
below
201 - body carries a copy of the newly created
entry including its assigned id
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/car”
Example
https://localhost/AutoDispatcher/v1.3/car/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing car instances if the id in the
URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Car“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Changes the instance data of the given id. The
request body must supply a validly filled „Car“ data
structure that will be set if an entry by the supplied id can be found.
Results
200 - body carries a copy of the resulting /
changed entry, see „car“ data structure below
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Creates a new instance. The request body must supply a validly filled "Car" data structure that will be set onto the newly created entry.
Results
200 - body carries a copy of the resulting /
changed entry if an id was supplied, see „Car“ data
structure below
201 - body carries a copy of the newly created
entry including its assigned id
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
„/truck”
Example
https://localhost/AutoDispatcher/v1.3/truck/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing truck instances if the id in
the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Truck“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Changes the instance data of the given id. The
request body must supply a validly filled „Truck“ data
structure that will be set if an entry by the supplied id can be found.
Results
200 - body carries a copy of the resulting /
changed entry, see „Truck“ data structure below
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Creates a new instance. The request body must supply a validly filled "Truck" data structure that will be set onto the newly created entry.
Results
200 - body carries a copy of the resulting /
changed entry if an id was supplied, see „Truck“ data
structure below
201 - body carries a copy of the newly created
entry including its assigned id
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/trailer”
Example
https://localhost/AutoDispatcher/v1.3/trailer/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing trailer instances if the id in
the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Trailer“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Changes the instance data of the given id. The
request body must supply a validly filled „Trailer“ data
structure that will be set if an entry by the supplied id can be found.
Results
200 - body carries a copy of the resulting /
changed entry, see „Trailer“ data structure below
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Creates a new instance. The request body must supply a validly filled "Trailer" data structure that will be set onto the newly created entry.
Results
200 - body carries a copy of the resulting /
changed entry if an id was supplied, see „Trailer“ data
structure below
201 - body carries a copy of the newly created
entry including its assigned id
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/transport”
Example
https://localhost/AutoDispatcher/v1.3/transport/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing transport instances if the id
in the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Transport“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Changes the instance data of the given id. The
request body must supply a validly filled „Transport“ data
structure that will be set if an entry by the supplied id can be found.
Results
200 - body carries a copy of the resulting /
changed entry, see „Transport“ data structure below
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Creates a new instance. The request body must supply a validly filled "Transport" data structure that will be set onto the newly created entry.
Results
200 - body carries a copy of the resulting /
changed entry if an id was supplied, see „Transport“ data
structure below
201 - body carries a copy of the newly created
entry including its assigned id
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/address”
Example
https://localhost/AutoDispatcher/v1.3/address/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing address instances if the id in
the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Address“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Changes the instance data of the given id. The
request body must supply a validly filled „Address“ data
structure that will be set if an entry by the supplied id can be found.
Results
200 - body carries a copy of the resulting /
changed entry, see „Address“ data structure below
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Creates a new instance if no matching entry is found. In any case the request body must supply a validly filled „Address“ data structure that will be used to find a match or to set for a newly created entry if no match is found. In order to find a match the street name, street number, address info, zip code and city name get compared. This means that other properties of the „Address“ data structure like contact and location are ignored, and that in the case that a match is found the contact and location properties are taken from the found entry and not from the supplied body. To change an existing entry the PUT method must be used.
Results
200 - body carries a copy of a found matching entry
201 - body carries a copy of the newly created
entry including its assigned id
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/freightorder”
Example
https://localhost/AutoDispatcher/v1.3/freightorder/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing freight order instances if the
id in the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved data structure (see below) or a list
thereof.
404 - if no data found by the supplied id
Changes the instance data of the given id. The
request body must supply a validly filled data structure that will be set if an
entry by the supplied id can be found.
Results
200 - body carries a copy of the resulting /
changed entry, see
data structure below
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Creates a new instance. The request body must supply a validly filled "FreightOrder" data structure that will be set onto the newly created entry.
Results
200 - body carries a copy of the resulting /
changed entry if an id was supplied, see "FreightOrder"
data structure below
201 - body carries a copy of the newly created
entry including its assigned id
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/task”
Example
https://localhost/AutoDispatcher/v1.3/task/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing task instances if the id in
the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Task“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Invalid request type. The server rejects any such
request.
Results
405 - not allowed
Creates a new instance. The request body must supply a validly filled "Task" data structure that will be set onto the newly created entry.
Results
200 - body carries a copy of the resulting /
changed entry if an id was supplied, see „Task“ data
structure below
201 - body carries a copy of the newly created
entry including its assigned id
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/calculation”
Example https://localhost/AutoDispatcher/v1.3/calculation/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing calculation instances if the
id in the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Calculation“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Invalid request type. The server rejects any such
request.
Results
405 - not allowed
Creates a new instance. The request body must supply a validly filled "Calculation" data structure that will be set onto the newly created entry.
Results
201 - body carries a copy of the newly created
entry including its assigned id, see „Calculation“ data
structure below
405 - if an id was supplied
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. If it is
still running, it gets aborted first.
Any data in the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/result”
Example
https://localhost/AutoDispatcher/v1.3/result/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing result instances if the id in
the URL is omitted.
Any supplied body gets ignored.
Results
200 – body carries the retrieved „Result“ data structure (see below) or a list thereof.
404 – if no data found by the supplied id
500 – if some error occurred during PDF generation
/ processing
Supported formats
Subroutes
Invalid request type. The server rejects any such
request.
Results
405 - not allowed
Invalid request type. The server rejects any such
request.
Results
405 - not allowed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/clustering”
Example
https://localhost/AutoDispatcher/v1.3/clustering/cc90b3a70f1c4271b5f95a48342f4008
Invalid request type. The server rejects any such
request.
Results
405 - not allowed
Invalid request type. The server rejects any such
request.
Results
405 - not allowed
Supplies a list of orders and parameters defining how to cluster these orders. The request body must supply a validly filled ClusteringTask data structure – see 5.25 . This request does not persist any data, neither input data nor result data.
Results
201 - body carries the result of the clustering, see 5.26 ClusteringResult data structure
422 - if the supplied data in the body cannot get
processed
Invalid request type. The server rejects any such
request.
Results
405 - not allowed
Route
“/execution”
Example
https://localhost/AutoDispatcher/v1.3/execution/cc90b3a70f1c4271b5f95a48342f4008
Returns the data of the entry identified by the
instance id in the URL or a list of all existing execution instances if the id
in the URL is omitted.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Execution“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Changes the instance data of the given id. The
request body must supply a validly filled „Execution“ data
structure that will be set if an entry by the supplied id can be found.
Results
200 - body carries a copy of the resulting /
changed entry, see „Execution“ data structure below
404 - if no data found by the supplied id
422 - if the supplied data in the body cannot get
processed
Creates a new instance. The request body must supply a validly filled "Execution" data structure that will be set onto the newly created entry. The field „idResult“ must be filled with the id of the previously calculated tour plan (see “Result” resource). The state of the new execution instance is ‘created’.
Results
201 - body carries a copy of the newly created
entry including its assigned id, see „Execution“ data
structure below
405 - if an id was supplied
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/beacon”
Example
https://localhost/AutoDispatcher/v1.3/beacon/cc90b3a70f1c4271b5f95a48342f4008
Returns either
◦
idExecution:
(mandatory) UID of the execution instance of which to return the beacons
◦
idTransport:
(optional) UID of the transport of which to return the beacons
Any supplied body gets ignored.
Results
200 - body carries the retrieved „Beacon“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Invalid request type. The server rejects any such
request since beacon data is immutable.
Results
405 - not allowed
Creates a new instance. The request body must supply a validly filled "Beacon" data structure that will be set onto the newly created entry. The field „idExecution“ must be filled with the id of an existing and running execution instance (see “Execution” resource), and the field “idTransport” filled with the id of the transport to which the beacon data applies.
Results
201 - body carries a copy of the newly created
entry including its assigned id, see „Beacon“ data
structure below
405 - if an id was supplied
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/executionstate”
Example
https://localhost/AutoDispatcher/v1.3/executionstate/cc90b3a70f1c4271b5f95a48342f4008
Returns either
◦ idExecution: (mandatory) UID of the execution instance of which to return the execution states
◦ idTransport: (optional) UID of the transport of which to return the execution states
Any supplied body gets ignored.
Results
200 - body carries the retrieved „ExecutionState“
data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Invalid request type. The server rejects any such
request since execution state data is immutable.
Results
405 - not allowed
Creates a new instance. The request body must supply a validly filled "ExecutionState" data structure that will be set onto the newly created entry. The field „idExecution“ must be filled with the id of an existing and running execution instance (see „Execution“ resource), and the field “idTransport” filled with the id of the transport to which the execution state data applies.
Results
201 - body carries a copy of the newly created
entry including its assigned id, see „ExecutionState“ data structure below
405 - if an id was supplied
422 - if the supplied data in the body cannot get
processed
Deletes the instance of the given id. Any data in
the request body gets ignored.
Results
200 - if the entry was found and got deleted
successfully
404 - if no data found by the supplied id
Route
“/conflicts”
Example
https://localhost/AutoDispatcher/v1.3/conflicts/cc90b3a70f1c4271b5f95a48342f4008
Returns the conflicts data of the execution instance id supplied in the URL. The requested data can further be specified by supplying the optional query parameter “idTransport” which is the UID of a transport of which possible conflicts data is to be returned.
Any supplied body gets ignored.
Results
200 - body carries the retrieved „conflicts“ data structure (see below) or a list thereof.
404 - if no data found by the supplied id
Invalid request type. The server rejects any such
request since conflicts data cannot be set.
Results
405 - not allowed
Invalid request type. The server rejects any such
request since conflicts data cannot be set.
Results
405 - not allowed
Invalid request type. The server rejects any such
request since conflicts data cannot be deleted.
Results
405 - not allowed
The JSON data generally follows the “Google JSON Style Guide” (see here: https://google.github.io/styleUIDe/jsoncstyleUIDe.xml).
All native types have to
be supplied as strings holding data in a certain format.
UID – a string containing a unique
identification value e. g. "ovfgkffgi33g734jg8nj83n4l36okjng8kfnk4m47"
string - any
string value
double - a
floating point value with a point as comma e. g. „3.141“
int - an integer e. g. „1234“
boolean
- a boolean value of either „false“
or „true“
arrays are shown
by square brackets like this: [ ]
{
"id" : UID, // id of this
address instance
"location" : Coordinates, //
geological coordinates of this address, see Coordinates structure
"contact" : string, // free
text, name of the contact this address is attached with
"streetName"
: string, // name of the street
"streetNo"
: string, // street number
"addInfo"
: string, // additional address information, e. g. „c/o“
"zip" : string, // postal
ZIP of the city
"city" : string, // city
name
}
{
"id" : UID, // id of this
driver instance
"description" : string, //
"some free text describing the instance here"
"cph"
: double, // costs of this driver in euro per hour
"pauseDurationMinutes"
: int, // duration of the pause of this driver in minutes, default: 60
"pauseAfterWorkedMinutes"
: int, // duration of work time in minutes after which driver must
// pause, default:
240
"workDurationMaxMinutes"
: int // total work duration in minutes of this driver (pauses
// excluded),
default: 480
}
{
"id" :
UID, // id of this truck instance
"description" : string, // some free
text describing the instance here
“subType” :
string, // sub type of truck, can be “75” for 7.5 tons truck, or “16” for 16
tons,
// or “25” for 25
tons, or “44” for 44 tons
"idAddressHomedepot" : UID, //
id of the address used as home depot of this truck
"capacityWeight" : double, // maximum weight capacity
in kilograms
// that can be used
for loading freight
„capacitySpace"
: double, // maximum space capacity in cubic meters
// that can be used
for loading freight
"cph"
: double, // time dependent costs of this vehicle in euro per hour
"cpkm"
: double, // distance dependent costs in euro per driven kilometer without any
// freight – a.k.a.
“empty load distance costs”
“cpkmload” :
double, // distance dependent costs in euro per driven kilometer when the
// weight capacity is
maxed out – a. k. a. “full load distance costs”
"fixCosts"
: double, // override value freight order fix costs in euro per year
"roadChargePKm"
: double, // override value freight order applicable road charge in euro
// per km
"emissionClass"
: int, // emission class of this truck, used freight order calculation of toll
// costs; but only
relevant if no road charge override is enabled and set
// possible
values:
// 0 - (A) - Euro 6 / S6
//
1 - (B) - Euro 5 / EEV 1 / S5
// 2 - (C) - Euro
4 / Euro 3 + PMK 2* / S4 / S3 + PMK 2*
// 3 - (D) - Euro
3 / Euro 2 + PMK 1* / S3 / S2 + PMK 1*
// 4 - (E) - Euro
2 / S2
// 5 - (F) - Euro
1 / Euro 0 / S1 / keine SSK
"axleCount"
: int, // count of axles on this truck, used freight order calculation of toll
costs;
// but only
relevant if no road charge override is enabled and set
“axleWeight”
: double, // maximum allowed weight in metric tons per axle
“permissibleTotalMass”
: double, // maximum total allowed weight in metric tons for the truck
“height” : double, // height of truck
in meters; default: 4.0
“width” : double, // width of truck in
meters; default: 2.5
“weight” : double, // weight of truck
in metric tons; default: 7.5
“length” : double, // length of truck
in meters; default: 10.0
“hazmat” : boolean
// true if the truck transports hazardous goods, otherwise false
}
{
"id" : UID, // id of this
car instance
"description" : string, //
some free text describing the instance here
"idAddressHomedepot"
: UID, // id of the address used as home depot of this car
"capacityWeight"
: double, // maximum weight capacity in kilograms
// that can be used
for loading freight
„capacitySpace"
: double, // maximum space capacity in cubic meters
// that can be used
for loading freight
"cph"
: double, // override value freight order costs in euro per hour
"cpkm"
: double, // override value freight order costs in euro per driven kilometer
"fixCosts"
: double // override value freight order fix costs in euro per year
}
{
"id" : UID, // id of this
trailer instance
"description" : string, //
some free text describing the instance here
"capacityWeight"
: double, // maximum weight capacity in kilograms
// that can be used
for loading freight
„capacitySpace"
: double, // maximum space capacity in cubic meters
// that can be used
for loading freight
"cph"
: double, // value freight order costs in euro per hour
"cpkm"
: double, // value freight order costs in euro per driven kilometer
"fixCosts"
: double, // value freight order fix costs in euro per year
"axleCount"
: int // count of axles on this truck, used freight order calculation of toll
costs;
// but only
relevant if no road charge override is enabled and set on the truck
// or if the
moving vehicle is a car
}
{
"id" : UID, // id of this
transport instance
"description" : string, //
some free text describing the instance here
"idDriver"
: UID, // Id of the driver instance assigned to this transport
"idVehicle"
: UID, // Id of the vehicle instance assigned to this transport,
// i. e. id of either car or truck
"idTrailer"
: UID, // Id of the trailer instance assigned to this transport, can be ignored
// if transport
does not have a trailer
"handlingDurationModifier"
: double, // modifying factor freight order pickup / delivery
// handling by
driver; e. g. „2.0“ freight order slower handling or „0.8“ freight
// order slightly
faster handling; default is "1.0"
“maxFoDistance”
: double // Maximum distance in kilometers from
transport start up to
//
which to consider offered FOs.
}
{
"id" : UID, // id of this
freight order instance
"customId"
: string, // some free text describing the instance here
"weight" : double, //
weight in kilograms of the freight
"space" : double, // space
in cubic meters of the freight
"idAddressPickup"
: UID, // id of the address used as pickup location
"idAddressDelivery"
: UID, // id of the address used as delivery location
"twPickup"
: int[2], // two values defining the pickup time window of this freight order
// twPickup[0] - earliest possible time in minutes after
midnight,
// not allowed to be smaller than 0 (i. e. 00:00 h)
// twPickup[1] - latest allowable time in minutes after
midnight,
// not allowed to be greater than 1439 (i. e. 23:59 h)
"twDelivery"
: int[2], // two values defining the
delivery time window of this freight order
// twDelivery[0] - earliest possible time in minutes after
midnight,
// not allowed to be smaller than 0 (i. e. 00:00 h)
// twDelivery[1] - latest allowable time in minutes after
midnight,
// not allowed to be greater than 1439 (i. e. 23:59 h)
"handlingDurationPickup"
: int, // duration in minutes defining how long the pickup
// procedure takes
"handlingDurationDelivery"
: int // duration in minutes defining
how long the delivery
// procedure takes
}
{
"id" : UID, // id of this task instance
"description" : string, // free text,
defining the task
"transports" : UID[ ], // ids of all
transport available freight order transporting the given freight
// orders
"fos" : UID[ ], // ids of all freight orders to be transported
“timeBegin” : String, // planned
begin time; timestamp in UTC including timezone
// information, e.
g. “2011-12-03T10:15:30+01:00”
“timeBeginIsHoliday”
: boolean, // true if the begin day is a
national/regional holiday
// false if the
begin day is not a national/regional holiday
"empStopsPerTransport" : int,
// (optional)
//
an empirical hint value defining how many stops a transport will
//
get assigned in the result; used freight order speeding up the calculation.
// Default is „0“ which means to ignore this setting.
“initialStrategyMinTransports” :
String, // (optional) strategy used to minimize the count of
// employed
transports; must be one of these values:
// ‘affinity’ –
(default) mediator determines assignments of orders to transports
//
‘vertical’ – mediator tries to ‘fill up’ transports before trying to assign
orders
// to another transport
//
‘horizontal’ – mediator tries to achieve an even assignment of orders among
// the available transports
//
‘auto’ – automatic logic that uses a (in respect to calculation time costly)
// branch-and-bound approach to find the
minimal count of transports
//
‘disabled’ – do not try to minimize the count of agents
“initialRoutetype” : String //
(optional) type of route planning to employ during generation
//
of an initial theoretical solution; must be one of these values:
//
‘static’ – (default) paths, distances, durations are planned by (fast) static
// requests
//
‘dynamic’ – paths, distances, durations are planned by (slow) dynamic
// requests; but since the theoretical
solution later in the solving process
// needs to get resolved by dynamic routing
requests, for smaller problem
// sets initial dynamic routing might result
in better results since then a
// plethora of parameters get considered
early
//
‘mixed’ – distance gets estimated first based on a quick calculation.
// If the estimated distance is larger than a
preset value then static routing
// is employed, but if it is less or equal to
that preset value then dynamic
// routing is employed.
“routetypeMixedThreshold” : double,
// (optional) threshold factor for ‘mixed’ route type;
//
the default is 25.0
“initialResolutionEnabled” : boolean, // (optional) defines activation state of details
//
resolution after initial theoretical tour planning; default is ‘true’
“optimizationNegotiationEnabled” : boolean, // (optional) defines activation state of agent
//
optimization negotiation (‘optiloop’); default is
‘false’
“generateInstructions” : boolean, // (optional) if true (default) then generate
driving
//
instructions which get added to the final result;
// if false then do not generate driving instructions; turning instructions
//
generation off speeds the result generation a bit up
“clusteringMethod”
: String // (optional) type of method to employ for clustering orders
// ‘classify’ –
classify the task to automatically determine a fitting method
// ‘centerpoints’ – cluster by using a center point between
pickup and delivery
// location of an order; or for service orders
use the service location
// ‘connectors’ –
(default) cluster using all locations (pickup and delivery) and
// then create sets of orders that determine
if an order is included in a cluster
// with all its locations (pickup and
delivery; or for service orders only delivery)
// or if each location is mapped to a
different cluster thus the order becoming
// a so-called ‘connector’ order
// ‘sectors’ –
cluster by determining multinodes (pickup or
delivery; ‘roots’) and
// then create a distinct number of sectors
(‘areas’) going out from each root
// where each one holds a disjunctive set of
orders.
}
{
"id" : UID, // id of this
calculation instance
"idTask"
: UID, // id of the task freight order which this is a calculation instance
"state" : String, // status
of the calculation; will be one of these:
// „running“ - if calculation
is in progress
// „finished“ - if calculation
ended / is complete
// „failed“ - if an internal
error occurred and thus the calculation got aborted
"idResult"
: UID // holds the id of the Result instance once the calculation finished
}
{
"id" : UID, // id of this
result instance
"idTask"
: UID, // id of the original task freight order which this is a calculation
result
"quality" : double, //
absolute quality measure of this result, lower values are better
"schedules" : Schedule[ ],
// schedule of each transport, see Schedule structure
"unservicedFos"
: UID[ ] // list of ids of all freight orders that could not get planned
// into any
schedule
}
{
"idTransport"
: UID, // id of the transport instance to which this schedule belongs
"costsDistance"
: double, // costs in euro that are caused by driven distance
"costsDuration"
: double, // costs in euro that are caused by duration of the schedule
“costsDeploy”
: double, // costs that are caused by deploying (i.
e. using) the transport
“costsFixed”
: double, // the applied fixed costs
“costsToll”
: double, // costs that are caused by driving on toll applicable roads
"costsTotal"
: double, // total costs in euro (sum of distance costs, duration costs, deploy
// costs, fixed costs, and
toll costs)
“totalDistance”
: double, // total driven distance of the schedule in kilometers (includes toll
// distance)
“tollDistance”
: double, // distance driven on toll applicable ways; this value will be zero
if
// the vehicle of the
transport does not have toll-costs-per-km or it is zero
“totalDuration”
: int, // total duration of the schedule in minutes
"timeStart"
: int, // time when the schedule begins,
// value is in
minutes after midnight,
// not allowed to be smaller than 0 (i. e. 00:00 h)
"timeEnd"
: int, // time when the schedule ends,
// value is in
minutes after midnight,
// not allowed to be greater than 1439 (i. e. 23:59 h)
"nodes" : Node[ ], // a
sequential list of nodes that make up the schedule,
// see Node
structure
}
Note that the time values (i.
e. properties “timeElapsedArrival”, “timeBeginService”, “timeElapsedDeparture”,
“timePauseBegin”, “timePauseEnd”)
define elapsed minutes after midnight (00:00 h) of the day the schedule begins.
This means that the values should be in the range of [ 0 ..
1439 )
{
"id" : UID, // id of this
result instance
"idFo"
: UID, // id of the freight order getting picked up or delivered at this node
"isPickup"
: boolean, // true if freight gets picked up, false
if it gets delivered
"weightBefore"
: double, // total loaded freight weight in kg at arrival at this node
"weightAfter"
: double, // total loaded freight weight in kg at departure from this node
"spaceBefore"
: double, // total space used up by freight in m³ at arrival at this node
"spaceAfter"
: double, // total space used up by freight in m³ at departure from this node
"timeElapsedArrival"
: int, // timestamp of arrival at this node (minutes after midnight)
"timeBeginService"
: int, // timestamp of service begin at this node (minutes after midnight)
"timeElapsedDeparture"
: int, // timestamp of departure from this node (minutes after
// midnight)
"distDetour"
: double, // detour distance in meters caused by this node
"durationDetour"
: double, // detour duration in minutes caused by this node
"timePauseBegin"
: int, // if driver pauses at this node, timestamp defining when a
// scheduled pause begins
(minutes after midnight)
"timePauseEnd"
: int, // if driver pauses at this node, timestamp defining when a scheduled
// pause ends (minutes after
midnight)
"pausePosition"
: int, // code that defines if a driver pause is scheduled at this node, and if
// if so at which phase.
Possible values
// 0 - no pause scheduled at
this node
// 1 - pause before arrival
// 2 - pause between arrival
and (before) service
// 3 - pause between service
and (before) departure
"distance" : double, //
distance in meters between previous node and this node
"duration" : double, //
duration in minutes between previous node and this node
"ascend" : double, //
ascend in meters between previous node and this node
"descend" : double, //
descend in meters between previous node and this node
"path" : Coordinates[ ], //
sequential coordinates making up the route,
// see Coordinates structure
"instructions" :
Instruction[ ], // sequential list if driving instructions, see Instruction
structure
"toll" : Toll[ ] //
sequential list of toll sections, see Toll structure
}
{
"distance" : double, //
distance in meters to drive according to this instruction
"duration" : double, //
time in minutes to drive according to this instruction
"code" : int, // code
indicator of what to do, can be one of these
// -2 - turn left
// 0 - drive straightly onward
// 2 - turn right
// 4 - destination reached
// 6 - enter the roundabout
"street" : string, //
street name to which the instruction applies to
"indexCoordsBegin"
: int, // zero-based index in coordinates field („Path“) defining where
// the instruction
starts; inclusive
"indexCoordsEnd"
: int, // zero-based index in coordinates field („Path“) defining where the
// instruction
ends; non-inclusive
"instruction" : string //
instruction as a human readable text
}
{
"type" : boolean, // either „true“ if the given interval defines a
path where toll applies or
// „false“ if the
given interval defines a path where no toll applies
"begin" : int, //
zero-based index in coordinates field („Path“) defining where the
// toll / no-toll
section starts; inclusive
"end" : int // zero-based
index in coordinates field („Path“) defining where the
// toll / no-toll
section ends; non-inclusive
}
{
"lon" : double, // coordinate longitude value
"lat"
: double // coordinate latitude value
}
{
"id" : UID, // id of
this execution instance
“idResult” :
UID, // id of the result instance which is the base of this execution
“state” : string // process state of
this execution instance
// can be one of these:
// created – the instance was
created but not yet started
// running – the instance got
started previously and gets executed currently
// completed – the plan on which
the instance was based on got executed successfully
// failed – during the execution
one or more critical failures occurred which is why the
//
execution failed
}
{
“id” : UID, // id of this beacon
instance
“idExecution”
: UID, // id of the execution instance to which this beacon belongs
“idTransport”
: UID, // id of the transport to which this beacon belongs
“location” : Coordinates, //
geographical location to which this beacon applies
“timestamp” : int, // timestamp in UTC
applicable to this beacon
“eventType”
: string, // type of event happening at this beacon; can be one of these:
// trivial – no event but simply
location and timestamp; payload is empty/null
// plan – payload carries an object
of type “FOEvent”
// extra – payload is of type string and
explains an extraordinary event
“payload” : type depends on value of
field “EventType” (see above)
}
{
“idFo” :
UID, // id of the freight order instance to which this plan event applies
“action” : string, // defines the
event’s action verb applicable to the specified freight order:
// pickup - the freight order gets
picked up
// delivery - the freight order
gets delivered
// service - the service identified
by the freight order id is executed
// transship - the freight order
gets transshipped to another transport; see id of other
// transport
in Details below
// fail - the execution of the
freight order failed; see Details freight order explanation
// cancel - the execution of the freight
order was canceled; see Details freight order
// explanation
// delay - the freight order
experiences a delay; see Details freight order estimated delay
// other – something unexpected
happened; see Details
“detail” : string, // detailed
information depending on the action verb, e. g.
// arrival - transport arrived at
place freight order pickup / delivery / service, waiting freight
// order service
// service - transport is currently
servicing freight order
// departure - transport finished
service and departs the location
// UID of transport to which the
freight order got transshipped
// time duration in case of a delay
// else any free text
}
{
“id” : UID,
// id of this execution state instance
“idExecution”
: UID, // id of the execution instance on which this execution state belongs
“idTransport”
: UID, // id of the transport to which this execution state belongs
“location” : Coordinates, //
geographical location at which this execution state was current
“timestamp” : int, // timestamp in UTC
when this execution state was current
“events” : ExecutionEvent
[ ], // a list of all freight order events and the time and place where
//
and when each one happened
}
{
“location” :
Coordinates, // geographical location at which this execution event was current
“timestamp” : int, // timestamp in UTC
when this execution event was current
“event” : FOEvent,
// data on what got executed at the given time and place
}
{
“idExecution” : UID, // id of the execution instance on
which this conflicts instance belongs
“conflicts” : Conflict [ ], // a list
of conflict instances defining deviance from the tour plan
//
specified in the result instance used as basis freight order an
execution instance;
//
note that the list is empty if no conflicts occurred
}
{
“idTransport” : UID, // id of the transport to which this
conflict instance belongs
“idFo” :
UID. // id of the freight order instance to which this conflict refers
“detail” :
string, // detailed comment information on this conflict
“plannedAction”
: ExecutionEvent, // action instance defining what
was planned
“actualAction”
: ExecutionEvent, // action instance defining what
actually happened
}
{
“orders” : UID[ ], // list of IDs of
orders that shall get clustered; of course the orders have to
// have been
created before either by CSV import (see 2.1 ) or the freight
order
// route (see 2.8 ).
“method” : string, // defines the
method to be used for clustering; possible values are:
// ‘centerpoints’ – cluster by using the centerpoint
on a direct line between
// pickup and delivery of an order; or if it
is a service order then choose the
// delivery location (which is treated as the
service location)
// ‘connectors’ –
cluster using all locations (pickup and delivery) and then create
// sets of orders that determine if an order
is included in a cluster with all its
// locations (pickup and delivery; or for
service orders only delivery), or if each
// location is mapped to a different cluster
thus the order becoming a so-called
// ‘connector’ order.
// ‘sectors’ –
cluster by determining multinodes (pickup or
delivery; so-called
// ‘roots’) and then create a distinct number
of sectors (‘areas’) going out from
// each root where each one holds a
disjunctive set of orders.
“countClusters”
: int, // the desired count of clusters to create; note that if
// ‘allowLessClusters’
is true then the countClustersActual in
the resulting data
// can be less than countClusters.
Also if the count of orders to be clustered is
// less than countClusters
then the actual count of clusters will be less.
“allowLessClusters” : boolean //
if true then the clustering can result in less clusters than
// specified in countClusters. If false
then stick to the countClusters value.
}
{
“orders” : UID[ ], // list of IDs of
the clustered orders
“clustersPickup”
: int[ ], // array that defines which order in the orders array of the
input
// ClusteringTask has its pickup location assigned to
which cluster ID;
// the index of
this array corresponds to the index of that orders array, and the
// values of the clusters
array are the ids of the cluster to which that order is
// assigned.
// Depending on
the clustering method it is possible that some orders do not
// have their
pickup assigned to any cluster – then the cluster ID value is < 0.
“clustersDelivery” : int[ ], // array that defines
which order in the orders array of the input
// ClusteringTask has its delivery location assigned to
which cluster ID;
// the index of
this array corresponds to the index of that orders array, and the
// values of the clusters
array are the ids of the cluster to which that order is
// assigned.
// Depending on
the clustering method it is possible that some orders do not
// have their
delivery assigned to any cluster – then the cluster ID value is < 0.
“countClustersActual”
: int // the resulting actual count of clusters with at least one order
// assigned; this
can be less than the desired countClusters –
see remarks in
// countClusters and allowLessClusters
of ClusteringTask.
}
1.0.0 – initial version freight order C#
implementation containing base and calculation parts
1.1.0 – extension containing Execution Tracking
service
1.2.0 – initial implementation version
1.2.2 – basis freight order implementation by
external partner company
1.3.0
– basis freight order integration of planning service; mainly adapted JSON data
to fit actual implementation
1.3.1
– extension of API by CSV file import
1.3.2 – added to Result resource the download in PDF format (see 3.3.1)
1.3.3 – fixed separator symbols of CSV import data to be commas
1.3.4 – corrected invalid descriptions of POST methods; previous descriptions said that existing entries could be updated by POST supplying existing IDs which was wrong; in any case PUT must be used to update existing entries
1.3.5 – added “Schedule” resource parameters “totalDistance” and “totalDuration” (see 5.13), and to “Task” resource the “timeBegin” parameter (see 5.10)
1.3.6 – added return code 500 for Result PDF generation / processing (see 3.3.1)
1.3.7
– changed the returned data format of CSV imports
1.3.8 – add properties “costsDeploy”, “costsFixed”, “costsToll”, “tollDistance” to “Schedule” resource
1.3.9 – add “cpkmload” parameter to truck resource
1.3.10 – add “height” parameter to Truck resource (see 5.5) and “timeBeginIsHoliday” parameter along with changed info on “timeBegin” to Task resource (see 5.10)
1.3.11 – add “maxFoDistance” parameter to Truck resource (see 5.5)
1.3.12 – add “subType” parameter to Truck resource (see 5.5)
1.3.13 – add more parameters to Truck resource (see 5.5)
1.3.14 – update added parameters of Task resource (see 5.10)
1.3.15 – add the orders clustering route (see 3.4 , 5.25 , 5.26 ) and ‘clusteringMethod’ property to Task resource (see 5.10 )
1.3.16 – add the “/ids” subroute to GET of Result resource (see 3.1.1 )
The data must heed the following rules.
· Text data must be stored as UTF-8 without BOM.
· Data fields must be separated by ‘,’ (comma) symbols.
·
Data in
individual fields must be delimited by ‘”’ (double quote) symbols.
· One individual data set is stored in a single line, i. e. the data sets are separated by CR (carriage return) symbols – as is custom in the Unix world.
· The first line does not contain field header names but starts with actual data.
·
Decimal values have to use “.” as the
comma symbol and no thousands separator. Exponential format is not allowed.
"id";"Order Name";"Pick
Up Name";"Pick Up Country";"Pick
Up Postal Code";"Pick Up City";"Pick Up Streetname";"Pick
Up Housenumber";"Drop Off Name";"Drop Off Country";"Drop
Off Postal Code";"Drop Off City";"Drop Off Streetname";"Drop
Off Housenumber";"Freight Weight";"Freight Volume"
|
|
Field name |
Data type |
Description |
Example |
|
1 |
id |
integer value |
Data set ordinal – will be output if errors occur during processing |
1 |
|
2 |
Order Name |
text |
Descriptive text defining the order |
Daimler Gitterbox |
|
3 |
Pick Up Name |
text |
Pickup contact reference |
Häberle Stanzereien GmbH |
|
4 |
Pick Up Country |
text |
Pickup country name |
Deutschland |
|
5 |
Pick Up Postal
Code |
text |
Pickup ZIP code (country specific) |
71088 |
|
6 |
Pick Up City |
text |
Pickup city name |
Holzgerlingen |
|
7 |
Pick Up Streetname |
text |
Pickup street name |
Im Dörnach |
|
8 |
Pick Up Housenumber |
text |
Pickup house number |
13 |
|
9 |
Drop Off Name |
text |
Delivery contact reference |
HAL Computing Inc. |
|
10 |
Drop Off Country |
text |
Delivery country name |
Deutschland |
|
11 |
Drop Off Postal
Code |
text |
Delivery ZIP code (country specific) |
71032 |
|
12 |
Drop Off City |
text |
Delivery city name |
Böblingen |
|
13 |
Drop Off Streetname |
text |
Delivery street name |
In den Weinbergen |
|
14 |
Drop Off Housenumber |
text |
Delivery house number |
14 |
|
15 |
Freight Weight |
decimal value |
Freight weight in kilograms |
512,50 |
|
16 |
Freight Volume |
decimal value |
Freight volume in cubic meters |
4,5 |
"id";"Vehicle Name";"Vehicle
Start Country";"Vehicle Start Postal Code";"Vehicle Start City";"Vehicle
Start Streetname";"Vehicle Start Housenumber";"Vehicle End Country";"Vehicle
End Postal Code";"Vehicle End City";"Vehicle End Streetname";"Vehicle
End Housenumber";"Vehicle Payload";"Vehicle Volume";"Vehicle
Costs p distance";"Vehicle Costs p time";"Vehicle Toll Costs";"Driver
Costs p Time";"Driver Break after";"Driver Break Duration"
Note that data for vehicle start location (namely the columns “Vehicle Start Country", "Vehicle Start Postal Code", "Vehicle Start City", "Vehicle Start Streetname", and "Vehicle Start Housenumber") are considered to be the vehicle’s homedepot address.
Note
that data for vehicle end location (namely the columns “Vehicle End
Country", "Vehicle End Postal Code", "Vehicle End
City", "Vehicle End Streetname", and
"Vehicle End Housenumber") are ignored in
the current API version.
|
|
Field name |
Data type |
Description |
Example |
|
1 |
id |
integer value |
Data set ordinal – will be output if errors occur during processing |
1 |
|
2 |
Vehicle Name |
text |
Descriptive text defining the transport |
S – SL 2022 |
|
3 |
Vehicle Start Country |
text |
Vehicle start location’s country name |
Deutschland |
|
4 |
Vehicle Start Postal Code |
text |
Vehicle start location’s ZIP code (country specific) |
70173 |
|
5 |
Vehicle Start City |
text |
Vehicle start location’s city name |
Stuttgart |
|
6 |
Vehicle Start Streetname |
text |
Vehicle start location’s street name |
Königstrasse |
|
7 |
Vehicle Start Housenumber |
text |
Vehicle start location’s house number |
22 |
|
8 |
Vehicle End Country |
text |
Vehicle end location’s country name |
Deutschland |
|
9 |
Vehicle End Postal Code |
text |
Vehicle end location’s ZIP code (country specific) |
71032 |
|
10 |
Vehicle End City |
text |
Vehicle end location’s city name |
Böblingen |
|
11 |
Vehicle End Streetname |
text |
Vehicle end location’s street name |
In den Weinbergen |
|
12 |
Vehicle End Housenumber |
text |
Vehicle end location’s house number |
14 |
|
13 |
Vehicle Payload |
decimal value |
Maximum weight in kilograms that the vehicle can have loaded at
a time |
14000,0 |
|
14 |
Vehicle Volume |
decimal value |
Maximum volume in cubic meters that the vehicle can have loaded
at a time |
180,5 |
|
15 |
Vehicle Costs p distance |
decimal value |
Vehicle’s costs per distance in Euro per kilometer |
2,58 |
|
16 |
Vehicle Costs p time |
decimal value |
Vehicle’s costs per time in Euro per hour |
0,85 |
|
17 |
Vehicle Toll Costs |
decimal value |
Vehicle’s costs to be applied on toll roads in Euro per
kilometer; if no toll applies to vehicle then set to
zero; |
1,22 |
|
18 |
Driver Costs p Time |
decimal value |
Vehicle driver’s costs per time in Euro per hour |
28,23 |
|
19 |
Driver Break after |
integer value |
Count of minutes after which the vehicle’s driver must begin a
mandatory pause |
240 |
|
20 |
Driver Break Duration |
integer value |
Count of minutes that the vehicle’s driver’s pause must take |
60 |