Samsara Developer Portal

Integrate your data with the Samsara API, customize the Samsara experience, and join a community of developers building with Samsara.

Get Started


Create, manage, and track routes and driver workflow


This page provides an overview of common route planning concepts and describes how they map onto Samsara's routing system.

Check out these Knowledge Base articles for an overview of how routing works in the Samsara Dashboard and 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 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 Start Time & Location

All routes have a Scheduled Start Time and a Start Location.

The Scheduled Start Time helps define the route's tracking window: the time during which Samsara tracks the assigned vehicle in relation to the route's stop locations. Samsara begins tracking a route one hour before the route's scheduled start time by default, configurable up to 24 hours before through the Samsara dashboard.

The Start Location is meant to represent where the route should start from. It is used to capture the route's Actual Start Time, to mark the first stop as "En Route", and to provide an ETA for the first stop.

Here is how route tracking works in relation to the Scheduled Start Time and Start Location:

  1. Samsara begins tracking the route one hour before the route's scheduled start time.

  2. If the route's tracking window has started, and the vehicle exits and remains outside the Start Location geofence for 2 consecutive minutes, the route is considered "started", and the actual start time of the route is timestamped.

Example: vehicle leaves the start location at 8 AM, they stay outside the geofence until 8:02 AM. Samsara will timestamp the route as starting at 8 AM.

If the vehicle never crosses the route's start location, then the route's actual start time will be marked as when the vehicle arrived at the first stop.

Unknown Route Start Location

Sometimes you may not know where a route is supposed to start from. You should do your best guess to determine where this location may be. For example, it could be a home terminal or the last stop from a previous route. The best guess will help make sure that the start of the route is tracked as accurately as possible.

If there is no way to predict where a route will start from, a safe bet is to assign the start location to a place that the vehicle will never be. This will force the route to always "start" when the vehicle arrives at the first stop (instead of starting when the vehicle exits the start location geofence).

For example, you could set this to the middle of the San Francisco Bay:

"start_location_address": "San Francisco Bay, California",
"start_location_lat": 37.656357,
"start_location_lng": -122.274088

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
  • Scheduled/actual arrival time at the stop
  • Scheduled/actual departure time at the stop

Route Stop Destinations can be selected from the Samsara Address Book or they can be manually entered on the fly. Address Book entries are better because they allow for customized geofences and reusability.

Each route stop has a required Scheduled Arrival Time and an optional Scheduled Departure Time. If not provided, the scheduled departure time will be automatically populated based on the default route stop time in the Routing Settings page.

The Actual Arrival Time and the Actual Departure Time are tracked based on entering and exiting a stop’s geofence.

See Creating Routes for details and sample code.

Route Stop 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


An order defines the service/delivery completed during the progress of a route. A driver may complete one or many orders during a route. Sometimes there are multiple orders to fulfill at the same stop or sometimes it is a one-to-one mapping.

Samsara doesn’t have an "orders" entity tied to route stops. Order information (e.g. weight, cubes, SKUs) is added to route stops is by adding the information to the route stop Notes. Route stop notes can be formatted to provide better readability to the driver. The route stop notes section can show up to 2000 characters of information.

If the entire route is for one single order (e.g. a trucking load), then order name and number can be reflected in the route name.

If each route stop contains only a single order, then the order name and number can be reflected in each route stop's name.

If there are multiple orders per route stop (e.g. multiple orders at the same shopping mall), then each order can be reflected in the route stop notes, and the route stop can be reflective of the entire location servicing those multiple orders.

Order Delivery Windows

A delivery window (i.e. service window, appointment window) represents a time window within which the driver is required to complete the order. Sometimes this is a negotiated appointment slot, or sometimes this is the open and close times for the store the driver is delivering to.

Samsara doesn’t have a Delivery Window entity that can be tied to Orders. For the driver to have visibility into the Delivery Window, the recommendation is to add the Delivery Window information to the route stop notes.

Additionally, to ensure Samsara tracks the progress of a route properly, it is recommended that the route stop’s Scheduled Arrival Time is set as the end of the order delivery window in order to accurately track late arrivals.

Route Stop 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 End Time

The route’s end time signifies when the driver ended executing the route. This is a helpful data point so that fleets can track the route distance and route time traveled.

The Scheduled End Time for a route is always defined as one hour after the last stop’s scheduled arrival time. The Actual End Time is when all stops have been completed or when the route finishes tracking. See Creating Routes for details and sample code.

Updated about a month ago


Create, manage, and track routes and driver workflow

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.