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.
Encuentra la zona horaria de cualquier latitud y longitud
Las coordenadas por sí solas no te dicen qué hora es en un punto del mapa. El endpoint de zona horaria recibe una latitud y una longitud y devuelve el nombre de la zona horaria, su desfase UTC actual y su abreviatura.
Hacer la solicitud
GET /v1/timezone?lat=52.3676&lon=4.9041{
"status": "ok",
"timezone": "Europe/Amsterdam",
"utc_offset": "+02:00",
"abbreviation": "CEST"
}El campo timezone es un identificador estándar que puedes pasar directamente a la mayoría de las bibliotecas de fecha y hora. Los campos utc_offset y abbreviation son útiles para mostrar información cuando quieres enseñar al lector algo más familiar que una cadena identificadora.
Un segundo ejemplo, al otro lado de la línea de cambio de fecha
Los desfases no siempre son números pequeños y redondos, y algunos lugares están al otro lado de la línea de cambio de fecha respecto a la mayor parte de la población mundial.
GET /v1/timezone?lat=-17.7333&lon=168.3273{
"status": "ok",
"timezone": "Pacific/Efate",
"utc_offset": "+11:00",
"abbreviation": "VUT"
}Trata el identificador devuelto de la misma manera sin importar lo lejos que esté del reloj de tu propio servidor. Tu biblioteca de fechas ya sabe manejar correctamente un desfase de once horas, así que no hay ningún caso especial que programar para ubicaciones alejadas de tu propia zona horaria.
Combinarlo con la geocodificación
Este endpoint solo necesita coordenadas, así que se combina de forma natural con la geocodificación directa o inversa. Geocodifica primero una dirección para obtener su latitud y longitud y luego pásalas directamente a /v1/timezone para saber en qué zona está esa ubicación, sin preguntarle al usuario nada sobre zonas horarias.
Un atajo relacionado
Si ya tienes la dirección IP de un visitante en lugar de una dirección geocodificada, el endpoint /v1/ip devuelve un campo timezone directamente en su propia respuesta, sin necesidad de una llamada aparte a este endpoint. Usa /v1/timezone directamente cuando ya tengas coordenadas sin una consulta de IP asociada, como una dirección del perfil de envío de un cliente.
Tener en cuenta el horario de verano
Los campos utc_offset y abbreviation reflejan el desfase vigente en el momento por el que preguntaste. Si te interesa una fecha concreta y no el momento actual, pasa una marca de tiempo unix con el parámetro time para que la respuesta refleje el desfase que se aplicaba en esa fecha, no el de hoy.
GET /v1/timezone?lat=52.3676&lon=4.9041&time=1731000000Un error que conviene evitar
Llamar a este endpoint una vez y guardar en caché el valor de utc_offset a largo plazo es un atajo habitual que falla dos veces al año en los lugares que aplican el horario de verano. El identificador de la zona horaria en sí es estable y seguro para guardar en caché. El desfase y la abreviatura no lo son, ya que cambian con el calendario, así que vuelve a calcularlos en el momento de mostrarlos en lugar de almacenarlos junto al identificador.
Lo que cuesta
Cada consulta de zona horaria es una solicitud. Si ya geocodificas una dirección como parte de un flujo de registro o de pago, añadir una consulta de zona horaria para la misma ubicación duplica el número de solicitudes de ese flujo, de una a dos, lo que sigue siendo insignificante frente a las 2.500 solicitudes gratuitas al día incluidas con cada clave.
Es fácil equivocarse con los datos de zona horaria cuando se manejan a mano, sobre todo en torno a los cambios de horario de verano, así que vale la pena obtenerlos de una única fuente en lugar de mantener tu propia tabla de desfases. La documentación de consulta de zona horaria incluye la lista completa de parámetros.