Controla el uso de tu clave antes de alcanzar un límite
Vigilar las cabeceras de cuota sobre la marcha te indica cuándo te acercas a un límite, mucho antes de que se rechace realmente una solicitud.
Convierte una marca de tiempo UTC a la hora local de tus usuarios
Guardar las marcas de tiempo en UTC es lo correcto para una base de datos. Mostrar UTC a un usuario en un ticket de soporte, una confirmación de pedido o un registro de actividad no lo es, y es una de las pequeñas frustraciones más comunes en la interfaz de un producto.
La conversión en dos pasos
Primero, determina desde dónde debe interpretarse la marca de tiempo, ya sea con las coordenadas de una dirección registrada o con las coordenadas de una consulta de IP. Segundo, pasa esas coordenadas y la propia marca de tiempo UTC a /v1/timezone mediante el parámetro time, para que el desfase devuelto corresponda al momento en cuestión y no al momento actual.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1734000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-05:00",
"abbreviation": "EST"
}Aplica el utc_offset a tu marca de tiempo UTC almacenada, o pasa el identificador de zona horaria a tu propio código de formato de fechas, y muestra el resultado en lugar del valor UTC sin procesar.
Un segundo ejemplo, con meses de diferencia
Las mismas coordenadas devuelven un desfase distinto según la marca de tiempo que pases, que es precisamente la razón de que exista el parámetro time.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1719000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-04:00",
"abbreviation": "EDT"
}Fíjate en que el desfase pasó de menos cinco horas a menos cuatro horas entre las dos llamadas para exactamente la misma ubicación, únicamente porque una marca de tiempo cae en horario de verano y la otra no. Una visualización que ignorara esto y aplicara un único desfase fijo a ambas tendría una hora de error en una de ellas.
Por qué importa el parámetro time
El desfase cambia a lo largo del año en la mayoría de los lugares que aplican el horario de verano. Si siempre llamas al endpoint sin el parámetro time, obtienes el desfase de hoy, que será incorrecto para una marca de tiempo de hace seis meses. Pasa siempre la marca de tiempo que estás convirtiendo, no la hora actual, cuando ambas puedan caer en lados opuestos de un cambio de horario de verano.
Guardar en caché la zona horaria, no el desfase
El identificador de zona horaria de un conjunto de coordenadas rara vez cambia, así que es seguro guardar en caché la propia cadena timezone asociada a una ubicación. Los valores utc_offset y abbreviation no son seguros para guardarlos en caché mucho tiempo, ya que cambian con el horario de verano, así que vuelve a calcularlos en el momento de mostrarlos en lugar de almacenarlos.
Un caso límite que conviene conocer
No todas las ubicaciones aplican el horario de verano. Una ubicación que mantiene un desfase fijo todo el año devolverá el mismo utc_offset sea cual sea la marca de tiempo que pases, lo cual es el comportamiento esperado y no una señal de que se haya ignorado el parámetro time. No des por hecho que un resultado fijo para dos marcas de tiempo distintas significa que algo está roto.
Coste en solicitudes
Una conversión es una solicitud. Un panel que convierte a la vez las horas de muchos registros almacenados debería agrupar las coordenadas subyacentes en un POST masivo en lugar de recorrerlas una marca de tiempo cada vez, manteniendo el mismo costo de una solicitud por elemento pero en una sola llamada.
Acertar con la hora local importa más de lo que la mayoría de los equipos esperan, hasta que un ticket de soporte muestra la hora equivocada. Encontrarás los detalles de los campos de solicitud y respuesta en la documentación de consulta de zona horaria.