Monitore o uso da sua chave antes de atingir um limite
Acompanhar seus cabeçalhos de cota ao longo do caminho mostra quando um limite está se aproximando, bem antes de uma requisição ser realmente rejeitada.
Converta um registro de data e hora UTC para a hora local dos seus usuários
Armazenar timestamps em UTC é a escolha certa para um banco de dados. Mostrar UTC a um usuário em um chamado de suporte, em uma confirmação de pedido ou em um log de atividades não é, e isso é uma das pequenas frustrações mais comuns na interface de um produto.
A conversão em duas etapas
Primeiro, saiba a partir de onde o timestamp deve ser interpretado, seja pelas coordenadas de um endereço cadastrado ou pelas coordenadas de uma consulta de IP. Segundo, passe essas coordenadas e o próprio timestamp UTC para /v1/timezone usando o parâmetro time, para que o fuso retornado corresponda ao momento em questão, e não ao momento atual.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1734000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-05:00",
"abbreviation": "EST"
}Aplique o utc_offset ao seu timestamp UTC armazenado, ou passe o identificador do fuso horário para o seu próprio código de formatação de datas, e exiba o resultado em vez do valor UTC bruto.
Um segundo exemplo, com meses de diferença
As mesmas coordenadas retornam uma diferença de UTC diferente dependendo do timestamp que você passa, e é exatamente por isso que o parâmetro time existe.
GET /v1/timezone?lat=40.7128&lon=-74.0060&time=1719000000{
"status": "ok",
"timezone": "America/New_York",
"utc_offset": "-04:00",
"abbreviation": "EDT"
}Observe que a diferença passou de menos cinco horas para menos quatro horas entre as duas chamadas para exatamente o mesmo local, apenas porque um timestamp cai no horário de verão e o outro não. Uma exibição que ignorasse isso e aplicasse uma única diferença fixa aos dois ficaria uma hora errada em um deles.
Por que o parâmetro time importa
A diferença de UTC muda ao longo do ano na maioria dos lugares que adotam horário de verão. Se você sempre chamar o endpoint sem o parâmetro time, vai receber a diferença de hoje, que estará errada para um timestamp de seis meses atrás. Sempre passe o timestamp que você está convertendo, e não o horário atual, quando os dois puderem cair em lados opostos de uma mudança de horário de verão.
Armazene em cache o fuso horário, não a diferença
O identificador de fuso horário para um conjunto de coordenadas raramente muda, então é seguro armazenar em cache a própria string timezone associada a um local. Os valores utc_offset e abbreviation não são seguros para cache por muito tempo, já que mudam com o horário de verão, então recalcule-os no momento da exibição em vez de armazená-los.
Um caso extremo que vale conhecer
Nem todo local adota horário de verão. Um local que mantém uma diferença fixa o ano todo vai retornar o mesmo utc_offset qualquer que seja o timestamp que você passar, o que é o comportamento esperado, e não um sinal de que o parâmetro time foi ignorado. Não presuma que um resultado igual para dois timestamps diferentes significa que algo está quebrado.
Custo das requisições
Uma conversão é uma requisição. Um painel que converte horários de muitos registros armazenados de uma vez deve agrupar as coordenadas correspondentes em um POST em lote em vez de percorrer um timestamp por vez, mantendo o mesmo custo de uma requisição por item, mas em uma única chamada.
Acertar o horário local importa mais do que a maioria das equipes imagina, até que um chamado de suporte mostre a hora errada. Os detalhes dos campos de requisição e de resposta estão na documentação da consulta de fuso horário.