Timestamps

All timestamps used in the Sensos API follow a consistent format.

This guide provides details on how timestamps are handled, their format, and how to interpret them within your system.

Timestamp Format

The Sensos API uses ISO 8601 format for all timestamps. This format is widely used and ensures consistent, unambiguous representation of time across various systems. The format for a timestamp is:

YYYY-MM-DDTHH:MM:SSZ

Example

"2024-08-18T12:34:56Z"

In this example:

• YYYY represents the 4-digit year.
• MM is the 2-digit month.
• DD is the 2-digit day.
• T separates the date from the time.
• HH represents the 2-digit hour in 24-hour format.
• MM is the 2-digit minute.
• SS is the 2-digit second.
• Z indicates that the time is in UTC (Coordinated Universal Time).

Time Zones and UTC

All timestamps returned by the Sensos API are in UTC (Coordinated Universal Time), represented by the letter Z at the end of the timestamp. This ensures consistency across different geographic locations and systems, as UTC is not subject to time zone changes or daylight saving adjustments.

If you need to convert the UTC time to your local time zone, make sure to account for any time zone offsets and daylight saving changes.

Handling Timestamps

Parsing Timestamps

Many programming languages and libraries provide built-in support for parsing ISO 8601 timestamps. Depending on the language you're using, you can easily convert these timestamps into a more convenient format for your application.

Here are examples of how to handle timestamps in different programming languages:

JavaScript

const timestamp = "2024-08-18T12:34:56Z";
const date = new Date(timestamp);
console.log(date.toString()); // Outputs date in local time zone

Python

from datetime import datetime

timestamp = "2024-08-18T12:34:56Z"
dt = datetime.fromisoformat(timestamp.replace("Z", "+00:00"))
print(dt)

Java

import java.time.Instant;

String timestamp = "2024-08-18T12:34:56Z";
Instant instant = Instant.parse(timestamp);
System.out.println(instant.toString()); // Outputs UTC time

Formatting Timestamps

If you need to send or display timestamps in a specific format, you can use libraries or built-in functions in your programming language to convert the UTC timestamp into the desired format.

For example, converting a timestamp to a local time format:

• JavaScript: Use .toLocaleString()
• Python: Use strftime()
• Java: Use DateTimeFormatter

Importance of UTC

Using UTC ensures that timestamps remain consistent regardless of where your users or systems are located. Since UTC does not change with daylight saving time, it provides a stable and predictable reference for all time-related events. This is especially important in distributed systems where users may be in different time zones.