HG IP Location Documentação
API de geolocalização por IP
Documentação
Índice
Introdução
Obter a localição de seu usuário é muito importante para entender seu público.
O HG IP Location é uma API que fornece dados dados de geolocalização através do endereço de IP de seu usuário.
API fácil de implementar, com respostas e parâmetros objetivos, com bibliotecas em PHP, Ruby e JavaScript. (em breve)
Mesmo que sua aplicação não seja com essas linguagens, abaixo você pode conferir como integrar a API.
Todos esses dados referentes ao IP são retornados na mesma requisição de uma só vez, sendo esses dados:
Em uma só requisição, você pode obter:
- cidade, estado e país;
- maiores informações sobre o país como imagens da bandeira, capital e DDI*;
- latitude e longitude da cidade encontrada;
- código WOEID para que seja simples uma consulta posterior de previsão do tempo usando o HG Weather.
Tudo isso em uma só requisição.
Essa API requer o uso de uma chave para funcionar, o limite de consultas é compartilhado com as requisições do HG Weather.
O modo de alta precisão traz dados mais apurados e requer a contratação de um plano da API, conheça nossos planos clicando aqui.
* Alguma dessas informações podem estar disponíveis apenas no modo de alta precisão.
Todas as requisições em como base o seguinte endpoint:
Estrutura de dados
Os dados referentes à consulta chegam no parâmetro results
, você também pode conferir a autenticação de sua chave no parâmetro de retorno valid_key
e verificar no by
se a consulta foi feita pelo modo de address_precision (consulta de alta precisão) ou address_standard (consulta normal).
address
- endereço de IP consultadotype
- ipv4 ou ipv6city
- cidaderegion
- região/estadocountry_name
- nome do paíscontinent
- continente do IP no idioma selecionadocontinent_code
- código do continenteregion_code
- código da região/estadoisp
- provedor de internet (necessita do plano Professional ou acima, somente requisição precision)-
country
- objeto com os dados do paísname
- nome do paíscode
- código do paíscapital
- capital do país-
flag
- objeto com a bandeira do paísname
- nome da moedabuy
- valor para compra
calling_code
- DDI do país
latitude
- latitude da cidadelongitude
- longitude da cidadewoeid
- código da cidade para consulta no HG Weather
Você pode personalizar o resultado da consulta omitindo alguns dados veja como.
Autenticação e chave
A API do HG IP Location é de acesso aberto, os dados em si são retornados mesmo sem ter um plano contratado.
Um plano apenas é exigido para obtenção de dados de alta precisão.
Para utilização dessa API, é necessário que uma chave seja informada, mesmo que usando o plano gratuito.
Seus limites de consulta serão maiores do que o acesso sem chave.
Você pode consultar os limites de busca com e sem chave neste link.
Sua chave deve ser informada em toda requisição, utilizando o parâmetro key
.
Obtendo os dados de geolocalização via IP
Obtendo os dados de geolocalização do endereço de IP.
Requer chave: sim
Parâmetros
user_ip
- IP de seu usuário exemplo000.000.000.000
ou envieremote
para o sistema obter o IP com base no cliente.precision
- boolean, padrãofalse
, envietrue
para obter os dados de alta precisão
Os limites de consulta para esse modo são tratados de forma mensal e não diária como são nos demais endpoints das APIs HG Brasil.
Aumente seus limites na API ou obtenha suporte
Conheça as vantagens de ser membro da API
Sendo assinante, além de ajudar a manter o serviço para a comunidade, você terá acesso ao nosso suporte, maiores limites de consulta e recursos exclusivos.
Quero conhecerFormatos de retorno
Você pode escolher o formato de resposta da API através do parâmetro format
na sua requisição.
Formatos disponíveis
json
- retorno em JSON, padrãojson-cors
- retorno em JSON com headers CORS, chave exposta requeridaphp-serialize
- serialização do PHP (antigo formato da API)debug
- JSON visual para humanos, apenas para testes, não utilizar em produção
Esse formato requer uma chave válida e seu domínio, exatamente igual ao utilizado no site, deve ser cadastrado no momento da criação da chave.
Personalizando a resposta
Algumas aplicações, como IOT, tem menos poder em processar e parsear dados. Por isso você pode em sua requisição, solicitar que alguns dados sejam omitidos, para que apenas os dados que você necessite sejam exibidos.
Você pode escolher quais campos são retornados, limitar arrays ou ignorar os retornos de status e chave. Este recurso é compatível apenas com o formato JSON e requer o uso de sua chave de API.
-
fields
- neste parâmetro você configura o recurso e escolhe quais campos manter, dados válidos abaixo, você pode colocar mais de um, separados por vírgulaonly_results
- remove os dados de status, cache e chave, enviando apenas os resultadosnome-do-campo
- nome do campo desejado
array_limit
- inteiro limitando o número de itens em arrays do retorno
Qualquer forma de busca pode ser utilizada junto a este método.
Dicas de boas práticas
Faça cache
Para que seus limites de consulta sejam utilizados da melhor forma possível, faça cache de suas requisições.
Cada pageview do seu site ou aplicação, não necessita necessáriamente de uma nova consulta ao HG IP Location.
Por exemplo, se seu usuário acabou de entrar, faça uma consulta (mesmo que seja no lado do cliente), mas assim que o dado for obtido, salve em um armazenamento local ou temporário para que na próxima página que seu usuário entrar, essa consulta não seja necessária.
Não deixe consultas de alta precisão expostas
Consultas de IP de alta precisão exigem um plano e são bem limitadas devido seu custo.
Não é recomendado fazer essas consultas de forma exporta, por exemplo via JavaScript no browser, pois seu limite pode ser atingido rapidamente.
Utilize rotinas
Se sua aplicação permitir, utilize rotinas ou threads para obter os dados. Isso pode melhorar o tempo final de resposta do seu serviço que utiliza a API.
Exoneração de responsabilidade
API para fins informativos. Não garantimos a precisão dos dados fornecidos pela API ou contidos nesta página, uma vez que devem ser utilizados apenas para efeitos informativos. Trabalhamos pela estabilidade e precisão dos dados, porém, os dados podem estar atrasados ou errados "no estado em que se encontram", confirme todos os dados antes de efetuar qualquer ação que possa ser afetada por estes valores, assim como demais endpoints da API.
Qualquer dúvida verifique nossos termos de uso ou entre em contato.