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

Creating Routes

What are we building?

This guide will describe how to:

  • Create the most basic route.
  • Assign a route to a driver, vehicle, or trailer.
  • Define the route stops and schedule.
  • Provide route stop instructions via notes.

The Route Creation API Endpoint

πŸ“˜

For a general introduction to the Samsara REST API, see the Getting Started guide.

For an overview on Routing concepts, see the Routing overview page.

Routes are created using the following API endpoint:

POST https://api.samsara.com/v1/fleet/dispatch/routes

This endpoint accepts a JSON request body that represents the route being created.

The response will be the full route object including the route's ID and the route stop IDs.

The examples in the sections below all describe the JSON request body that you should submit to the POST /v1/fleet/dispatch/routes API. For reference docs, see here.

A Basic Route

The minimum requirements for any route are:

  • A route name.
  • A start time.
  • A start location.
  • At least one dispatch job (route stop) that must include:
    • A destination location.
    • A scheduled arrival time.

πŸ“˜

Check out the Route Start Time and Location section of the routing overview page for details on route start time and location.

πŸ“˜

All route locations can either:

  • Reference a registered Address by its ID (preferred)
  • Be defined inline by providing lat/long coordinates and a street address

All the examples in this guide reference registered Addresses by their IDs. See Route Locations for more details on how to register addresses or how to define route locations inline.

Let’s look at the sample JSON request for creating a very basic route:

{
  "name": "Basic Route",
  "scheduled_start_ms": 1586476800000,
  "start_location_address_id": 9890808,
  "dispatch_jobs": [
    {
      "destination_address_id": 9890809,
      "scheduled_arrival_time_ms": 1586480400000
    }
  ]
}

The scheduled_start_ms which is the scheduled start time of the route in a UTC Unix epoch timestamp in milliseconds. The start_location_address_id references a registered Address by its ID. The dispatch_jobs array contains one route stop with it Address and scheduled arrival timestamp. This request demonstrates the minimum requirements for creating a route.

This route is currently Unassigned. This means the route can either be claimed by a driver in the Samsara Driver App, or the route can be updated later with an assignment.

Assigning a Route

To assign a route to a driver or vehicle, you would include either the driver_id or vehicle_id field in the request:

{
  "name": "Route with Driver Assignment",
  "driver_id": 1255786,
  "scheduled_start_ms": 1586476800000,
  "start_location_address_id": 9890808,
  "dispatch_jobs": [
    {
      "destination_address_id": 9890809,
      "scheduled_arrival_time_ms": 1586480400000
    }
  ]
}

🚧

A route can be assigned to either a driver or a vehicle but not to both.

To assign the route to a vehicle instead, you would include the vehicle_id field instead of the driver_id.

To assign a route to a trailer, the route must also be assigned to either a driver or a vehicle. The below example assigns the route to both a vehicle and a trailer.

{
  "name": "Route with Vehicle and Trailer Assignment",
  "vehicle_id": 212014918085958,
  "trailer_id": 4804797,
  "scheduled_start_ms": 1586476800000,
  "start_location_address_id": 9890808,
  "dispatch_jobs": [
    {
      "destination_address_id": 9890809,
      "scheduled_arrival_time_ms": 1586480400000
    }
  ]
}

The Route Schedule

The examples above included only one dispatch job (route stop). Let's take a look at defining multiple dispatch jobs:

{
  "name": "Two Stop Route",
  "driver_id": 1255786,
  "scheduled_start_ms": 1586476800000,
  "start_location_address_id": 9890808,
  "dispatch_jobs": [
    {
      "destination_address_id": 9890809,
      "scheduled_arrival_time_ms": 1586480400000
    },
    {
      "destination_address_id": 9890810,
      "scheduled_arrival_time_ms": 1586484000000
    }
  ]
}

Stop Order

Route Stops are always ordered by their scheduled arrival times. It does not matter which order you place them in the array, Samsara will always order them by their scheduled arrival times.

Departure Times

If a scheduled departure time is not provided, the stop will use the fleet's Default Route Stop Time. This setting is configurable in the Samsara Dashboard under Settings -> Routing. The Default Route Stop Time is automatically set to 30 minutes.

The route above has the following schedule. It uses the default route stop time of 30 min.

  • Route Start Time: April 10, 2020 12:00:00 AM UTC (1586476800000 Unix epoch in milliseconds)
  • Stop #1:
    • Scheduled Arrival Time: April 10, 2020 1:00:00 AM UTC (1586480400000 Unix epoch in milliseconds)
    • Scheduled Departure Time: April 10, 2020 1:30:00 AM UTC
  • Stop #2:
    • Scheduled Arrival Time: April 10, 2020 2:00:00 AM UTC (1586484000000 Unix epoch in milliseconds)
    • Scheduled Departure Time: April 10, 2020 2:30:00 AM UTC
  • Route End Time: April 10, 2020 3:00:00 AM UTC (the scheduled route end time is always 1 hour after the last stop's scheduled arrival time)

When tracking the route, Samsara will use the above schedule to determine when stops are on-time, early, or late.

You may provide explicit scheduled departure times in your request as well:

{
  "name": "Scheduled Departure Times",
  "driver_id": 1255786,
  "scheduled_start_ms": 1586476800000,
  "start_location_address_id": 9890808,
  "dispatch_jobs": [
    {
      "destination_address_id": 9890809,
      "scheduled_arrival_time_ms": 1586480400000,
      "scheduled_departure_time_ms": 1586481300000
    },
    {
      "destination_address_id": 9890810,
      "scheduled_arrival_time_ms": 1586484000000,
      "scheduled_departure_time_ms": 1586484900000
    }
  ]
}

These scheduled departure times will now be used in determining when a route is on-time, early, or late.

πŸ“˜

Timestamps

In the Routes API, all timestamps are milliseconds from the Unix epoch in UTC time. When the route is presented in the Samsara dashboard or Driver App, times will be displayed in use the locale of the browser or mobile device.

Orders

Route stops primarily represent physical locations. This is because the route stop contains geofence details that Samsara uses to automatically track stop arrival and departure using the vehicle gateway.

If each location only contains a single order, then you only need to create a route stop for each order. The order details can be included in the route stop's name or notes.

Sometimes, multiple orders may share the same location. Examples of this include deliveries to malls, warehouses, apartments, etc. In this case, you may want to practice stop consolidation, which means associating multiple orders with a single stop. This prevents overlapping geofences which can cause issues with automated route tracking.

If you want to associate multiple orders with a single stop, you can still include details for each order in the stop's notes field. See Route Stop Instructions below for example code. Additionally, the Live Share Link associated with the stop will only contain the stop's name, so the same link could be shared with multiple customers if they share the same location.

Delivery Windows

If a stop has a delivery window, it is recommended that you set the scheduled arrival time for the stop to be the end of the order delivery window. This will inform the driver that they need to arrive at the stop before that time. Additionally, you can include order delivery windows in route stop notes.

Route Stop Instructions

You can use the notes field on each dispatch job (route stop) in order to give instructions to the driver. These fields can contain general information such as gate codes or phone numbers, and they can also contain information about the order such as weight, cubes, SKUs.

The notes fields can be formatted using newline characters: /n and tabs: /t.

Let's say you want to include the following route stop note:

Gate code: 12345
Phone number: 1234567890

Order Info:
    - SKU #: 1234567890
    - Number of cubes: 2

You would replace all newline and tab characters with \n and \t in the string that you provide to the notes field as part of your request:

{
  "name": "Stop Instructions",
  "driver_id": 1255786,
  "scheduled_start_ms": 1586476800000,
  "start_location_address_id": 9890808,
  "dispatch_jobs": [
    {
      "destination_address_id": 9890809,
      "scheduled_arrival_time_ms": 1586480400000,
      "notes": "Gate code: 12345\nPhone number: 1234567890\n\nOrder Info:\n\t- SKU #: 1234567890\n\t- Number of cubes: 2"
    }
  ]
}

This is how the note will appear in the Samsara Driver App:

πŸ“˜

Route Stop Tasks

The notes field described above are static and cannot be edited by a driver.

Route stop tasks, which require a driver to enter information into a custom form, can be defined using Samsara Documents. See Creating Stop Tasks for more information.

Route Completion

By default, routes will automatically complete when the vehicle arrives at the last stop. If instead, you want the route to complete when the vehicle departs from the last stop, you can set complete_last_stop_on_arrival to false in your request to create a route:

{
  "name": "Complete on Departure",
  "scheduled_start_ms": 1586476800000,
  "start_location_address_id": 9890808,
  "complete_last_stop_on_arrival": false,
  "dispatch_jobs": [
    {
      "destination_address_id": 9890809,
      "scheduled_arrival_time_ms": 1586480400000
    }
  ]
}

Updated about a month ago



Creating Routes


Suggested Edits are limited on API Reference Pages

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