Creating Routes
Create and assign routes and configure route start and completion settings.
Learn how to:
- Create a basic route.
- Assign a route to a driver or vehicle.
- Adjust the route starting and completion settings for your use case.
- Provide route stop instructions via notes.
- Use external IDs to help sync with an external system.
Create a basic route
The minimum requirements for any route are:
- A route name.
- At least two stops that must include
- An address or single-use location. (See Stop Locations).
- A scheduled arrival/departure time.
Let’s look at the simple request for creating a very 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",
"stops": [
{
"addressId": "12086521",
"scheduledDepartureTime": "2021-05-07T14:30:00Z"
},
{
"addressId": "21275794",
"scheduledArrivalTime": "2021-05-07T15:00:00Z"
}
]
}'
This example uses Addresses to assign the stops' locations. See the Stop Locations guide for details.
This route is currently unassigned. To see how to assign a route, read on below.
Assigning a route
To assign a route to a driver or vehicle, either include the driverId
or vehicleId
field in the request:
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": "2021-05-07T14:30:00Z"
},
{
"addressId": "21275794",
"scheduledArrivalTime": "2021-05-07T15:00:00Z"
}
]
}'
A route can be assigned to either a driver or a vehicle but not to both.
You can assign a route to a vehicle by replacing the driverId
field above with vehicleId
.
If neither the driverId
nor vehicleId
field is assigned, the route will be "unassigned." You can assign it later by Updating the Route.
Route start and completion settings
You can customize the automatic tracking of your route start time and completion time in two ways:
- Setting the route's starting condition
- Setting the route's completion condition
This is controlled by the settings
field of the route. The default settings for a route are:
{
"settings": {
"routeStartingCondition": "departFirstStop",
"routeCompletionCondition": "arriveLastStop"
}
}
This means that, by default, the route will start when the vehicle departs from the first stop, and the route will complete when the vehicle arrives at the last stop.
You can adjust these settings to fit your use case:
routeStartingCondition
: Valid values:departFirstStop
,arriveFirstStop
routeCompletionCondition
: Valid values:arriveLastStop
,departLastStop
Stop arrival and departure times
When creating routes, each stop requires a schedule to determine when the vehicle is expected to arrive or depart. The first and last stop of a route are special and depending on the route's starting and completion conditions the first and last stop may require one of an arrival or departure time.
First stop
WhenrouteStartingCondition
is departFirstStop
then scheduledDepartureTime
is required.
When routeStartingCondition
is arriveFirstStop
then scheduledArrivalTime
is required.
Last stop
When routeCompletionCondition
is arriveLastStop
then scheduledArrivalTime
is required.
When routeCompletionCondition
is departLastStop
then scheduledDepartureTime
is required.
Intermediate stops
All other stops must have a scheduledArrivalTime
. The scheduledDepartureTime
is optional, and, if omitted, will be automatically set to the next stop's scheduledArrivalTime
.
Stops are automatically ordered by 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.
By default, Samsara validates that arrival and departure times cannot overlap. This validation can be disabled in organization wide by navigating to Settings > Dispatch.
📘Timestamps
See the Timestamps guide for details on working with timestamps.
Route Stop Instructions
Use the notes
field on the route or each route stop to share instructions with 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 support 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:
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": "2021-05-07T14:30:00Z"
},
{
"addressId": "21275794",
"scheduledArrivalTime": "2021-05-07T15:00:00Z",
"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 appears in the Samsara Driver App:
Route Stop Tasks
See Creating Stop Tasks to learn how to create interactive driver tasks using Samsara's Documents feature.
(The
notes
field described above is only meant for static instructions).
External IDs
You can use External IDs on routes, stops, and addresses in order to help sync with an external system.
The following example creates a route with an external ID on the route and stops with external IDs, and it also sets route stop locations using address external IDs (as shown in Stop Locations):
curl --request POST 'https://api.samsara.com/fleet/routes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <<token>>' \
--data-raw '{
"name": "Route 1234",
"externalIds": {
"routePlanningSystem": "route1234"
},
"stops": [
{
"externalIds": {
"routePlanningSystem": "stop1234"
},
"addressId": "routePlanningSystem:address1234",
"scheduledDepartureTime": "2021-05-07T14:30:00Z"
},
{
"externalIds": {
"routePlanningSystem": "stop4567"
},
"addressId": "routePlanningSystem:address4567",
"scheduledArrivalTime": "2021-05-07T15:00:00Z"
}
]
}'
Note: external IDs must be unique if they share the same key.
Updated 16 days ago