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

Track Route Progress

What are we building?

This example will guide you through the following:

  • Polling the API to get updates to the state of all route stops.

📘

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.

Polling for Updates

You can poll for route stop state changes using this REST API endpoint:

GET https://api.samsara.com/v1/fleet/dispatch/routes/job_updates

See the full reference docs here.

A job update is whenever a route stop changes state. You can read more about route stop state changes in the Route Tracking Knowledge Base article.

This endpoint is designed for you to repeatedly poll using a sequence_id to get updates since the last time you sent a request. For example:

Call Sequence

Description

Call #1

GET /v1/fleet/dispatch/routes/job_updates
Returns all job updates within the last 24 hours plus
sequence_id: abcdefg

Call #2

GET /v1/fleet/dispatch/routes/job_updates?sequence_id=abcdefg
Returns all job updates since the last time you called the endpoint plus
sequence_id: hijklmnop

Call #3

GET /v1/fleet/dispatch/routes/job_updates?sequence_id=hijklmnop
Returns all job updates since the last time you called the endpoint plus
sequence_id: qrstuvwuxyz

...

You can repeatedly poll the endpoint as described above and get new updates each time.

The full response to the GET /v1/fleet/dispatch/routes/job_updates looks like:

{
  "sequence_id": "eyJpZCI6NDMyMDgxNDg0MywiY3JlYXRlZF9hdCI6MTU4MTA2MDA1NTc5OX0=",
  "job_updates": [
    {
      "route_id": 4299693125,
      "changed_at_ms": 1581045837716,
      "job_id": 4315607830,
      "prev_job_state": "JobState_Scheduled",
      "job_state": "JobState_Skipped"
    },
    {
      "route_id": 4299693138,
      "changed_at_ms": 1581045837924,
      "job_id": 4315607883,
      "prev_job_state": "JobState_EnRoute",
      "job_state": "JobState_Arrived"
    }
    ...
  ]
}

You can write a loop to repeatedly poll the endpoint to get new updates with each new sequence_id:

import requests
import json
import time

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

# Initialize `sequence_id` to the empty string
params = {"sequence_id": ""}

while True:
    response = requests.request("GET", url, headers=headers, params=params).json()
    if response["job_updates"] is None:
        # There are no updates since the last time we sent a request
        # Sleep for 5 seconds
        time.sleep(5)
        continue
    for job_update in response["job_updates"]:
        # Do something with job update
        pass
    # Update `sequence_id`
    params["sequence_id"] = response["sequence_id"]

The sequence_id query parameter will allow you to retrieve new updates since the last time you sent a request. If you omit sequence_id from your request, you will get all route stop updates from the last 24 hours.

If the job_updates array is null, then there are no job updates since the last time you sent a request. It is recommended you wait at least 5 seconds before sending another request.

If the job_updates array is not null, then you should process the results and immediately query for more updates using the sequence_id. Each response payload will include a maximum of 500 job updates, so you should continue querying the endpoint until job_updates is null.

Updated 27 days ago



Track Route Progress


Suggested Edits are limited on API Reference Pages

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