Overview

This guide provides an overview of best practices when building an route planning integration with Samsara.

Check out these Knowledge Base articles for an overview of how routing works in the Samsara Dashboard and Driver app:

• Creating Routes in the Dashboard
• Routing in the Driver App

See the sub-pages in the ⬅️ navigation bar for more details on specific routing operations. The rest of this page details the main concepts around routing in Samsara, and provides an overview of how to set up a route planning integration.

Route Tracking

Samsara tracks routes for a given driver or vehicle sequentially and selects the route with the earliest scheduled start time to track first.

Samsara uses the Samsara Vehicle Gateway to automatically track route progress.

Check out this Knowledge Base article for an in-depth guide on different route stop states and the logic behind how Samsara assigns those states:

• Route Stop Arrival & Configuration

Route Assignment

Route assignment refers to what a route should be tied to in order to track the route’s progress. For example, some fleets assign routes to a vehicle since the vehicle’s driver might change throughout the progress of the route. Similarly some fleets assign routes to trailers or to drivers directly. The recommendation is to assign routes to whatever entity is least likely to change during the progress of a route.

Samsara Routes can be assigned to two different entities. A Route can only be assigned to one of these entities, not both:

• Driver
• Vehicle

Unassigned routes can either be assigned later by editing the route, or they can be claimed by drivers through the Driver App if that setting is turned on. See Creating Routes for details and example code.

Route Stops

A route stop represents the customer location for whom you are servicing one or more orders. Route stops have a number of qualities:

• Route Stop Destination (Geofence)
• Scheduled/actual arrival time of the stop
• Scheduled/actual departure time of the stop
• Stop state information and timestamps (en route, arrived, departed, etc. see Route Stop Arrival & Configuration)
• Notes (to list orders, driver instructions, etc)

Orders

Samsara doesn’t have an explicit "orders" entity. Instead, you can decide how you want to store order information depending on your use case:

• Trucking load (entire route represents a single order): Use the route's name and notes fields to store order information.
• Order per stop (single order at a single geofence): Use the stop's name and notes fields to store order information.
• Multiple orders per stop (multiple orders at a single geofence):
  • Option 1 - combined orders: Use the stop's notes field to list each order at that geofence.
    • Pros: Does not require manual stop arrival/depart for drivers.
    • Cons: Arrival/Departure at the geofence will be triggered only once so all orders will have the same En Route, ETA, Arrival, and Departure times.
  • Option 2 - individual orders: Create multiple stops using the same geofence, each representing an order. Require drivers to manually arrive/depart each stop to indicate delivery of each order.
    • Pros: Each order's state will be unique to that order, depending on when the driver manually arrives/departs from that order's stop.
    • Cons: Requires that the driver manually arrive/depart from each stop since they all have the same geofence.

Order Delivery Windows

A delivery window (i.e. service window, appointment window) is a time window within which the driver must complete the order. Examples of this include a negotiated appointment slot, the open/close times for a store, etc.

Samsara doesn’t have an explicit delivery window entity that can be tied to orders. Instead, it is recommended that delivery window information is stored in the route stop's notes.

Additionally, you should use the route stop's scheduled arrival and scheduled departure times to indicate the delivery window.

Instructions

Often times a driver may have specific instructions or information they need to be aware of, whether it is the gate code to enter a gate or the phone number for the individual he or she is delivering to.

Route stop instructions are added as route stop Notes. Route stop notes can contain any sort of free form information that the driver should be aware of.

See Creating Routes for details and sample code.

Tasks

When a driver arrives at a stop, that driver might have a series of tasks to complete (e.g. unload goods, complete Bill of Lading, complete Proof of Delivery, check reefer temperature).

In the Samsara Driver App, tasks are represented by Samsara Documents. Samsara Documents are custom forms that can be set up in the Samsara Dashboard for drivers to fill out during their day as needed. For more on documents, see the Documents knowledge base article.

Documents can be attached to a Route Stop as a Task for the driver to do.

See Creating Stop Tasks for details and sample code.

Starting and Completion Settings

You can customize the automatic tracking of your route start time and completion time in two ways:

• Setting the route's starting condition
• Setting the route's completion condition

routeStartingCondition

If you set the routeStartingCondition to arriveFirstStop, then arrival at the first stop will trigger the route's start.

If you set the routeStartingCondition to departFirstStop, then departure from the first stop will trigger the route's start.

routeCompletionCondition

If you set the routeCompletionCondition to arriveLastStop, then arrival at the last stop will trigger the route's completion.

If you set the routeCompletionCondition to departLastStop, then departure from the last stop will trigger the route's completion.

Default Conditions

The default conditions are:

• routeStartingCondition is set to departFirstStop
• routeCompletionCondition is set to arriveLastStop