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.
Descubra o fuso horário de qualquer latitude e longitude
As coordenadas sozinhas não dizem que horas são em um ponto do mapa. O endpoint de fuso horário recebe latitude e longitude e retorna o nome do fuso horário, seu deslocamento UTC atual e sua abreviação.
Fazendo a requisição
GET /v1/timezone?lat=52.3676&lon=4.9041{
"status": "ok",
"timezone": "Europe/Amsterdam",
"utc_offset": "+02:00",
"abbreviation": "CEST"
}O campo timezone é um identificador padrão que você pode passar diretamente para a maioria das bibliotecas de data e hora. Os campos utc_offset e abbreviation são úteis para exibição, quando você quer mostrar ao leitor algo mais familiar do que uma string de identificador.
Um segundo exemplo, do outro lado da linha internacional de data
Os deslocamentos nem sempre são números pequenos e redondos, e alguns lugares ficam do outro lado da linha internacional de data em relação à maior parte da população mundial.
GET /v1/timezone?lat=-17.7333&lon=168.3273{
"status": "ok",
"timezone": "Pacific/Efate",
"utc_offset": "+11:00",
"abbreviation": "VUT"
}Trate o identificador retornado da mesma forma, independentemente de quão distante ele esteja do relógio do seu próprio servidor. A sua biblioteca de datas já sabe lidar corretamente com um deslocamento de onze horas, então não há nenhum caso especial a escrever para locais distantes do seu próprio fuso horário.
Combinando com a geocodificação
Este endpoint só precisa de coordenadas, então combina naturalmente com a geocodificação direta ou reversa. Geocodifique primeiro um endereço para obter sua latitude e longitude e depois passe esses valores diretamente para /v1/timezone para descobrir em qual fuso esse local está, sem perguntar nada ao usuário sobre fusos horários.
Um atalho relacionado
Se você já tem o endereço IP de um visitante em vez de um endereço geocodificado, o endpoint /v1/ip retorna um campo timezone diretamente na própria resposta, sem nenhuma chamada separada a este endpoint. Use /v1/timezone diretamente quando você já tem coordenadas sem uma consulta de IP associada, como um endereço do perfil de entrega de um cliente.
Considerando o horário de verão
Os campos utc_offset e abbreviation refletem o deslocamento em vigor no momento consultado. Se você se interessa por uma data específica, e não pelo momento atual, passe um timestamp unix no parâmetro time para que a resposta reflita o deslocamento que valia naquela data, e não o deslocamento de hoje.
GET /v1/timezone?lat=52.3676&lon=4.9041&time=1731000000Um erro que vale a pena evitar
Chamar este endpoint uma vez e armazenar o valor de utc_offset em cache por muito tempo é um atalho comum que falha duas vezes por ano em lugares que adotam horário de verão. O identificador de fuso horário em si é estável e seguro para cache. O deslocamento e a abreviação não são, já que mudam com o calendário, então recalcule-os no momento da exibição em vez de armazená-los junto com o identificador.
Quanto custa
Cada consulta de fuso horário é uma requisição. Se você já geocodifica um endereço como parte de um fluxo de cadastro ou de checkout, adicionar uma consulta de fuso horário para o mesmo local dobra a contagem de requisições desse fluxo, de uma para duas, o que ainda é irrelevante diante das 2.500 requisições gratuitas por dia incluídas em cada chave.
Dados de fuso horário são fáceis de errar manualmente, especialmente perto das transições do horário de verão, então vale a pena obtê-los de uma única fonte em vez de manter sua própria tabela de deslocamentos. A documentação da consulta de fuso horário traz a lista completa de parâmetros.