Samsara has a feature called an Address Book that allows you to specify locations of interest and collect useful data about operations at each one.

All Addresses contain the following fields:

To see a full list of fields that Addresses support, see Addresses reference docs.

📘

For a general introduction to using the Samsara REST API, see the Getting Started guide.

Creating an Address

Use the Create an address API to create an Address.

A Circular Geofence

Here's a sample request body to create an Address with a circular geofence:

{
  "formattedAddress": "1990 Alameda Street, San Francisco, CA 94103",
  "geofence": {
    "circle": {
      "radiusMeters": 250
    }
  },
  "name": "Samsara"
}

The above POST request will create an Address at 1990 Alameda Street, San Francisco, CA 94103 with a circular geofence that has a radius of 250 meters. This Address will be called "Samsara".

Samsara will geocode the formattedAddress, so no latitude/longitude coordinates are required for circular geofences. See Retrieving an Address and Latitude/Longitude Overrides for details on retrieving and working with coordinates.

The response to this POST request is:

{
  "data": {
    "id": "12042269",
    "name": "Samsara",
    "createdAtTime": "2020-05-22T03:15:40.037250883Z",
    "formattedAddress": "1990 Alameda Street, San Francisco, CA 94103",
    "geofence": {
      "circle": {
        "radiusMeters": 250
      }
    },
    "latitude": null,
    "longitude": null
  }
}

🚧

Missing Latitude/Longitude

There is a known bug that causes the latitude/longitude to be missing in the response from the POST request for circular geofences. The latitude/longitude are returned through the GET /addresses endpoints. See Retrieving Addresses.

Notice that the above Address now contains an id field. This is the Samsara-provided unique identifier for the Address and can be used to retrieve the Address or use with other API endpoints. Addresses also support External IDs. See the External IDs guide for details on how to include external IDs upon creation of an Address.

A Polygonal Geofence

Here's a sample request body to create an Address with a polygonal geofence:

{
  "formattedAddress": "1990 Alameda Street, San Francisco, CA 94103",
  "geofence": {
    "polygon": {
      "vertices": [
        {
          "latitude": 37.76843235268285,
          "longitude": -122.40497116903383
        },
        {
          "latitude": 37.76985413820823,
          "longitude": -122.4050569997223
        },
        {
          "latitude": 37.77004071782183,
          "longitude": -122.40356754736023
        },
        {
          "latitude": 37.768466276936245,
          "longitude": -122.40373920873718
        }
      ]
    }
  },
  "name": "Samsara"
}

The response will be:

{
  "data": {
    "id": "12048024",
    "name": "Samsara",
    "createdAtTime": "2020-05-22T16:02:10.588692032Z",
    "formattedAddress": "1990 Alameda Street, San Francisco, CA 94103",
    "geofence": {
      "polygon": {
        "vertices": [
          {
            "latitude": 37.76843235268285,
            "longitude": -122.40497116903383
          },
          {
            "latitude": 37.76985413820823,
            "longitude": -122.4050569997223
          },
          {
            "latitude": 37.77004071782183,
            "longitude": -122.40356754736023
          },
          {
            "latitude": 37.768466276936245,
            "longitude": -122.40373920873718
          }
        ]
      }
    },
    "latitude": 37.76923653525234,
    "longitude": -122.40431227354127
  }
}

Samsara will geocode the formattedAddress into the latitude/longitude fields at the top level of the object.

Notice that the above Address now contains an id field. This is the Samsara-provided unique identifier for the Address and can be used to retrieve the Address or use with other API endpoints. Addresses also support External IDs. See the External IDs guide for details on how to include external IDs upon creation of an Address.

Latitude/Longitude Overrides

🚧

Polygonal Geofences

Polygonal geofences do not support latitude/longitude overrides. Only circular geofences do.

All Addresses must include a formattedAddress which will be geocoded to produce the latitude and longitude fields at the top level of the object. You may override these values for circular geofences by including latitude/longitude values in your request object:

{
  "name": "Samsara",
  "formattedAddress": "1990 Alameda Street, San Francisco, CA 94103",
  "geofence": {
    "circle": {
      "radiusMeters": 250
    }
  },
  "latitude": 37.76965129999999,
  "longitude": -122.4058058
}

The above request will create an Address at the latitude/longitude above rather than the latitude/longitude geocoded from the formattedAddress.

Note: You may include the latitude/longitude overrides within either the top-level object or within the circle object. The latitude/longitude overrides in the top-level object will take precedence if both are provided.

Inexact Addresses

Samsara does not support inexact addresses. The formattedAddress field is always required, and Samsara will always try to geocode it to assign the Address to a physical location.

If the site does not have a formattedAddress, a best guess should be used.

Another option is to create a circular Address with the exact latitude/longitude provided in the override fields and include a placeholder for the formattedAddress:

{
  "name": "New Site",
  "formattedAddress": "Best Guess Road",
  "geofence": {
    "circle": {
      "radiusMeters": 250
    }
  },
  "latitude": 37.76965129999999,
  "longitude": -122.4058058
}

The above request will create a circular geofence at the provided latitude/longitude and include the "Best Guess" formattedAddress in the Address object.

🚧

Invalid Formatted Addresses

If latitude/longitude overrides are not provided, Samsara will try to geocode the formattedAddress and assign the Address object to the first location it can find.

The Addresses API will not notify you of an invalid formattedAddress.

External IDs

Addresses support External IDs, or custom identifiers provided by you. See the External IDs guide for details on how to include external IDs in Addresses.

Retrieving Addresses

A Single Address

Use the Retrieve an address endpoint to get a single Address object by its Samsara ID or external ID:

• Samsara ID: GET /addresses/12042269
• External ID: GET /addresses/routing:abc123

The response would be:

{
  "data": {
    "id": "12042269",
    "name": "Samsara",
    "createdAtTime": "2020-05-22T03:15:40.037251Z",
    "formattedAddress": "1990 Alameda Street, San Francisco, CA 94103",
    "geofence": {
      "circle": {
        "latitude": 37.76865129999999,
        "longitude": -122.4048058,
        "radiusMeters": 250
      }
    },
    "externalIds": {
      "routing": "abc123"
    },
    "latitude": 37.76865129999999,
    "longitude": -122.4048058
  }
}

Listing Addresses

Use the List all addresses endpoint to list all Addresses in your organization:

{
  "data": [
    {
      "id": "12042269",
      "name": "Samsara",
      "createdAtTime": "2020-05-22T03:15:40.037251Z",
      "formattedAddress": "1990 Alameda Street, San Francisco, CA 94103",
      "geofence": {
        "circle": {
          "latitude": 37.76865129999999,
          "longitude": -122.4048058,
          "radiusMeters": 250
        }
      },
      "latitude": 37.76865129999999,
      "longitude": -122.4048058
    },
    { ... },
    { ... },
    ...
  ],
  "pagination": {
    "endCursor": "abc123-def456-ghi789",
    "hasNextPage": true
  }
}

The response will include a list of Addresses. See the Pagination guide on how to paginate through the results.

See the Filtering guide on how to filter the results.

Updating Addresses

You use the Update an address API to update an Address. This API updates the specified Address by setting the values of the fields passed. Any fields not passed will be left unchanged.

For example if I wanted to change the size of a geofence's radius, I could submit the following request:

PATCH /addresses/12042269

{
  "geofence": {
    "circle": {
      "radiusMeters": 500
    }
  }
}

This would update the Address to have a radius of 500 meters:

{
  "data": {
    "id": "12042269",
    "name": "Samsara",
    "createdAtTime": "2020-05-22T03:15:40.037251Z",
    "formattedAddress": "1990 Alameda Street, San Francisco, CA 94103",
    "geofence": {
      "circle": {
        "latitude": 37.76865129999999,
        "longitude": -122.4048058,
        "radiusMeters": 500
      }
    },
    "externalIds": {
      "routing": "abc123"
    },
    "latitude": 37.76865129999999,
    "longitude": -122.4048058
  }
}

You can also use an external ID as in the URL path of the PATCH request. See the External IDs guide for details on using and updating external IDs.

Deleting an Address

Use the Delete an address endpoint to delete an Address. This cannot be undone.

External IDs can be used in the URL path of the DELETE endpoint.