Routing

Samsara refers to loads as routes. A route is a planned sequence of stops assigned to either a vehicle or a driver.

Why Routing Matters for TMS

• Automated Load Assignment
  Automatically push loads (routes) from your TMS into Samsara so drivers see them in the Samsara Driver App.

• Real-Time Progress Tracking
  Samsara's Vehicle Gateways automatically track ETA, arrival, departure, and route completion times, giving dispatchers continuous visibility.

• Driver Workflow
  Drivers can see route stops, any notes or instructions, and use forms to capture key documents (e.g., proof of delivery).

• Seamless Two-Way Sync
  Keep your TMS and Samsara updated whenever a stop is added, removed, or changed.

Key Concepts

1. Routes vs. Loads

   • In Samsara, each “route” can represent an entire load (or multiple shipments).
   • A route must have at least two stops (e.g., pickup and dropoff).

2. Assigning Routes

   • Routes can be assigned to only one of the following:
     • A driver (recommended if the driver remains with the load)
     • A vehicle (recommended if the vehicle remains the same but drivers might change)

3. Stops & Addresses

   • Each route has multiple stops.
   • Stops can reference reusable Addresses (preferred) or single-use lat/long.
   • Use notes or scheduled times to inform drivers of instructions, delivery windows, etc.

4. Automatic Tracking

   • Samsara uses GPS and geofences to track each route stop’s en route, arrived, departed, or skipped states.

5. Route Completion Settings

   • Control how routes “start” or “end” automatically (e.g., on arrival vs. departure of a stop).

1. Creating Routes

Basic Requirements

• Route Name – Unique label for the load (e.g., “Load #1234”).
• At Least Two Stops – For pickup and dropoff (or multiple stops if needed).
• Stop Location – Typically an Address ID or a single-use lat/long.
• Scheduled Arrival/Departure Times – Let Samsara plan arrival/departure tracking.

Example: Creating a Basic Route

curl --request POST 'https://api.samsara.com/fleet/routes' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer <token>>' \
     --data-raw '{
       "name": "Route 1234",
       "driverId": "1654973",
       "stops": [
         {
           "addressId": "12086521",
           "scheduledDepartureTime": "2024-06-13T19:08:25Z"
         },
         {
           "addressId": "21275794",
           "scheduledArrivalTime": "2024-06-13T20:15:00Z"
         }
       ]
     }'

• driverId: Assigns this route to the driver with ID 1654973.
• stops: Each stop references an existing address by ID. (See Addresses API.)
• scheduledArrivalTime / scheduledDepartureTime: Timestamps that Samsara uses for route planning.

Route Settings

You can control start and completion conditions with the settings field:

"settings": {
  "routeStartingCondition": "departFirstStop",
  "routeCompletionCondition": "arriveLastStop"
}

• routeStartingCondition can be departFirstStop or arriveFirstStop.
• routeCompletionCondition can be arriveLastStop or departLastStop.

By default, departFirstStop and arriveLastStop are used.

2. Managing Stop Details

Stop Notes & Instructions

Use the notes field to pass important info like gate codes, contact phone, or order details. Samsara does not have a concept of an Order and instead you can add any order details to the free-form notes section of each stop.

{
  "addressId": "21275794",
  "scheduledArrivalTime": "2024-06-13T20:15:00Z",
  "notes": "Gate code: 12345\nPhone: 1234567890\n\nOrder Info:\n\t- SKU: 123456"
}

Drivers see these notes in the Samsara Driver App.

Single-Use Locations vs. Addresses

• Addresses – Reusable geofences you create via the Addresses API.
• Single-Use – Supply lat/long inline with singleUseLocation.
• Recommendation: Use Addresses for better geocoding, reporting, and reusability.

3. Updating Existing Routes

Routes often change—stops get added or removed, schedules shift, or a new driver is assigned.

• The [PATCH /fleet/routes/:id] endpoint requires you to send the entire updated stops array.
• Retain Stop IDs: If you want to keep an existing stop, make sure to include its id in your updated list. Otherwise, Samsara treats it as removed.

Example: Adding a Stop

import requests, json

url = "https://api.samsara.com/fleet/routes/routePlanningSystem:load_1234"
headers = {
  "Content-Type": "application/json",
  "Authorization": "Bearer <token>"
}

# Get current route data
route = requests.get(url, headers=headers).json()
stops = route["data"]["stops"]

# Add a new stop
stops.append({
  "addressId": "21275762",
  "scheduledArrivalTime": "2024-06-13T21:00:00Z"
})

# Send PATCH request
payload = { "stops": stops }
response = requests.patch(url, headers=headers, data=json.dumps(payload))

4. Tracking Route Progress

Polling: Route Audit Logs Feed

Use GET /fleet/routes/audit-logs/feed to poll for updates (stop arrivals, departures, skip events). Each call returns:

• operation: e.g. "stop arrived", "stop en route", "stop skipped".
• changes.before / changes.after: The state of each stop.
• Pagination via endCursor: Pass ?after=<previousEndCursor> to get new updates since your last call.

curl --request GET 'https://api.samsara.com/fleet/routes/audit-logs/feed?after=<cursor>' \
     --header 'Authorization: Bearer <token>'

Webhooks: RouteStopArrival & RouteStopDeparture

For event-driven workflows, subscribe to the RouteStopArrival or RouteStopDeparture webhooks:

{
  "eventType": "RouteStopArrival",
  "data": {
    "routeStopDetails": {
      "state": "arrived",
      "id": "141414",
      "actualArrivalTime": "2024-06-13T19:15:00Z"
    },
    "route": {
      "id": "342341",
      "externalIds": {
        "myRouteId": "abc"
      },
      "stops": [...]
    },
    "driver": {...}
  }
}

This approach notifies your TMS when a driver arrives/departs a stop.

5. Load & Resource Assignments

Carrier Proposed Assignments

If you need to prompt drivers to confirm which trailer or vehicle they’re using, use Carrier Proposed Assignments. This is separate from route assignment but complements load workflows:

• Propose a trailer or shipping ID to the driver.
• The driver accepts in the Samsara Driver App.
• The TMS sees updated driver-trailer association.

6. Best Practices & Tips

1. Combine GPS + Routing

   • Use the route feed + GPS data to show real-time progress in your TMS.
   • If you need more frequent location updates, see GPS Tracking for TMS Integrations.

2. Reference Addresses

   • Addresses allow custom geofences, better geocoding, and consistent reuse.
   • Single-use is quick for one-offs but lacks robust reporting and smaller geofence controls.

3. Check for Stop Arrival/Departure

   • If automatic arrival detection doesn’t suit your workflow (due to large geofences or close stops), you can configure manual arrive/depart in the Samsara Dashboard.

7. Example End-to-End Flow

1. Create Addresses for all major customer locations in Samsara.
2. Create a route referencing those addresses.
3. Assign the route to a driver (or vehicle).
4. As the driver moves, Samsara automatically updates the route’s progress.
5. Poll /fleet/routes/audit-logs/feed or subscribe to webhooks to see arrivals, departures, or skipped stops.
6. Update the route if the load changes (add stops, change times, reassign driver).
7. Complete the route automatically (or on driver departure from the last stop, depending on your settings).

Next Steps

• For deeper addresses how-to, see the Addresses API Guide.
• For real-time location data, see GPS Tracking for TMS Integrations.
• If you need to automate trailer or shipping ID assignments, check out Carrier Proposed Assignments.