> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryprofound.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rangos de fechas y zonas horarias

> Cómo trabajar con fechas y zonas horarias en la API de Profound

## Descripción general

Todos los datos de nuestro sistema se almacenan en UTC, pero nuestro procesamiento se ejecuta según un horario EST (Eastern Standard Time). Comprender cómo funcionan los rangos de fechas es fundamental para consultar los datos correctos para tu caso de uso.

<Warning>
  Un manejo incorrecto de las zonas horarias es la causa más común de datos faltantes o inesperados en las respuestas de la API. Lee esta guía con atención.
</Warning>

## Comportamiento del sistema

### Horario de procesamiento de datos

Nuestro sistema procesa los datos según la zona horaria EST:

* El "día" 1 de enero EST comienza a las **00:00 EST** (05:00 UTC)
* El "día" 1 de enero EST termina a las **23:59 EST** (04:59 UTC del día siguiente)

Todos los datos se almacenan con marcas de tiempo UTC en nuestra base de datos.

### Formatos de fecha admitidos

La API acepta fechas en varios formatos:

1. **Solo fecha** (recomendado para consultas diarias): `2025-01-01`
2. **Fecha y hora sin zona horaria**: `2025-01-01T00:00:00`
3. **Fecha y hora con zona horaria UTC**: `2025-01-01T05:00:00Z`

## Cómo se interpretan las fechas

### Sin especificar la zona horaria

Cuando proporcionas una fecha **sin zona horaria** (sin el sufijo `Z`), la API la interpreta como **EST**:

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-01-31"
}
```

**Qué ocurre:**

* `2025-01-01` → Se interpreta como `2025-01-01T00:00:00 EST` → Se convierte a `2025-01-01T05:00:00Z` UTC
* `2025-01-31` → Se interpreta como `2025-01-31T00:00:00 EST` → Se convierte a `2025-01-31T05:00:00Z` UTC

Esto coincide con la forma en que nuestro sistema define los "días" y es el **enfoque recomendado** para la mayoría de los casos de uso.

### Con zona horaria UTC (sufijo Z)

Cuando proporcionas una fecha **con el sufijo Z**, la API la interpreta como **UTC literal**:

```json theme={null}
{
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-02-01T00:00:00Z"
}
```

**Qué ocurre:**

* `2025-01-01T00:00:00Z` → Se usa tal cual en UTC
* `2025-02-01T00:00:00Z` → Se usa tal cual en UTC

<Warning>
  Usar marcas de tiempo UTC (con Z) requiere que conviertas manualmente de EST a UTC. Este enfoque existe por compatibilidad con versiones anteriores, pero **no se recomienda** para integraciones nuevas.
</Warning>

## Ejemplos

### Correcto: consultar los datos de enero de 2025 (días EST)

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-02-01"
}
```

Esto devuelve todos los datos desde:

* Inicio: 1 de enero, 00:00 EST (05:00 UTC del 1 de enero)
* Fin: 1 de febrero, 00:00 EST (05:00 UTC del 1 de febrero)

El rango es inclusivo (`<=`), pero como los datos normalmente no tienen marcas de tiempo exactamente a las 00:00, en la práctica esto abarca todo enero.

### Incorrecto: consultar enero de 2025 con medianoche UTC

```json theme={null}
{
  "start_date": "2025-01-01T00:00:00Z",
  "end_date": "2025-02-01T00:00:00Z"
}
```

Esto devuelve datos desde:

* Inicio: 31 de diciembre, 19:00 EST (00:00 UTC del 1 de enero)
* Fin: 31 de enero, 19:00 EST (00:00 UTC del 1 de febrero)

**Problema:** te faltan 5 horas al inicio e incluyes 5 horas que no quieres al final.

### Correcto: consultar enero de 2025 con UTC (conversión manual)

Si debes usar marcas de tiempo UTC, tienes que tener en cuenta el desfase de EST:

```json theme={null}
{
  "start_date": "2025-01-01T05:00:00Z",
  "end_date": "2025-02-01T05:00:00Z"
}
```

Esto abarca correctamente todo enero (días EST), pero requiere cálculos manuales de zona horaria.

## Rangos horarios

### El formato de solo fecha usa medianoche por defecto

Cuando usas el formato de solo fecha, la hora predeterminada es `00:00:00`:

```json theme={null}
{
  "start_date": "2025-01-01"  // Equivalent to 2025-01-01T00:00:00 EST
}
```

### Especificar horas exactas

Puedes especificar horas exactas para consultas más detalladas:

```json theme={null}
{
  "start_date": "2025-01-01T08:00:00",  // 8 AM EST
  "end_date": "2025-01-01T17:00:00"     // 5 PM EST
}
```

Esto consulta los datos de 8 AM a 5 PM EST del 1 de enero.

### Comportamiento de los rangos de fechas

Los rangos de fechas son **inclusivos** en ambos extremos `(start <= x <= end)`:

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-01-02"
}
```

Esto incluye:

* Todo el 1 de enero (desde las 00:00 EST en adelante)
* El 2 de enero exactamente a las 00:00 EST
* Como los datos tienen marcas de tiempo a lo largo del día, normalmente no hay datos exactamente a las 00:00, así que en la práctica esto abarca todo el 1 de enero

Para consultar un solo día, establece `end_date` en el día siguiente a las 00:00.

## Prácticas recomendadas

<Check>
  **Recomendado:** usa el formato de solo fecha sin zona horaria para consultas diarias
</Check>

```json theme={null}
{
  "start_date": "2025-01-01",
  "end_date": "2025-02-01"
}
```

<Check>
  **Recomendado:** usa fecha y hora sin zona horaria para consultas dentro del mismo día
</Check>

```json theme={null}
{
  "start_date": "2025-01-15T09:00:00",
  "end_date": "2025-01-15T17:00:00"
}
```

<Check>
  **Recomendado:** usa fecha y hora sin zona horaria para consultas de informes por hora (a través de la pestaña **V2 (hourly)** de [Agent Analytics](/es/rest-api/examples/agent-analytics))
</Check>

```json theme={null}
{
  "start_date": "2025-01-15T14:00:00",
  "end_date": "2025-01-15T14:59:59"
}
```

<Warning>
  **Usuarios de zonas horarias con desfase fraccionario:** al consultar con granularidad por hora con `/v2/reports/*`, consulta 2 horas consecutivas para obtener datos completos de una sola hora local. Consulta [Zonas horarias con desfase fraccionario](#fractional-offset-timezones) para más detalles.
</Warning>

<Warning>
  **Evita:** usar el sufijo Z a menos que comprendas las implicaciones del desfase UTC
</Warning>

```json theme={null}
{
  "start_date": "2025-01-01T00:00:00Z",  // Probably not what you want
  "end_date": "2025-02-01T00:00:00Z"
}
```

## Horario de verano

EST aplica el horario de verano (DST):

* **Horario estándar (EST):** UTC-5 (normalmente de noviembre a marzo)
* **Horario de verano (EDT):** UTC-4 (normalmente de marzo a noviembre)

La API gestiona automáticamente las transiciones del horario de verano. Cuando especificas fechas sin zona horaria, la conversión a UTC tiene en cuenta si el horario de verano estaba activo en esa fecha.

**Ejemplo durante el horario de verano:**

```json theme={null}
{
  "start_date": "2025-07-01"  // Interpreted as EDT (UTC-4)
}
```

→ Se convierte a `2025-07-01T04:00:00Z` UTC (no 05:00 debido al horario de verano)

## Zonas horarias con desfase fraccionario

Algunas zonas horarias usan desfases UTC fraccionarios en lugar de horas completas:

| Zona horaria | Desfase UTC |
| - | - |
| Hora estándar de India (IST) | +5:30 |
| Hora de Afganistán (AFT) | +4:30 |
| Hora de Myanmar (MMT) | +6:30 |
| Hora de Nepal (NPT) | +5:45 |
| Islas Chatham (CHAST) | +12:45 |
| Islas Marquesas (MART) | -9:30 |

Como los intervalos por hora están alineados con los límites de hora completa en UTC, una sola hora local en estas zonas horarias siempre abarcará dos intervalos por hora. Para obtener datos completos de cualquier hora local, debes consultar **2 horas consecutivas**.

### Ejemplo: consultar las 2:00 PM IST

IST es UTC+5:30, por lo que las 2:00 PM IST = 08:30 UTC. La hora de 2:00 PM a 3:00 PM IST (08:30 - 09:30 UTC) abarca dos intervalos horarios UTC:

* **08:00 - 08:59 UTC** (contiene los primeros 30 minutos: 2:00 PM - 2:30 PM IST)
* **09:00 - 09:59 UTC** (contiene los últimos 30 minutos: 2:30 PM - 3:00 PM IST)

Para obtener la hora completa, consulta ambos intervalos:

```json theme={null}
{
  "start_date": "2025-01-15T08:00:00Z",
  "end_date": "2025-01-15T09:59:59Z"
}
```

<Warning>
  Esto se aplica al consultar con **granularidad por hora** a través de `/v2/reports/*`. Si estás en una zona horaria con desfase fraccionario y solicitas datos por hora, solicita siempre 2 horas consecutivas para no perder los datos que caen en el intervalo adyacente.
</Warning>

## Solución de problemas

### Faltan datos en los límites del día

**Problema:** consultas el 1 de enero, pero faltan las primeras o las últimas horas.

**Solución:** asegúrate de no usar el sufijo `Z`. Usa `"start_date": "2025-01-01"` en lugar de `"start_date": "2025-01-01T00:00:00Z"`.

### Aparecen datos del día anterior o siguiente

**Problema:** tu consulta diaria incluye datos de días adyacentes.

**Solución:** probablemente estés usando el sufijo `Z` con medianoche UTC, que no se alinea con los días EST. Elimina el sufijo de zona horaria.

### Comportamiento inesperado con el horario de verano

**Problema:** tus consultas tienen una diferencia de 1 hora durante las transiciones del horario de verano.

**Solución:** deja que la API gestione el horario de verano automáticamente usando fechas sin zona horaria. Si debes usar UTC, recuerda que el desfase cambia entre EST (-5) y EDT (-4).

## Cambios futuros

<Note>
  En una versión futura de la API, planeamos admitir desfases de zona horaria ISO 8601 completos (por ejemplo, `-05:00`, `+09:00`) para permitir consultas en varias zonas horarias. En ese momento, las fechas sin especificación de zona horaria quedarán obsoletas.
</Note>

Por ahora, el enfoque recomendado es usar fechas sin zona horaria y dejar que la API se encargue de la conversión a EST por ti.