Comprender los formatos de timestamp

Introducción

Los timestamps existen en distintos formatos y precisiones. Comprenderlos es clave para trabajar con datos temporales, APIs, bases de datos y sistemas distribuidos.

Resumen rápido: los timestamps Unix (segundos, milisegundos, microsegundos, nanosegundos), las cadenas ISO 8601 y el formato RFC 3339 son los más comunes. Cada uno sirve a un propósito diferente en el desarrollo de software.

Formatos de timestamp Unix

Epoch Unix (tiempo POSIX)

El timestamp Unix representa el tiempo como número de segundos/milisegundos desde el 1 de enero de 1970, 00:00:00 UTC.

Unix Epoch Reference:
  Start Date: January 1, 1970, 00:00:00 UTC
  Current: January 1, 2026, 00:00:00 UTC
  Timestamp: 1735689600 (seconds)

Niveles de precisión

Precisión	Ejemplo	Magnitud	Uso común
Segundos	1735689600	10 dígitos	Sistemas Unix/Linux
Milisegundos	17356896000000	13 dígitos	JavaScript, APIs web
Microsegundos	173568960000000000	16 dígitos	Medición de alta precisión
Nanosegundos	173568960000000000000	19 dígitos	Computación científica

Ejemplos de código: distintas precisiones

// JavaScript uses milliseconds by default
const msTimestamp = Date.now(); // 17356896000000
const secTimestamp = Math.floor(Date.now() / 1000); // 1735689600
const nsTimestamp = Date.now() * 1000000; // 173568960000000000000

console.log('Milliseconds:', msTimestamp);
console.log('Seconds:', secTimestamp);
console.log('Nanoseconds:', nsTimestamp);

from datetime import datetime
import time

# Python supports multiple precisions
now = datetime.now(datetime.timezone.utc)
sec_timestamp = int(now.timestamp())
ms_timestamp = int(now.timestamp() * 1000)
us_timestamp = int(now.timestamp() * 1000000)
ns_timestamp = int(now.timestamp() * 1000000000)

print(f'Seconds: {sec_timestamp}')
print(f'Milliseconds: {ms_timestamp}')
print(f'Microseconds: {us_timestamp}')
print(f'Nanoseconds: {ns_timestamp}')

import java.time.Instant;

// Java supports multiple precisions
Instant now = Instant.now();
long secTimestamp = now.getEpochSecond(); // 1735689600
long msTimestamp = now.toEpochMilli(); // 17356896000000
int nsTimestamp = now.getNano(); // Nanoseconds within second

System.out.println("Seconds: " + secTimestamp);
System.out.println("Milliseconds: " + msTimestamp);
System.out.println("Nanoseconds: " + nsTimestamp);

Formato ISO 8601

Definición

ISO 8601 es un estándar internacional para representar fechas y horas. Es el formato más usado para almacenar e intercambiar timestamps.

Variantes de formato

Basic ISO 8601 Formats:
  1. Calendar Date: 2026-01-01
  2. Date and Time: 2026-01-01T12:00:00
  3. With Time Zone: 2026-01-01T12:00:00+08:00
  4. UTC (Z notation): 2026-01-01T12:00:00Z
  5. With Fractional Seconds: 2026-01-01T12:00:00.123Z
  6. With Milliseconds: 2026-01-01T12:00:00.123Z
  7. With Nanoseconds: 2026-01-01T12:00:00.123456789Z

Desglose de ISO 8601

Format: YYYY-MM-DDThh:mm:ss.sssTZD

Components:
  YYYY - Four-digit year (2026)
  MM - Two-digit month (01)
  DD - Two-digit day (01)
  T - Separator between date and time
  hh - Two-digit hour (00-23)
  mm - Two-digit minute (00-59)
  ss - Two-digit second (00-59)
  sss - Fractional seconds (optional)
  TZD - Time zone designator (Z, +08:00, -05:00)

Ejemplos de código: ISO 8601

// JavaScript has built-in ISO 8601 support
const now = new Date();
const isoString = now.toISOString(); // "2026-01-01T12:00:00.000Z"

// Parse ISO 8601
const date = new Date('2026-01-01T12:00:00Z');

console.log('ISO 8601:', isoString);
console.log('Parsed:', date.toISOString());

from datetime import datetime, timezone

# Generate ISO 8601
now_utc = datetime.now(timezone.utc)
iso_string = now_utc.isoformat() # "2026-01-01T12:00:00+00:00"

# Parse ISO 8601
parsed_date = datetime.fromisoformat('2026-01-01T12:00:00+00:00')

print(f'ISO 8601: {iso_string}')
print(f'Parsed: {parsed_date.isoformat()}')

import java.time.Instant;
import java.time.format.DateTimeFormatter;

// Generate ISO 8601
Instant now = Instant.now();
String isoString = now.toString(); // "2026-01-01T12:00:00:00Z"

// Parse ISO 8601
Instant parsed = Instant.parse("2026-01-01T12:00:00:00Z");

System.out.println("ISO 8601: " + isoString);
System.out.println("Parsed: " + parsed);

Formato RFC 3339

Definición

RFC 3339 es un subconjunto de ISO 8601 diseñado específicamente para protocolos de internet y estándares de correo electrónico.

Diferencias con ISO 8601

Característica	ISO 8601	RFC 3339
Formato	Múltiples variantes	Formato fijo
Zona horaria	Puede usar offset o Z	Puede usar offset o Z
Aplicaciones	Propósito general	Protocolos de internet (HTTP, email)
Segundos fraccionales	Opcional	Opcional
Ejemplo	2026-01-01T12:00:00+08:00	2026-01-01T12:00:00+08:00

Nota: RFC 3339 es casi idéntico a ISO 8601. En la práctica se usan de forma intercambiable en aplicaciones de internet.

Ejemplos de código: RFC 3339

// RFC 3339 is similar to ISO 8601
const now = new Date();
const rfc3339String = now.toISOString(); // "2026-01-01T12:00:00.000Z"

// RFC 3339 commonly used in HTTP headers
const httpDate = now.toUTCString(); // "Wed, 01 Jan 2026 12:00:00 GMT"

console.log('RFC 3339:', rfc3339String);
console.log('HTTP Date:', httpDate);

from datetime import datetime, timezone
import email.utils

# Generate RFC 3339 (same as ISO 8601)
now_utc = datetime.now(timezone.utc)
rfc3339_string = now_utc.isoformat() # "2026-01-01T12:00:00+00:00"

# Generate HTTP date format
http_date = email.utils.format_datetime(now_utc)

print(f'RFC 3339: {rfc3339_string}')
print(f'HTTP Date: {http_date}')

Conversión de formatos

Unix Timestamp ↔ ISO 8601

// Unix to ISO 8601
function unixToIso(unixTimestamp, precision = 'ms') {
  let ts = unixTimestamp;
  if (precision === 's') {
    ts = unixTimestamp * 1000;
  } else if (precision === 'us') {
    ts = unixTimestamp / 1000;
  } else if (precision === 'ns') {
    ts = unixTimestamp / 1000;
  } else if (precision === 'ns') {
    ts = unixTimestamp / 1000000;
  }
  return new Date(ts).toISOString();
}

// ISO 8601 to Unix
function isoToUnix(isoString) {
  return Math.floor(new Date(isoString).getTime() / 1000);
}

// Examples
const unixTs = 1735689600;
const isoStr = unixToIso(unixTs); // "2026-01-01T00:00:00.000Z"
const backToUnix = isoToUnix(isoStr); // 1735689600

console.log('Unix → ISO:', isoStr);
console.log('ISO → Unix:', backToUnix);

from datetime import datetime, timezone

def unix_to_iso(unix_timestamp, precision='s'):
    """Convert Unix timestamp to ISO 8601 string"""
    ts = unix_timestamp
    if precision == 's':
        ts = unix_timestamp
    elif precision == 'ms':
        ts = unix_timestamp / 1000
    elif precision == 'us':
        ts = unix_timestamp / 1000
    elif precision == 'ns':
        ts = unix_timestamp / 1000000
    elif precision == 'ns':
        ts = unix_timestamp / 1000000000

    dt = datetime.fromtimestamp(ts, timezone.utc)
    return dt.isoformat()

def iso_to_unix(iso_string):
    """Convert ISO 8601 string to Unix timestamp"""
    dt = datetime.fromisoformat(iso_string)
    return int(dt.timestamp())

# Examples
unix_ts = 1735689600
iso_str = unix_to_iso(unix_ts)  # "2026-01-01T00:00:00+00:00"
back_to_unix = iso_to_unix(iso_str)  # 1735689600

print(f'Unix → ISO: {iso_str}')
print(f'ISO → Unix: {back_to_unix}')

Detección de precisión

Detectar precisión de timestamp Unix

function detectPrecision(timestamp) {
  const str = timestamp.toString();

  if (str.length === 10) {
    return 'seconds';
  } else if (str.length === 13) {
    return 'milliseconds';
  } else if (str.length === 16) {
    return 'microseconds';
  } else if (str.length === 19) {
    return 'nanoseconds';
  }

  return 'unknown';
}

// Examples
console.log(detectPrecision(1735689600)); // "seconds"
console.log(detectPrecision(17356896000000)); // "milliseconds"
console.log(detectPrecision(173568960000000000)); // "microseconds"
console.log(detectPrecision(173568960000000000000)); // "nanoseconds"

def detect_precision(timestamp):
    """Detect Unix timestamp precision"""
    str_ts = str(int(timestamp))

    if len(str_ts) == 10:
        return 'seconds'
    elif len(str_ts) == 13:
        return 'milliseconds'
    elif len(str_ts) == 16:
        return 'microseconds'
    elif len(str_ts) == 19:
        return 'nanoseconds'

    return 'unknown'

# Examples
print(detect_precision(1735689600))  # "seconds"
print(detect_precision(173568960000000))  # "milliseconds"
print(detect_precision(173568960000000000))  # "microseconds"
print(detect_precision(173568960000000000000))  # "nanoseconds"

Tabla comparativa

Unix Timestamp vs ISO 8601 vs RFC 3339

Aspecto	Unix Timestamp	ISO 8601	RFC 3339
Formato	Número (entero/float)	Cadena	Cadena
Legible por humanos	No	Sí	Sí
Zona horaria	No (UTC implícito)	Sí (opcional)	Sí (opcional)
Precisión	Configurable	Configurable	Configurable
Tamaño de almacenamiento	4-8 bytes	20-30 bytes	20-30 bytes
Soporte en DB	Universal	Universal	Universal
Uso común	Timestamps del sistema	APIs, JSON, DB	HTTP, email, APIs
Ejemplo	1735689600	2026-01-01T12:00:00:00Z	2026-01-01T12:00:00:00Z

Recomendación: usa timestamps Unix para almacenamiento interno y cálculos. Usa ISO 8601/RFC 3339 para APIs, intercambio de datos y formatos legibles.

Mejores prácticas

Almacenamiento

1. Usa timestamps Unix en bases de datos para almacenamiento e indexación eficientes
2. Usa ISO 8601 para APIs externas y el intercambio de datos
3. Incluye zona horaria al mostrar al usuario
4. Documenta el formato en comentarios del esquema

-- Best practice: Store Unix timestamp in database
CREATE TABLE events (
  id INT PRIMARY KEY,
  event_timestamp BIGINT,  -- Unix timestamp in milliseconds
  description TEXT,
  created_at TIMESTAMP WITHOUT TIME ZONE DEFAULT NOW()
);

Respuestas de API

1. Usa ISO 8601 en cuerpos de respuesta
2. Incluye timestamp Unix para uso programático
3. Especifica la zona horaria claramente

{
  "event": {
    "id": 123,
    "timestamp": 173568960000000,
    "iso8601": "2026-01-01T12:00:00:00Z",
    "timezone": "UTC",
    "human_readable": "January 1, 2026 at 12:00:00 AM UTC"
  }
}

Manejo de errores

1. Valida el formato antes de parsear
2. Maneja segundos intercalares en aplicaciones de alta precisión
3. Degradación controlada para formatos desconocidos

// Validate ISO 8601 format
function isValidISO8601(str) {
  const isoRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2}:\d{2})?$/;
  return isoRegex.test(str);
}

// Handle parsing errors
function safeParseISO8601(str) {
  try {
    return new Date(str);
  } catch (error) {
    console.error('Invalid ISO 8601 format:', str);
    return new Date(); // Fallback to current time
  }
}

Errores comunes

Error 1: asumir que el timestamp Unix siempre está en segundos

// ❌ Wrong: Always dividing by 1000
const timestamp = Date.now();
const wrongDate = new Date(timestamp / 1000); // Incorrect division

// ✅ Right: Check precision first
const date = new Date(timestamp); // Date accepts milliseconds directly

Error 2: ignorar zonas horarias

// ❌ Wrong: Creating local time without timezone
const localTime = new Date('2026-01-01T12:00:00'); // Ambiguous

// ✅ Right: Specify timezone explicitly
const utcTime = new Date('2026-01-01T12:00:00Z'); // Clear UTC
const tokyoTime = new Date('2026-01-01T12:00:00+09:00'); // Tokyo time

Error 3: mezclar formatos

// ❌ Wrong: Inconsistent formats in API
{
  "timestamp": 1735689600,
  "date": "01/01/2026",
  "time": "12:00 PM",
  "datetime": "2026-01-01 12:00"
}

// ✅ Right: Consistent ISO 8601 format
{
  "timestamp": 1735689600,
  "iso8601": "2026-01-01T12:00:00:00Z",
  "timezone": "UTC"
}

Herramientas relacionadas

• Unix Timestamp Converter - Convierte entre timestamps Unix y fechas con detección automática de precisión
• ISO 8601 Converter - Convierte hacia/desde ISO 8601
• RFC 3339 Converter - Trabaja con formato RFC 3339
• Current Timestamp - Hora actual en varios formatos y precisiones
• Timestamp Validator - Valida y detecta formatos de timestamp

Preguntas frecuentes

P: ¿Cuál es la diferencia entre ISO 8601 y RFC 3339?

R: RFC 3339 es un subconjunto de ISO 8601 diseñado para protocolos de internet. En la práctica son casi idénticos, pero RFC 3339 es más estricto.

P: ¿Cómo sé si un timestamp Unix está en segundos o milisegundos?

R: Cuenta los dígitos: 10 dígitos = segundos, 13 dígitos = milisegundos. También puedes revisar el año (segundos = 1970+, milisegundos = 1970+).

P: ¿Qué precisión debo usar?

R: Milisegundos para apps web (default de JavaScript), segundos para eficiencia en base de datos o micro/nanosegundos para alta precisión.

P: ¿ISO 8601 soporta zonas horarias?

R: Sí, soporta offsets (+08:00) y la notación Z para UTC.

P: ¿Cómo manejo zonas horarias con timestamps Unix?

R: Los timestamps Unix siempre están en UTC. Convierte a hora local solo para mostrar al usuario.

P: ¿Cuál es el valor máximo de un timestamp Unix?

R: En sistemas de 64 bits, el problema de 2038 no aplica. El máximo teórico es de miles de millones de años en el futuro.