To quickly and easily create a large number of routes for your fleet, you can upload a comma-separated values (CSV) file. For example templates, see the following two files: template for routes using the Address Book or template for routes using raw addresses.
At a high-level, each row in the file represents a stop on a route, with multiple rows collectively representing an entire route. Every route must have at least two stops. As a result, each route in the CSV file must have a minimum of two rows. The first row for a given route represents the starting location and time.
For more information about adding routes in bulk, see the following topics:
-
Create the CSV file in the spreadsheet application of your choice. See CSV Formatting Rules for Routes for detailed formatting requirements.
-
From the Samsara dashboard, select Dispatch (
) > Routes.
-
Select More Actions > Upload CSV.
-
Click the link to Upload a file or drag and drop it to the dialog.
-
Click Upload to initiate the file upload.
To upload routes in bulk, you must create a CSV file that adheres to the following guidelines:
-
The file can contain up to 1,000 rows of data.
-
All field headings in row 1 must be left intact, even if you choose to leave that entry blank.
-
Every entry must have a Route Name and a Stop Name. Group all stops in a route by using the same Route Name for each entry.
-
Every route in Samsara must have a start and end location, which means two stops are required.
-
Samsara recommends using a spreadsheet application to edit your CSV file. Google Sheets and Excel are both great options. If you use a text editor, you must format any entries that contain commas in quotes (for example a full address).
-
Routes can be assigned to either a vehicle or driver, or they can be left unassigned.
For assigned routes, enter the assignee in either the Assigned Driver Username and Assigned Vehicle Name field. Routes cannot be assigned to both, so you can only use one assignment method per route. Assignees must also match names in the Samsara dashboard.
For unassigned routes, leave both fields blank.
-
All date and time values in a CSV file must be based off of the timezone set in General Settings for the Samsara dashboard. Local timezone settings associated with the user are not observed. For example, if the timezone of the dashboard is set to Eastern Time, the user is in Pacific Standard time, and the time of a stop is set to 2 PM in the CSV file, the stop will be scheduled for 2 PM Eastern Time.
-
You can upload routes scheduled far into the future, but the Samsara dashboard will only display the next 30 days of scheduled routes. If a file successfully uploads, this means that your route was created. When the scheduled date is within 30 days, you will be able to view it on the dashboard.
The following table describes the CSV fields you can use to define routes:
|
Field |
Description |
Example |
|---|---|---|
|
Route Name |
Descriptive name to identify the route. Group related stop entries in a route using a consistent Route Name. |
Ice Cream Deliveries |
|
Assigned Driver Username (Optional) |
To assign a driver to a route, the driver username must already be defined in Samsara and you must copy the username exactly. Leave this field blank if you want to instead use an Assigned Vehicle Name or to import the route as unassigned. |
driver_a |
|
Assigned Vehicle Name (Optional) |
To assign a vehicle to a route, the vehicle name must already be defined in Samsara and you must copy the name exactly. Leave this field blank if you want to instead use an Assigned Driver Name or to import the route as unassigned. |
Semi1 |
|
Stop Name (Required) |
Descriptive name to identify the stop. This field must be completed for each location within the route, including the start location. All routes must have a minimum of two stops. As a result, you must have at least two stop names. For each additional stop on the route, another stop name is required. |
Bi-rite |
|
Stop Arrival Time (Optional for the first stop; Required for 2+ stops) |
This field represents the scheduled arrival time for the driver to arrive at a stop or end location. Timezones are relative to the timezone set in General Settings of the Samsara dashboard. If you expect the driver to already be in the first location when the route begins, you may want to leave the stop arrival time blank for the first row. If you expect to track the arrival time at the first stop, you may want to complete the stop arrival time. This field must be completed for all other stops. |
|
|
Stop Departure Time (Required for the first stop if Stop Arrival Time is blank; Optional for 2+ stops) |
This field represents the scheduled departure time or planned time for the driver to leave the start location. Timezones are relative to the timezone set in General Settings of the Samsara dashboard. This field is optional for all other stops. |
|
|
Stop Notes (Optional) |
Identifies any notes you want to include about the stop. Notes added to route stops are visible to drivers in the Samsara Driver App under the respective stop. The route view for fleet administrators does not include the driver notes. |
Deliver 5 cases |
|
Address Name (Required if Latitude, Longitude, and Full Address are not specified) |
Name of the address location in the Address Book. If an Address Name is specified, the route stop will be created using the geofence of the Address Book entry with the same name. The name must be an exact match. Names are also case and space sensitive. Include any spaces if present in the beginning or end of a name. If you do not specify an Address Book entry with the Address Name field, you can leave this field blank and instead specify the Latitude, Longitude, and Full Address. |
Bi-Rite |
|
Latitude (Required if Address Name is not specified) |
The Latitude, Longitude, and Full Address fields can be used together to create a route stop instead of using an Address Book entry. |
36.24491 |
|
Longitude (Required if Address Name is not specified) |
The Latitude, Longitude, and Full Address fields can be used together to create a route stop instead of using an Address Book entry. |
-79.98793 |
|
Full Address (Required if Address Name is not specified) |
The Latitude, Longitude, and Full Address fields can be used together to create a route stop instead of using an Address Book entry. |
8632 US Highway 158, Stokesdale, NC 27357 |
To help you get started, there are two example templates that you can view. The first template represents creating routes using the Address Book. The second template represents creating routes using raw addresses (Latitude, Longitude, Full Address). It is also possible to mix and match these two methods in one file (with some rows using the Address Book and other rows using raw addresses).
Refer to the following table for common issues you may encounter when trying to bulk upload routes.
|
Issue |
Description |
|---|---|
|
Route Name doesn't match |
Each route must have at least two stops (start and end) with the same Route name. Ensure that each a stop has a route name that matches at least one entry before or after it. |
|
Driver Username or Vehicle Name does not match |
For driver and vehicle assignments, you must enter an exact match to the name specified in the Samsara dashboard. To avoid typos, consider downloading your list of drivers or vehicles to copy and paste the exact names in your routes file. |
|
Multiple drivers or vehicles listed in a single route |
You can assign a route to either one driver or one vehicle only. Attempting to assign portions of a route to multiple drivers will result in upload failure. |
|
Stop Arrival and Departure Times not in chronological order |
Ensure that your route stops are scheduled in chronological order. Attempting to schedule all stops for the same time or scheduling a stop to depart after the next stop is scheduled to arrive will result in upload failure. |
|
Address Name does not match an Address Book entry |
Ensure that your Address Name matches an entry exactly in the Samsara dashboard. Addresses are case and space sensitive. Consider downloading your Address Book to copy and paste the exact Address Name in your routes file. |
|
Mixing Address Name with Latitude, Longitude, or Full Address |
Ensure that you choose only one method for specifying an address:
The method that you do not choose should be left blank. Since these represent two distinct methods for specifying the address information for your route stop, they are never intended to be mixed together and can result in upload failure. |
|
Deleted or edited headings |
The first row of the CSV file identifies the headings that map to the fields in the Samsara dashboard. These entries are mandatory and must be included exactly as shown. Editing or removing any of the values in the first row will result in an error. |
|
Hidden data in extra fields or entries |
In some cases, if you reuse an older template with extra rows at the bottom and don't properly delete the old information, you may accidentally upload incomplete route information. To prevent this type of error, always start with a new CSV file or only copy exactly columns A through K in row 1 into a new CSV. If you have already formatted your route and don’t believe you’ve made any other of the above errors, simply copy and paste columns A through K of all the rows you want to keep and paste into a new CSV. If there were any hidden entries in the old file, this would remove them. |
To isolate an issue with route creation, use the following workflow:
-
Start with just one route in a file.
If your file is failing for unknown reasons, try to upload just the first route by itself to see if it will upload. It is easier to diagnose a problem in one route first and determine if that same problem might exist for all the other routes.
-
Divide your routes into smaller segments for testing.
If the first route uploads successfully, try to divide the CSV roughly in half to see if one half of the routes upload successfully with the other half fails. This can help you determine if you have made errors in multiple places or if it is more likely that just one or two routes could be causing the issue. Divide again. If one half of your routes fails, divide that file in half again or into smaller chunks to see if you can narrow down the problem to just one or two routes.
-
Review any errors mentioned in the error message.
Uploading a single route is more likely to identify a clear error message, as having multiple routes could lead to more than one type of error.
The row names provided in the error message do not include the header row, so the row number will be off by one. For example, if the error message says row 5, examine row 6 in your CSV file.
-
Leave optional fields blank.
When testing your first route, remove any optional values from your route and leave them blank to verify that the file can be uploaded without the optional information. This can be a quick test to narrow down the most likely fields that have errors.
-
Check for typos or missing data.
Because you must specify exact matches for Driver Usernames, Vehicle Names and Address Names, you can download the CSV files for each of these and then copy the two corresponding columns into a new sheet and use Excel to look for duplicates in the two columns. For a successful upload, you would expect every Driver Username, Vehicle Name and Address Name in your Route to be marked as a duplicate. If any are not marked as duplicates you can determine whether that is due to missing information on the dashboard or a typo.
-
If you still need help, contact Support and supply your CSV file.
