Stop Locations
Manage the location where a route stop is planned
There are two ways to define a stop location:
- Using an Address object
- Defining a single-use location
The Addresses API allows you to define locations of interest with configurable geofences that are reusable across routes. Creating stops with single-use locations requires that you provide lat/long coordinates each time.
Note: Some data points in the Samsara dashboard (e.g. Time on Site Report, Proximity search) will not provide accurate data for use single-use locations.
It is recommended that you use the Addresses API. The Addresses API provides:
- Easy reuse
- Custom geofences
- Geocoding: The Addresses API will automatically define lat/log coordinates based on a street address provided
- External IDs: Refer to Addresses based on a custom identifier that you provide
Using an Address object
See the Addresses guide to see how to create and manage Addresses.
Step 1: Create an Address
The following request creates an Address that can be reused when creating Routes. It also sets an External ID on the Address: routePlanningSystem:abc123.
curl --request POST 'https://api.samsara.com/addresses' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
"name": "Samsara",
"formattedAddress": "1990 Alameda St, San Francisco, CA 94103, USA",
"geofence": {
"circle": {
"radiusMeters": 250
}
},
"externalIds": {
"routePlanningSystem": "abc123"
}
}'{
"data": {
"id": "12086521",
"name": "Samsara",
"createdAtTime": "2020-05-27T21:23:46.203619757Z",
"formattedAddress": "1990 Alameda St, San Francisco, CA 94103, USA",
"geofence": {
"circle": {
"radiusMeters": 250
}
},
"externalIds": {
"routePlanningSystem": "abc123"
},
"latitude": 37.76865129999999,
"longitude": -122.4048058
}
}Step 2: Reference the Address when creating a Route
Now you can refer to the Address by its id when creating routes (instead of having to define the Address each time):
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-06T05:17:38.746Z"
},
{
"addressId": "21275794",
"scheduledArrivalTime": "2021-05-06T05:29:40.746Z"
}
]
}'External IDs
You can also refer to the Addresses by external ID when defining the route stop:
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": "routePlanningSystem:abc123",
"scheduledDepartureTime": "2021-05-06T05:17:38.746Z"
},
{
"addressId": "routePlanningSystem:def456",
"scheduledArrivalTime": "2021-05-06T05:29:40.746Z"
}
]
}'Single-use Locations
To create a route stop using a single-use location, provide a singleUseLocation for the stop with:
- The location's
address - The location's
latitudeandlongitude - Optionally, a
radiusMetersfor the circular geofence around the location. If omitted, the geofence defaults to a 300 meter radius.
curl --request POST 'https://api.samsara.com/fleet/routes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer TOKEN' \
--data-raw '{
"name": "Route 1234",
"stops": [
{
"singleUseLocation": {
"address": "1990 Alameda St, San Francisco, CA 94103, USA",
"latitude": 37.76865129999999,
"longitude": -122.4048058,
"radiusMeters": 500
},
"scheduledDepartureTime": "2021-05-06T05:17:38.746Z"
},
{
"addressId": "routePlanningSystem:def456",
"scheduledArrivalTime": "2021-05-06T05:29:40.746Z"
}
]
}'Note: Single-use locations use circular geofences with a default radius of 300 meters. You can override this by setting radiusMeters on the stop's singleUseLocation. For polygon geofences or reusable locations, use the Addresses API to create an Address with a custom geofence and reference it by addressId.
Updated 19 days ago