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.
Geolocalize um visitante pelo IP sem script de terceiros
A maior parte da geolocalização de IP na web funciona por meio de uma tag JavaScript que chama um terceiro a partir do navegador do visitante. Isso significa mais um script para carregar, mais uma requisição pela qual o navegador precisa esperar e mais uma coisa que pode falhar silenciosamente se o visitante bloqueá-la.
Uma consulta no servidor, em vez disso
O endpoint /v1/ip recebe um endereço IP e retorna diretamente os dados de localização. Se você o chamar a partir do seu próprio backend, usando o endereço IP que o seu servidor web já vê na conexão de entrada, não há nenhum script rodando no navegador do visitante.
GET /v1/ip?ip=203.0.113.42{
"status": "ok",
"ip": "203.0.113.42",
"version": 4,
"found": true,
"country": "France",
"country_code": "FR",
"region": "Ile-de-France",
"city": "Paris",
"postcode": "75001",
"lat": 48.8566,
"lon": 2.3522,
"timezone": "Europe/Paris",
"asn": 12345,
"org": "Example Networks"
}Omitindo o parâmetro de IP
Se você chamar este endpoint sem o parâmetro ip, ele consulta o próprio endereço de quem faz a chamada, o que é conveniente quando o seu backend faz a requisição em nome do visitante conectado a ele no momento. Passar o parâmetro ip explicitamente é o que você quer quando já tem o endereço registrado e vai consultá-lo mais tarde.
O que você recebe
País, região e cidade atendem à maioria dos casos de personalização. O campo timezone significa que muitas vezes você não precisa de uma segunda consulta só para saber a hora local desse visitante. Os campos asn e org identificam a rede à qual o endereço pertence, o que é útil para qualquer coisa além da personalização simples, como identificar provedores de hospedagem ou redes corporativas.
Um caso extremo que vale tratar
Nem todo endereço corresponde a uma localização. O campo found é false para uma faixa reservada, não alocada ou simplesmente ausente do conjunto de dados, e nesse caso os campos de localização estarão ausentes ou vazios. Verifique found antes de ler country ou city, em vez de supor que uma resposta HTTP bem-sucedida sempre significa uma localização utilizável, já que uma requisição para um endereço privado ou reservado ainda retorna 200 com found definido como false.
Um erro que vale a pena evitar
Chamar este endpoint em cada visualização de página, em vez de uma vez por sessão, é a forma mais comum de um site esgotar sua cota sem nenhum benefício real. O endereço IP de um visitante, e portanto sua localização aproximada, normalmente não muda de uma página para a outra durante a mesma visita. Consulte-o uma vez quando a sessão começar, armazene o resultado na sessão e leia essa cópia armazenada em todas as páginas seguintes, em vez de chamar o endpoint novamente.
Custo das requisições e cache
Cada consulta de IP é uma requisição. Como a localização de um visitante raramente muda dentro de uma mesma sessão, consulte-a uma vez e armazene o resultado durante a sessão, em vez de chamá-la a cada visualização de página. Isso mantém um site típico bem dentro das 2.500 requisições gratuitas por dia incluídas em cada chave ou disponíveis a partir de um único endereço, mesmo sem chave.
Uma consulta relacionada
O mesmo endpoint e a mesma estrutura de resposta funcionam para endereços IPv6 sem nenhuma mudança na sua requisição, e o campo version da resposta informa qual família você recebeu. Consulte a documentação da consulta IPv6 se o seu tráfego incluir uma parcela significativa de visitantes IPv6.
Fazer isso no servidor mantém qualquer script de terceiros totalmente fora da sua página, o que importa tanto para a velocidade quanto para a confiabilidade. Consulte a documentação da consulta IPv4 para ver a lista completa de campos.