Time Management in Validic's API

The Basics of Time Zones

In our interconnected world, managing time across different locations can be complex. Validic's API uses a standardized approach to ensure consistency and clarity in time reporting.

How Validic Handles Time

1. UTC (Coordinated Universal Time):

   • All times in our API are reported in UTC.
   • UTC is a global time standard, not tied to any specific location.
   • Example: "2024-07-23T20:59:38.450Z"
     • The 'Z' at the end indicates this is UTC.

2. UTC Offset:

   • We provide a UTC offset in seconds.
   • This allows calculation of the local time for each user.
   • Example: -14400 (equivalent to -4 hours)

3. Offset Origin:

   • We include an 'offset_origin' field to indicate where the UTC offset came from.

Example JSON Response

{
  "created_at": "2024-07-23T20:59:38.450Z",
  "start_time": "2024-07-23T16:59:38Z",
  "utc_offset": -14400,
  "offset_origin": "profile"
}

Interpreting the Data

• created_at and start_time are in UTC.
• utc_offset tells us how to adjust from UTC to local time:
  • -14400 seconds = -4 hours
  • This likely represents Eastern Daylight Time (EDT)
• To get local time, subtract 4 hours from the UTC time.
  • 20:59:38 UTC - 4 hours = 16:59:38 EDT

User Time Zone Management

• We can set a default time zone when provisioning a user.
• This default is used if a data source doesn't provide UTC offset information.

Why This Matters

• Consistent time reporting across different devices and locations
• Accurate data representation for users in various time zones
• Flexibility to display times in either UTC or local time as needed

Remember, while time zones can be complex, this system ensures that no matter where data is collected or viewed, we can always determine the precise local time of an event.