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. Please note that a few data points in the Samsara dashboard (for eg, Time on Site Report, Proximity search) will not provide accurate data if you use single-use location when creating the route. This is because these data points are based on Addresses in the Address book

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.