Routing

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

For an overview of how routing works in the Samsara Dashboard and Driver app, see these knowledge base articles:

• Routes Overview
• 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.

Key concepts

Route A planned sequence of stops assigned to a specific driver or vehicle, typically within a designated timeframe.

Stop (sometimes called a Route Stop) is a single location within a Route where a driver is scheduled (or required) to perform a specific action.

Route tracking

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

Samsara tracks routes sequentially and selects the route with the earliest scheduled start time to track first.

The Route Stop Arrival & Configuration article provides an in-depth guide on different route stop states and how ETAs are calculated.

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. Samsara treats routes and stops as the primary scheduling blocks, you can map your "orders" concept onto these objects to track deliveries, pickups, and more. Decide how you want to store order information depending on your use case:

• Truckload (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 scheduledArrivalTime and scheduledDepartureTime 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 or the phone number for the individual receiving the delivery.

Route stop instructions are added as route stop Notes. Route stop notes are free form text.

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.

Route start and completion settings

Samsara lets you control how and when your routes are marked as started and completed. You can set these conditions at the organization-wide level (in Dispatch Settings on the Dashboard) and for individual routes.

• For an organization-wide default, see the Dispatch Settings knowledge base article.
• For details on route configuration and tracking windows, see the Routes Overview article.

routeStartingCondition

This setting determines how the route’s start time is triggered.

• arriveFirstStop: The route starts when the driver arrives at the first stop.
• departFirstStop (default): The route starts when the driver departs the first stop.

routeCompletionCondition

This setting determines how the route’s completion time is triggered.

• arriveLastStop (default): The route completes when the driver arrives at the last stop.
• departLastStop: The route completes when the driver departs the last stop.