Samsara currently has two generations of APIs. The latest generation uses RFC 3339 format to represent timestamps as strings. The first-generation APIs present timestamps as the number of milliseconds since the Unix epoch (int64s).

📘Timezones

Samsara returns both RFC 3339 and Unix timestamps in Coordinated Universal Time (UTC).

You may need to convert timestamps to/from UTC for your application.

Parameters that support RFC 3339 accept timezone offsets (e.g., 2020-11-02T00:00:00-08:00 to represent GMT-08:00). However the API *response will always be formatted in UTC.

RFC 3339

The current generation of Samsara APIs use the RFC 3339 format for timestamps. RFC 3339 is a string representation of date and time.

Here is a basic example:

2020-06-18T17:24:53Z

The above timestamp refers to June 18, 2020 5:24:53 PM in Coordinated Universal Time (UTC).

Unix timestamps

The first-generation Samsara APIs express timestamps as milliseconds since the Unix epoch in UTC.

Here is a basic example:

1592501093000

The above timestamp refers to June 18, 2020 5:24:53 PM in Coordinated Universal Time (UTC).

Examples of date-time conversions

📘

Note:

The examples below will be in Python3 programming language, please install the following dependencies before executing the functions.

• pytz
• dateutil
• datetime

1. The function below will convert the date-time in RFC 339 format to the specified timezone.
   Function Usage: convert_timezone('2020-01-27T07:06:25Z', 'US/Eastern')

def convert_timezone(time_value, target_time_zone):
    """
    Converts time in RFC 3339 format into the specified timezone.
    :param time_value: time in RFC 3339 (Example: '2020-01-27T07:06:25Z')
    :param target_time_zone: Example 'US/Central', 'US/Pacific' etc.)
    :return: converted time in string format

    Function Usage: convert_timezone('2020-01-27T07:06:25Z', 'US/Eastern')
    """
    parsed_t = dp.parse(time_value)
    time_in_seconds = parsed_t.timestamp()
    fmt = '%Y-%m-%d %H:%M:%S %Z%z'
    target_zone = pytz.timezone(target_time_zone)
    time_from_utc = datetime.fromtimestamp(time_in_seconds, tz=timezone.utc)
    time_from = time_from_utc.astimezone(target_zone)
    time_from.strftime(fmt)
    time_to_utc = datetime.fromtimestamp(time_in_seconds, tz=timezone.utc)
    converted_time = time_to_utc.astimezone(tz=pytz.timezone(target_time_zone))
    return converted_time

2. The function below will convert date-time in RFC 339 to milliseconds UNIX time.
   Function Usage: convert_to_ms('2020-01-27T07:06:25Z')

import datetime

def convert_to_ms(ip_timestamp):
    """
    Converts time in RFC 339 format to milliseconds UNIX
    :param ip_timestamp: Time in RFC 3339 format
    Examples: 2019-06-13T19:08:25Z, 2019-06-13T19:08:25.455Z
    :return: Time in milliseconds

    Function Usage: convert_to_ms('2020-01-27T07:06:25Z')
    """
    try:
        date = datetime.datetime.strptime(ip_timestamp, '%Y-%m-%dT%H:%M:%S.%fZ')
    except ValueError:
        date = datetime.datetime.strptime(ip_timestamp, '%Y-%m-%dT%H:%M:%SZ')
    timestamp = str((date - datetime.datetime(1970, 1, 1)).total_seconds() * 1000)
    return timestamp[:-2]