Stop Locations

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 latitude and longitude

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"
        }
    ]
}'

Note: Single-use locations use circular geofences with a radius of 300 meters. This cannot be changed. Use the Addresses API to create custom geofences.