-> Planning Data

What information are needed for a planning process?

To start a planning it is mandatory to provide deliverydata (shipments) and vehicles. Our intelligent software algorithm fits the shipments on the available vehicles under considering complex constraints like, time windows, capacities, territories and further more.
Please see our chapter Calc route optimized timewindow for an comprehensive overview of possible query parameter, and body parameter consisting of deliverydata and vehicledata.
For a quick start please refer to our Optimizing Routes example.

What is the mandatory information regarding shipments and vehicles which needs to be provided for a planning?

Please see a detailed overview of all parameters for Vehicle and Delivery or as mentioned above in the chapter Calc route optimized timewindow where both are combined.
A minimum set of information is:
- deliverydata:
  - custom_id
  - customer_company
  - street
  - postalcode
  - city
  - load
  - load 2
  - load 3
  - pdt_from
  - pdt_to
- vehicles:
  - custom_id
  - name
  - vehicle_class
  - capacity_1
  - capacity_2
  - capacity_3
  - daily_rate
  - km_rate
  - departure_time_from
  - departure_time_to
  - return_time_to
  - max_tour_duration
  - depot_location

Where do I find an example how my data should look like and how to start a planning process?

Carefully read the Optimizing Routes chapter of the tutorial.

Do I need to consider something regarding the date and time format?

Make sure that all dates and times are formatted according to the ISO 8601 standard.
Be aware that the time zone designator is mandatory.

I use the same fleet for each planning. Do I need to send these vehicles with every request?

There are two possibilities:

The fleet is managed in your own Master Data tool (e.g. TMS System). Then the entire fleet which needs to be
considered must be send for each planning (recommended option).
The fleet is stored and managed in the Smartlane interface. You can use our GUI and API to manage your fleet.
Then the fleet will be considered automatically for each planning. Please ensure that all vehicles are activated
for the corresponding planning process.

How to manage your vehicles via Smartlane API please see: Vehicle

How can I assign a shipment to a specific vehicletype?

First the vehicletype needs to be defined for each vehicle. Therefore please refer to the parameter vehicletype in Vehicle.
The vehicle type can be referenced from a vehicle.
You can add the vehicletype to your shipment data. This can be done with the parameter vehicletype_name in Delivery.
Now it is ensured that the shipment is assigned to your expected vehicletype.

Note:

One vehicletype can contain several vehicles.
But one vehicle just can be assigned to one vehicletype.
One shipment can contain several vehicle types in the parameter vehicletype_name.

How can I assign a shipment to a specific vehicle?

This can be handled similar to the above question.
Just one thing needs to be considered:
- Each vehicle must have its own vehicletype defined. We propose to name the vehicletype identical to the name of your vehicle.
You can add the vehicletype to your shipment data.
Now it is ensured that the shipment is assigned to your expected vehicle.

How can I assign different timewindows to a delivery (Multiple Time Windows)?

Multiple Time Windows can be defined by using arrays of pdt_from and pdt_to.
Below example shows two delivery time windows for one shipment. The first is from "10:30" to "11:30", the second from "12:30" to "13:30".

"pdt_from": ["2020-07-03T10:30:00+02:00",
             "2020-07-03T12:30:00+02:00"],
"pdt_to": ["2020-07-03T11:30:00+02:00",
           "2020-07-03T13:30:00+02:00"]

How can I distinguish between Pickups and Deliveries?

There are two possibilities:

Use a mathematical operator for each load
- negative operator → Deliveries
- no (=positive) operator → Pickups
Use the parameter shipment_type as "delivery" or "pickup" and set all loads with no operator.
see: Delivery

Make sure that all three loads for each delivery are using the same operator.

Where do I find an overview of all possible parameter I can use for my shipments?

For a full overview please see: Delivery

My vehicles are restricted to postal codes. How can I define the allowed postal codes for my vehicle?

To reach the best result with our intelligent software and to save as much as costs (e.g. less vehicles, less driven km, ...) as possible, we propose to use as less constraints as possible.
But we also offer the possibility to restrict vehicles to allowed postal code territories.
You can define different territories consisting of several postal codes. Refer to territories and territory - postal codes
If you manage your fleet in our Smartlane interface you can allocate the defined territories to the corresponding vehicles. See territory - vehicles.
If you send the available fleet in each planning you can set the allowed territories for each vehicle by territory_custom_ids.

Additionally:
To restrict a vehicle to the defined territories the parameter obeys_territory_mapping needs to be activated.
If it is disabled the vehicle will not restrict to territories.

"territory_custom_ids": ["3", "4"],
"obeys_territory_mapping": true

Note:

A territory can consist of one or several postal codes.
One postal code can just be assigned to one territory.
A vehicle is allowed to restrict to one or more territories but can also be defined without any territory based restriction.
One territory can be assigned to several vehicles.

How can I define the stop duration for a shipment?

For the expected length of stay (els) we offer several possibilities.
The els is composed of two values:

The fixed_els: The fixed part of the loading and unloading time for a shipment.
The variable_els: The variable part of loading and unloading time based on the shipment loads.

We follow this hierarchy based on the provided els information.
1. fixed and variable els defined in shipment data.
2. fixed and variable els defined on a vehicle level.
3. fixed and variable els defined on a vehicle type level.
4. Fallback to default fixed and variable els stored in our DB if no els is provided in an upper level.

For a detailed description see "Expected length of stay" in the chapter Defining shipments .

My company is facing the veracity of Big Data. What happens if we provide inadequate shipment data (e.g. incorrect address data)?

Our intelligent algorithm is trained to filter out invalid and inconsistent data like imprecise addresses. Such data will be ignored for the the planning process and the dropping reason will be shared in the corresponding planning result.
This information can be requested via Process status (id).

Where do my vehicles end? Is it possible to define a different end address than the depot for my vehicles?

In general there are three possibilities to define the end of a vehicles route:

The vehicle returns to the depot after the last stop:
- Set the parameter roundtrip = true
The vehicle stays in the field / The tour ends after the last stop:
- Set the parameter roundtrip = false
The vehicle returns to a defined end location after the last stop:
- Set the parameter roundtrip = false AND
- Define an end_location for the corresponding vehicle. See below instruction for more:

An end address can be assigned for each vehicle. If an end address is defined, the tour always ends at this address. If no end address is defined, the tour ends at the depot or after the last stop based on the parameter roundtrip.
To define an end address the parameter end_location must be passed to the vehicle object in the delivery data.

{
  "custom_id": "1234",
   "name": "Vehicle 1",
   "daily_rate": 328.75,
   "km_rate": 0.39,
   "capacity_1": 5375,
   "capacity_2": 700,
   "capacity_3": 999,
   "departure_time_from": "2027-08-05T07:30:00+02:00",
   "departure_time_to": "2027-08-05T08:00:00+02:00",
   "return_time_to": "2027-08-05T15:30:00+02:00",
   "max_tour_duration": "600",
   "depot_location": {
        "city": "MyDepotCity",
        "postalcode": "12345",
        "street": "MyDepotStreet",
        "housenumber": "1",
     },
   "end_location": {
	   "city": "MyEndLocationCity",
	   "postalcode": "99999",
	   "street": "MyEndLocationStreet",
	   "housenumber": "99"
     },
    "roundtrip": false
}

For more information, see our API reference: Vehicle or Calc route optimized timewindow -> BODY PARAMS
-> parameter end_location
-> parameter roundtrip

How to observe the end address in the result response:

In the result response, the end address can be determined via the route_id. This
can be found in the Route (id) call -> Parameter end_location_id.
The end_location_id references an address which can be retrieved via the Address call:

import requests

auth_header = {"Authorization": 'JWT ' + token}

api_url = "https://<your company name>.prod.smartlane.io/api/address/<end_location_id>"

response = requests.get(api_url, headers=auth_header)

My shipments do have different priorities. How many priorities can I define?

This can be done via the parameter shipment_priority. (Note: This parameter is new since September 2022. Before the parameter deliverprio was used. This parameter is deprecated but still possible to use. We recommend to use the new parameter shipment_priority)
The shipment_priority is defined as an integer from 0-n.
Where "0" is the lowest priority and "n" is the highest priority.

{
    "custom_id": "1234",
    "customernr": "141494082",
    "street": "Elsenheimerstraße 45",
    "postalcode": "80687",
    "country": "DE",
    "city": "München",
    "load": 17.0,
    "load_2": 8,
    "load_3": 0,
    "shipment_priority": "7",
    "pdt_from": "2027-09-28T14:00:00+02:00",
    "pdt_to": "2027-09-28T14:30:00+02:00",
    "contactcompany": "Smartlane GmbH",
}

Detailed information in our API reference: Delivery or Calc route optimized timewindow -> Parameter shipment_priority.