Timestamps

The Manifold API uses standardized timestamp formats to ensure precise and consistent tracking of events, activities, and data queries. This document provides an overview of timestamp formatting, usage, and best practices for working with timestamps in the API.

Timestamp Format

All timestamps in the Manifold API are represented in ISO 8601 format with UTC (Coordinated Universal Time) as the default time zone. This ensures consistency across different systems and allows for seamless conversion to local time zones when needed.

Format: YYYY-MM-DDTHH:MM:SSZ

• YYYY: Year
• MM: Month (01 to 12)
• DD: Day of the month (01 to 31)
• T: Separator between date and time
• HH: Hour in 24-hour format (00 to 23)
• MM: Minutes (00 to 59)
• SS: Seconds (00 to 59)
• Z: Indicates that the time is in UTC

Example Timestamps

• 2024-10-13T15:28:33Z: October 13, 2024, at 3:28:33 PM UTC
• 2023-06-01T00:00:00Z: June 1, 2023, at 12:00:00 AM UTC

Timestamp Usage in the API

Timestamps are integral to many Manifold API endpoints, facilitating precise data queries and filtering. Common use cases include retrieving historical records, monitoring events, and managing resources.

Common Timestamp Fields

1. createdAt: The date and time when a resource (e.g., connection, driver) was created.
2. updatedAt: The last time a resource was updated.
3. startedAt: The start time of an event, trip, or activity.
4. endedAt: The end time of an event, trip, or activity.
5. time: A general-purpose timestamp for specific data points (e.g., GPS coordinates).

Querying with Timestamps

The Manifold API supports filtering data using timestamps in query parameters. This allows you to retrieve time-bound data for improved efficiency and relevance.

Supported Query Parameters

Example Query

To retrieve safety events that occurred between specific dates:

curl --request GET \
--url 'https://api.analytics.autos/safety-events?from=2024-10-01T00:00:00Z&to=2024-10-10T23:59:59Z' \
--header 'x-api-key: YOUR-API-KEY' \
--header 'Connection-Id: YOUR-CONNECTION-ID'

Example Endpoint Usage

Safety Events

• Fields: startedAt, endedAt
• Description: Track when safety events occurred during a specific time frame.

Trips

• Fields: startedAt, endedAt
• Description: Retrieve start and end times of trips for route validation and analysis.

Vehicles

• Fields: updatedAt
• Description: Identify the last time vehicle data was updated.

Working with Timestamps in Applications

When working with timestamps, you may need to convert UTC timestamps to local time zones for display or processing. The following are examples in popular programming languages:

JavaScript

const utcDate = new Date("2024-10-13T15:28:33Z");
const localDate = utcDate.toLocaleString("en-US", { timeZone: "America/New_York" });
console.log(localDate);

Python

from datetime import datetime
import pytz

utc_time = datetime.strptime("2024-10-13T15:28:33Z", "%Y-%m-%dT%H:%M:%SZ")
local_time = utc_time.replace(tzinfo=pytz.utc).astimezone(pytz.timezone("America/New_York"))
print(local_time)

Java

import java.time.ZonedDateTime;
import java.time.ZoneId;

ZonedDateTime utc = ZonedDateTime.parse("2024-10-13T15:28:33Z");
ZonedDateTime local = utc.withZoneSameInstant(ZoneId.of("America/New_York"));
System.out.println(local);

Best Practices

1. Use UTC for Data Storage:
   • Always store and retrieve timestamps in UTC to maintain consistency.
2. Specify Time Ranges for Filtering:
   • Use from and to query parameters to limit the scope of returned data, improving performance.
3. Handle Timezone Conversions on the Client Side:
   • Convert UTC timestamps to local time zones where necessary to meet user expectations.

Summary

Timestamps are a fundamental aspect of the Manifold API, providing precise time-based control over your data. By adhering to the standardized format and following best practices, you can ensure seamless integration and accurate handling of time-related data across your applications.