Addresses

Create and manage known locations with circular and polygonal geofences using the Samsara Addresses API.

Samsara’s Address feature lets you define locations of interest with configurable geofences, enabling data collection to optimize operations and manage your fleet efficiently. You can use the full set of address APIs and address related webhook events to synchronize address information both ways between your system and Samsara.

All Addresses contain the following fields:

Field	Description
formattedAddress	The street address. Example: 1990 Alameda Street, San Francisco, CA 94103
geofence	Either a circular or a polygonal geofence.
name	A user-provided name.

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. You can also listen for AddressCreated webhook notifications that are sent when new addresses are created.

Circular geofence

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

curl --request POST 'https://api.samsara.com/addresses' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "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.

Example response:

{
  "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 when creating circular geofences. To see the geocoded latitude/longitude, use the GET /addresses endpoint to retrieve the newly geocoded Address. 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.

Polygonal geofence

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

curl --request POST 'https://api.samsara.com/addresses' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "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"
}'

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.

Latitude/Longitude Overrides

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

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

curl --request POST 'https://api.samsara.com/addresses' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "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.

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 always attempts to geocode it to assign the Address to a physical location.

Use a best guess if the location does not have a formattedAddress.

Consider creating a circular Address with latitude/longitude provided in the override fields and include a placeholder for the formattedAddress:

curl --request POST 'https://api.samsara.com/addresses' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "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 latitude/longitude and set “Best Guess” as the 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 — 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

Example response

{
  "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. The response will include a list of Addresses. See the Pagination guide on how to paginate through the results, and the Filtering guide on how to filter results.

Updating Addresses

Use the Update an address API to update an Address. Fields omitted from the request body are not changed.

Listen for AddressUpdated webhook notifications to know when an address is updated in Samsara.

Example request to change the size of a geofence radius for an address:

curl --request PATCH 'https://api.samsara.com/addresses/12042269' \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
  "geofence": {
    "circle": {
      "radiusMeters": 500
    }
  }
}'

You can also use an external ID in the URL when making PATCH requests. 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.

You can listen for AddressDeleted webhook notifications to know when an address is deleted in Samsara.