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

Updating Routes

πŸ“˜

If a route requires many updates, it may be easier to delete the route and then create a new one. The following guide focuses on making smaller updates to a route.

What are we building?

This example will guide you through the following:

  • Using HTTP PUT semantics to correctly update the following aspects of a route:
    • The route name and notes
    • The route assignment
    • Route locations
    • Route schedule
    • Updating, adding, and removing route stops

Overview

πŸ“˜

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 updated using the following API endpoint:

PUT /v1/fleet/dispatch/routes/{route_id}

The HTTP PUT verb means that the route object provided in the JSON request body will replace the route object specified by the route_id in the path parameter. The route's ID will not change.

To update the route, you should:

  1. Retrieve the full representation of the route using a GET endpoint.
  2. Modify the fields of the JSON route object to make your desired update.
  3. Submit the full, modified route object to the PUT endpoint.

In general, this means you should retrieve the route you wish to update, modify its fields, and then submit the payload to the PUT endpoint.

Let's take a look at a very simple example that updates a route's name using Python:

import requests
import json

url = "https://api.samsara.com/v1/fleet/dispatch/routes"
headers = {"Authorization": "Bearer <token>"}

# ID of route to update
route_id = 4299693109

# Get the full route
route = requests.request(
  "GET", 
  url + '/' + str(route_id), 
  headers=headers).json()

# Update the route object's name
route["name"] = "New Name"

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

Updatable Fields

Here is what you can update:

  • Route start time: scheduled_start_ms
  • Name: name
  • Start location: you can either change the start_location_address_id to reference a different Samsara Address, or you can unset that value and define a new start location inline. See the example for details.
  • Route assignment: adding, removing, or modifying the driver_id or vehicle_id.
  • Notes: notes
  • Adding or removing dispatch_jobs.
  • Editing the following properties of a dispatch job:
    • Scheduled arrival time: scheduled_arrival_time_ms
    • Scheduled departure time: scheduled_departure_time_ms
    • Notes: notes
    • Destination location: you can either change the destination_address_id to reference a different Samsara Address, or you can unset that value and define a new destination location inline. See the example for details.

You cannot update the following fields. If you do, it will simply be ignored. This includes:

  • Scheduled end time: scheduled_end_ms. This is always automatically set to be 1 hour after the scheduled arrival time of the last stop and cannot be changed.
  • Anything that is β€œactual” (i.e. tracked by Samsara through route tracking):
    • Actual start time: actual_start_ms
    • Actual end time: actual_end_ms
    • Job state: job_state
    • State change times: en_route_at_ms, completed_at_ms, skipped_at_ms, arrived_at_ms

πŸ“˜

Updating multiple fields at once

You may update multiple fields at once by modifying all desired fields of the JSON route object and submitting that full, modified route object to the PUT endpoint.

Updating Live or Finished Routes

Once Samsara has started tracking a route, it is recommended that you ONLY MAKE UPDATES TO THE FOLLOWING FIELDS:

  • name
  • notes
  • dispatch_jobs: You should only add or modify dispatch jobs whose scheduled arrival time is after the current time.

❗️

Modifying a live or finished route's start information or route stops whose scheduled arrival time has already passed WILL RESULT IN UNPREDICTABLE BEHAVIOR.

Examples

Retrieve the Route

All the following examples require that you retrieve the full route object first:

import requests
import json

url = "https://api.samsara.com/v1/fleet/dispatch/routes"
headers = {"Authorization": "Bearer <token>"}

# ID of route to update
route_id = 4299693109

# Get the full route
route = requests.request(
  "GET", 
  url + '/' + str(route_id), 
  headers=headers).json()

You may then update the desired fields and submit the full route object to the PUT endpoint. See the example below.

Name and Notes

# Update the route object's name and notes
route["name"] = "New Name"
route["notes"] = "New notes."

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

Route Assignment

Routes can be assigned to either drivers or vehicles. They cannot be assigned to both.

# Make sure the vehicle assignment has been cleared
route["vehicle_id"] = None
# Assign the route to a new driver
route["driver_id"] = 1654973

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()
# Make sure the driver assignment has been cleared
route["driver_id"] = None
# Assign the route to a new vehicle
route["vehicle_id"] = 212014918732717

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()
# Clear the route assignment variables
route["driver_id"] = None
route["vehicle_id"] = None

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

Route Start Location

Route locations can either reference a registered Address object by its ID (recommended), or they can be defined inline within the route. See the Route Locations guide for more details.

🚧

Location Overrides

If an Address ID is used to define a route location, any additional location fields will act as overrides to that Address.

Therefore, you should always clear all location fields when updating a route location.

# Clear all start location fields
route["start_location_address_id"] = None
route["start_location_name"] = None
route["start_location_address"] = None
route["start_location_lat"] = None
route["start_location_lng"] = None

# Reference a different route start Address
route["start_location_address_id"] = 10755202

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()
# Clear all start location fields
route["start_location_address_id"] = None
route["start_location_name"] = None
route["start_location_address"] = None
route["start_location_lat"] = None
route["start_location_lng"] = None

# Define a new inline location
route["start_location_address"] = "1725 Sacramento St, San Francisco, CA 94109, USA"
route["start_location_lat"] = 37.79090310048426
route["start_location_lng"] = -122.42164644973755

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

Route Start Time

# Update the route's scheduled start time
route["scheduled_start_ms"] = 1586910600000

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

Adding Route Stops

To add a route stop, simply create a dispatch job object and add it to the dispatch_jobs array. Samsara will automatically order routes stops based on scheduled arrival time.

# Define a new stop
new_stop = {
  "destination_address_id": 9890809,
  "scheduled_arrival_time_ms": 1586480400000
}

# Add new stop to the dispatch_jobs array
route["dispatch_jobs"].append(new_stop)

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

Removing Route Stops

To remove a route stop you must remove it from the dispatch_jobs array. It is helpful if you know the dispatch job's ID.

# ID of the route stop to remove
stop_id = 4329351402

# Find the stop in the dispatch_jobs array and remove it
stop_index = None
for i, stop in enumerate(route["dispatch_jobs"]):
  if stop["id"] == stop_id:
    stop_index = i
if stop_index:
  route["dispatch_jobs"].pop(stop_index)

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

Route Stop Schedule

🚧

Scheduled Departure Times

There is a known issue with the routing API that allows you to accidentally set a scheduled_departure_ms to a time before the scheduled_arrival_ms. This will cause unpredictable behavior with route tracking.

Therefore, it is recommended that you always explicitly set the scheduled_departure_ms when updating a route stop's schedule. You may set it to null which will cause the stop to use the default route stop duration time, or you may explicitly set the value to a time after the scheduled arrival time.

# ID of the route stop to remove
stop_id = 4329351402

# Find the stop and update its schedule
for stop in route["dispatch_jobs"]:
  if stop["id"] == stop_id:
    # Clear the scheduled_departure_ms
    stop["scheduled_departure_ms"] = None
    # Set the new scheduled_arrival_ms
    stop["scheduled_arrival_ms"] = 1586913780000
    break

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

πŸ“˜

Stop Order

Samsara will automatically order stops based on scheduled_arrival_ms, regardless of the order you arrange them in the dispatch_jobs array.

Route Stop Locations

Route locations can either reference a registered Address object by its ID (recommended), or they can be defined inline within the route. See the Route Locations guide for more details.

🚧

Location Overrides

If an Address ID is used to define a route location, any additional location fields will act as overrides to that Address.

Therefore, you should always clear all location fields when updating a route location.

# ID of the route stop to remove
stop_id = 4329351402

# Find the stop and update its location
for stop in route["dispatch_jobs"]:
  if stop["id"] == stop_id:
    # Clear all start location fields
    stop["destination_address_id"] = None
    stop["destination_name"] = None
    stop["destination_address"] = None
    stop["destination_lat"] = None
    stop["destination_lng"] = None
    # Reference a different route start Address
    stop["destination_address_id"] = 10755202

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()
# ID of the route stop to remove
stop_id = 4329351402

# Find the stop and update its location
for stop in route["dispatch_jobs"]:
  if stop["id"] == stop_id:
    # Clear all start location fields
    stop["destination_address_id"] = None
    stop["destination_name"] = None
    stop["destination_address"] = None
    stop["destination_lat"] = None
    stop["destination_lng"] = None
    # Define a new inline location
    stop["destination_address"] = "1725 Sacramento St, San Francisco, CA 94109, USA"
    stop["destination_lat"] = 37.79090310048426
    stop["destination_lng"] = -122.42164644973755

# Submit the *full*, modified route to the PUT endpoint
response = requests.request(
  "PUT", 
  url + '/' + str(route_id), 
  headers=headers, 
  data=json.dumps(route)).json()

Updated 4 months ago



Updating Routes


Suggested Edits are limited on API Reference Pages

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