Timestamps

Understand the RFC 3339 and Unix timestamp formats used across Samsara’s API generations.

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

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 3339 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]