Overview

All routes have a start location and destination locations.

There are two ways to define route locations:

• Use the Addresses API
• Define a location on-the-fly

The Addresses API allows you to define a custom geofence that is reusable across routes. Defining a location on-the-fly requires that you provide lat/long coordinates each time you need to define a 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 retrieve 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.

As a quick example, the following request creates an Address that you can reuse when creating Routes:

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

{
    "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
            }
        },
        "latitude": null,
        "longitude": null
    }
}

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/v1/fleet/dispatch/routes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "name": "Route with Addresses",
    "driver_id": "1654973",
    "scheduled_start_ms": 1590710400000,
    "start_location_address_id": 12086521,
    "dispatch_jobs": [
        {
            "destination_address_id": 10755251,
            "scheduled_arrival_time_ms": 1590712200000
        }
    ]
}'

🚧

External IDs

Addresses support External IDs or user-provided custom identifiers. This can help you map Samsara Addresses with locations in your own system.

However the Routes API does not currently support referring to Addresses by their external IDs. If you choose to use external IDs with Addresses, the recommended approach is to get the Samsara ID of the Address by first retrieving it by its external ID:

GET /addresses/routingId:abc123

{
  "data": {
    "id": "12042269",
    ...
    "externalIds": {
      "routingId": "abc123"
    },
    ...
  }
}

Now you can refer to the Address by its Samsara ID 12042269 when creating Routes.

Locations on-the-fly

To define route locations on the fly, 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/v1/fleet/dispatch/routes' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <token>' \
--data-raw '{
    "name": "Route with on-the-fly locations",
    "driver_id": "1654973",
    "scheduled_start_ms": 1590710400000,
    "start_location_address": "1990 Alameda St, San Francisco, CA 94103, USA",
    "start_location_lat": 37.76865129999999,
    "start_location_lng": -122.4048058,
    "dispatch_jobs": [
        {
            "destination_address": "1725 Sacramento St, San Francisco, CA 94109, USA",
            "destination_lat": 37.79090310048426,
            "destination_lng": -122.42164644973755,
            "scheduled_arrival_time_ms": 1590712200000
        }
    ]
}'

On-the-fly like those defined above use circular geofences with a radius of 300 meters. This cannot be changed. Use the Addresses API to create custom geofences.

🚧

If both an Address ID and raw lat/long coordinates are provided, the location referenced by the Address ID will take precedence.