Guide des Timestamps UTC

Cette page est provisoirement disponible en anglais. La traduction française est en préparation.

Introduction

UTC (Coordinated Universal Time) is the standard time reference used in computing and networks. Understanding how to work with UTC timestamps is essential for building applications that work across multiple timezones and need precise time calculations.

Understanding UTC

What is UTC Time?

UTC is a time standard that:

• Has no timezone offset (no daylight saving time)
• Uses a 24-hour clock format (00:00:00 to 23:59:59.999)
• Represented as "Z" in ISO 8601 (e.g., 2025-01-07T12:00:00.000Z)
• Serves as the basis for all other timezones

UTC vs Local Time

Crucial Concept: Local time varies by geographic location and timezone. UTC is constant worldwide.

Warning: Always store UTC timestamps in your database. Convert to local time only for display purposes.

UTC Timestamp Format

ISO 8601

UTC timestamps in ISO 8601 always end with "Z":

2025-01-07T12:00:00.000Z  // January 7, 2025, 12:00:00 UTC

Unix Timestamp

UTC timestamps are the number of seconds since Unix epoch (1970-01-01 00:00:00 UTC):

1735689600 // January 1, 2025, 00:00:00 UTC

Converting UTC to Local Time

JavaScript

Copy
JAVASCRIPT
1// Convert UTC timestamp (seconds) to local time
2function utcToLocal(utcTimestampSeconds, timezoneOffsetHours = 0) {
3  const date = new Date(
4    (utcTimestampSeconds * 1000) + (timezoneOffsetHours * 60 * 60 * 1000),
5  );
6  return date.toLocaleString(); // Returns string like "1/7/2025, 6:12:00 PM"
7}
8
9// Get UTC timestamp and convert to local
10const now = Math.floor(Date.now() / 1000);
11console.log(utcToLocal(now, -5)); // UTC-5 for EST

Python

Copy
PYTHON
1from datetime import datetime, timezone
2from zoneinfo import ZoneInfo
3
4# Convert UTC to specific timezone
5def utc_to_local(utc_timestamp: int, timezone_str: str) -> datetime:
6    """
7    Convert UTC timestamp to local datetime in specified timezone.
8    
9    Args:
10        utc_timestamp: Unix timestamp in seconds
11        timezone_str: IANA timezone name (e.g., 'America/New_York')
12    
13    Returns:
14        Local datetime object
15    """
16    utc_time = datetime.fromtimestamp(utc_timestamp, tz=timezone.utc)
17    return utc_time.astimezone(ZoneInfo(timezone_str))
18
19# Example
20print(utc_to_local(1735689600, "America/Los_Angeles"))

SQL

Copy
SQL
1-- MySQL: Convert UTC timestamp to datetime
2-- Note: Use FROM_UNIXTIME() which respects the system timezone setting
3
4-- Convert UTC timestamp to MySQL DATETIME
5SELECT 
6  id,
7  FROM_UNIXTIME(created_at) AS mysql_datetime,
8  created_at
9FROM events
10WHERE id = ?;
11
12-- Store current UTC timestamp
13UPDATE events
14SET created_at = UNIX_TIMESTAMP(NOW());
15
16-- PostgreSQL: Use TIMESTAMPTZ for timezone-aware storage
17CREATE TABLE events (
18  id BIGSERIAL PRIMARY KEY,
19  event_timestamp TIMESTAMPTZ NOT NULL DEFAULT NOW(),
20  event_date TIMESTAMP WITH TIME ZONE 'UTC'
21);
22
23-- Query events with local time display
24SELECT 
25  id,
26  event_timestamp,
27  TO_CHAR(event_timestamp, 'YYYY-MM-DD HH24:MI:SS') AS local_time
28FROM events;

Best Practice: Always store UTC timestamps. Use application-level timezone conversion for display only.

Timezone Handling

Understanding Timezone Offsets

Timezone offsets are expressed as:

• UTC+XX:00 (e.g., UTC-5:00)
• UTC-XX:00 (e.g., UTC+8:00)

Timezone Conversion Examples

JavaScript Timezone Conversions

Copy
JAVASCRIPT
1// Convert between UTC and different timezones
2function convertToTimezone(utcDate, timezone) {
3  const options = { timeZone: timezone };
4  return utcDate.toLocaleString('en-US', options);
5}
6
7// Examples
8const utcDate = new Date('2025-01-07T12:00:00.000Z');
9
10console.log(convertToTimezone(utcDate, 'America/New_York'));    // "1/7/2025, 7:00:00 AM EST"
11console.log(convertToTimezone(utcDate, 'Asia/Tokyo'));      // "2025/1/7, 21:00:00 JST"
12console.log(convertToTimeDate, 'Europe/London'));     // "1/7/2025, 12:00:00 GMT"
13console.log(convertToTimezone(utcDate, 'Asia/Shanghai'));   // "2025/1/7, 20:00:00 CST"

Copy
JAVASCRIPT
1// Python timezone handling
2from datetime import datetime, timezone
3
4# Get current UTC time and convert to timezone
5now_utc = datetime.now(timezone.utc)
6
7# Convert to specific timezone
8now_tokyo = now_utc.astimezone('Asia/Tokyo')
9now_est = now_utc.astimezone('America/New_York')
10now_gmt = now_utc.astimezone('Etc/GMT')
11
12print(f"UTC: {now_utc}")
13print(f"Tokyo: {now_tokyo}")
14print(f"EST: {now_est}")
15print(f"GMT: {now_gmt}")

Best Practices

UTC Storage Guidelines

Storage: Always store UTC timestamps. They are timezone-agnostic and efficient for global applications.

Display: Convert to local timezone only at the UI layer. Never store local times back to the database.

Queries: Always filter and sort by UTC timestamps. This ensures consistent ordering regardless of user's timezone.

APIs: Always use UTC timestamps in API responses. Document timezone in API documentation.

Critical Warning: Never mix UTC timestamps with local timestamps in the same column. This creates data integrity issues and query inconsistencies.

Common Pitfalls

Pitfall 1: Forgetting About Timezones

Problem: Not all locations observe DST at the same time.

Example: Arizona doesn't observe DST, but New York does. This can cause 1-hour differences between them during certain periods.

Solution: Use IANA timezone databases (tz database) which include historical and current DST rules.

Pitfall 2: Incorrect Timezone Offsets

Problem: Using hardcoded offsets instead of timezone names.

Bad: const offset = -5 * 3600000; // EST is always -5, but Arizona doesn't observe DST

Good: const offset = 'America/New_York'; // Uses IANA database with correct historical DST

Pitfall 3: Assuming All Times Are in Same Format

Problem: Not all systems use UTC (e.g., some use GMT, others use UTC+X).

Example: Unix timestamps are always UTC-based, but file systems may vary.

Solution: Always specify timezone explicitly when parsing user input.

Working with Different Timezones

JavaScript

Copy
JAVASCRIPT
1// Best practice: Always specify timezone when creating dates
2const date1 = new Date('2025-01-07T12:00:00'); // UTC time (good)
3
4const date2 = new Date('2025-01-07T12:00:00-08:00'); // Bad: assumes local timezone
5
6// Convert between timezones
7function convertTimezones(fromDate, fromTz, toTz) {
8  return {
9    fromTime: fromDate.toLocaleString('en-US', { timeZone: fromTz }),
10    toTime: fromDate.toLocaleString('en-US', { timeZone: toTz }),
11    fromTimestamp: fromDate.getTime(),
12    toTimestamp: fromDate.toLocaleString('en-US', { timeZone: toTz }),
13  };
14}
15
16// Example: Convert UTC to multiple timezones
17const utcDate = new Date('2025-01-07T12:00:00.000Z');
18const conversions = [
19  convertTimezones(utcDate, 'UTC', 'America/New_York'),
20  convertTimezones(utcDate, 'UTC', 'Asia/Tokyo'),
21  convertTimezones(utcDate, 'UTC', 'Europe/London'),
22];

Python

Copy
PYTHON
1from datetime import datetime, timezone
2
3# Best practice: Use pytz library
4import pytz
5
6def convert_to_timezone(utc_time: datetime, timezone: str) -> datetime:
7    """
8    Convert UTC datetime to specified timezone using IANA timezone database.
9    
10    Args:
11        utc_time: UTC datetime object
12        timezone_str: IANA timezone name
13    
14    Returns:
15        Localized datetime object
16    """
17    utc_time = utc_time.replace(tzinfo=timezone.tzinfo(utc_time))
18    return utc_time.astimezone(timezone)
19
20# Example: Convert current UTC to multiple timezones
21now_utc = datetime.now(timezone.utc)
22now_est = now_utc.astimezone('America/New_York')
23now_gmt = now_utc.astimezone('Etc/GMT')
24now_tokyo = now_utc.astimezone('Asia/Tokyo')
25
26print(f"UTC: {now_utc}")
27print(f"EST: {now_est}")
28print(f"GMT: {now_gmt}")
29print(f"JST: {now_tokyo}")

Timezone Best Practices

Timezone Selection Guidelines

1. Always use IANA timezone names (e.g., "America/New_York", "Europe/London")
2. Use timezone databases (IANA tz database, tz database) instead of hardcoded offsets
3. Test DST transitions in your target regions (especially spring and fall)
4. Document your timezone assumptions clearly in API documentation
5. Consider using UTC for all internal storage and calculations
6. Display timezone names and local times separately in UI (store UTC internally)

Tools and References

Related Tools

• UTC/Local Converter - Convert between UTC and local time
• Timezone Browser - Browse IANA timezone database
• Current Timestamp - Get current UTC timestamp
• Unix Timestamp Converter - Convert between formats
• Timestamp Validator - Validate timestamp formats
• Timestamp Format Converter - Multi-format conversion center

Summary

Key Takeaway: Always store UTC timestamps. Handle timezone conversion at the application or query layer. This ensures data consistency and makes your application globally compatible.

Critical: Never mix UTC and local timestamps in database storage. Always store UTC and convert to local only when needed.

Performance Tip: UTC timestamps are ideal for:

• Database indexing (numeric comparisons)
• Range queries (numeric filters)
• Sorting operations (numeric order)
• Time-based partitioning

Code Examples Repository

For more timestamp and timezone code examples, see our related tools and guides for working with specific use cases:

• Timestamp Format Converter - Format conversions with code generation
• Unix Timestamp Converter - Bidirectional conversions
• UTC/Local Converter - Timezone-specific conversions