Stop Locations
Overview
There are two ways to define a stop location:
- Using the Addresses API
- Defining a single-use location
The Addresses API allows you to define a custom geofence that is reusable across routes. Defining a single-use location requires that you provide lat/long coordinates each time you need to define the location.
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.
The Addresses API
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 define a single use location, you must provide both of the following:
- The location's street address
- The latitude/longitude of the location
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 almost 2 years ago