-> 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?

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:
  1. 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).
  2. 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:
  1. Use a mathematical operator for each load
    • negative operator → Deliveries
    • no (=positive) operator → Pickups
  2. 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:
  1. The fixed_els: The fixed part of the loading and unloading time for a shipment.
  2. 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).

Can a different end address than the depot be defined for the vehicles?

Yes! This feature is called "Heimfahrer".

  • An end address can be assigned to each vehicle. If an end address is defined, the tour always ends at this address. If no end address is defined, the tour ends as before at the depot or after the last stop.
  • For this purpose, the "end_location" parameter must also be passed to the vehicle object.
{
  "custom_id": "1234",
   "name": "Vehicle 1",
   "plate": "M- FI 1958",
   "depot_location_id": 1,
   "obeys_territory_mapping": "false",
   "daily_rate": 328.75,
   "km_rate": 0.39,
   "vehicle_class": "truck",
   "capacity_1": 5375,
   "capacity_2": 700,
   "capacity_3": 999,
   "max_load_height": 2.3,
   "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",
   "traveltime_factor": 2.0,
   "liftgate": true,
   "trailer": true,
   "active": true,
       "end_location": {
       "city": "Munich",
       "street": "Elsenheimerstraße",
       "postalcode": "80687",
       "housenumber": "45"
        },
    "roundtrip": true
}

For more information, see our API reference: Vehicle-> parameter "end_location".

  • In the result response, the end address can then 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>.prd.smartlane.io/api/address/<end_location_id>"

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

How many priorities can I assign?

  • The previous parameter "deliverprio" has been replaced by 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",
    "height": 0.34,
    "contactcompany": "Smartlane GmbH",
    "trailer_needed": false,
    "liftgate_needed": false,
    "fixed_els_seconds": 3600
}
  • More information in our API reference: Delivery -> Parameter "shipment_priority".
  • INFO: the previous delivery of the priorities "low", "medium", "high" is still possible via the parameter "deliverprio". The two parameters must not be be mixed.