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.