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 (for eg, 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 you provide.
- External IDs: You can refer to Addresses based on a custom identifier that you provide.
Using an Address object
See the Addresses guide for detailed examples on how to create and manage Addresses.
Step 1: Create the Address
As a quick example, the following request creates an Address that you can reuse when creating Routes. It also creates an External ID for 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 their 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, you must provide a singleUseLocation
for the stop with:
- The location's
address
- The location's
latitude
andlongitude
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
},
"scheduledDepartureTime": "2021-05-06T05:17:38.746Z"
},
{
"addressId": "routePlanningSystem:def456",
"scheduledArrivalTime": "2021-05-06T05:29:40.746Z"
}
]
}'
Single-use locations use circular geofences with a radius of 300 meters. This cannot be changed. Use the Addresses API to create custom geofences.
Updated 27 days ago