1. HG Console
  2. HG IP Location
  3. Documentação

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.

Criar nova chave

Todas as requisições em como base o seguinte endpoint:

https://api.hgbrasil.com/geoip

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 consultado
  • type - ipv4 ou ipv6
  • city - cidade
  • region - região/estado
  • country_name - nome do país
  • continent - continente do IP no idioma selecionado
  • continent_code - código do continente
  • region_code - código da região/estado
  • isp - provedor de internet (necessita do plano Professional ou acima, somente requisição precision)
  • country - objeto com os dados do país
    • name - nome do país
    • code - código do país
    • capital - capital do país
    • flag - objeto com a bandeira do país
      • name - nome da moeda
      • buy - valor para compra
    • calling_code - DDI do país
  • latitude - latitude da cidade
  • longitude - longitude da cidade
  • woeid - código da cidade para consulta no HG Weather

Você pode personalizar o resultado da consulta omitindo alguns dados veja como.

Exemplo de resposta JSON
{"by":"address_standard","valid_key":true,"results":{"address":"66.249.83.93","type":"ipv4","city":"New York","region":"New York","country_name":"United States","continent":"América do Norte","continent_code":"NA","region_code":"NY","country":{"name":"United States","code":"US","capital":null,"flag":{"svg":"https://assets.hgbrasil.com/geoip/flags/svg/us.svg","png_16":"https://assets.hgbrasil.com/geoip/flags/16/us.png"},"calling_code":null},"latitude":40.763,"longitude":-73.9926,"woeid":null},"execution_time":0.0,"from_cache":false}

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.

https://api.hgbrasil.com/geoip?key=SUA-CHAVE

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 exemplo 000.000.000.000 ou envie remote para o sistema obter o IP com base no cliente.
  • precision - boolean, padrão false, envie true para obter os dados de alta precisão
https://api.hgbrasil.com/geoip?key=SUA-CHAVE&address=remote&precision=false

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 conhecer
Chamada para API

Formatos de retorno

Você pode escolher o formato de resposta da API através do parâmetro format na sua requisição.

https://api.hgbrasil.com/geoip?format=json-cors&key=SUA-CHAVE
Formatos disponíveis
  • json - retorno em JSON, padrão
  • json-cors - retorno em JSON com headers CORS, chave exposta requerida
  • php-serialize - serialização do PHP (antigo formato da API)
  • debug - JSON visual para humanos, apenas para testes, não utilizar em produção

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.

https://api.hgbrasil.com/geoip?fields=only_results,city,region,country_name,continent&key=SUA-CHAVE&address=remote

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írgula
    • only_results - remove os dados de status, cache e chave, enviando apenas os resultados
    • nome-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.

Exemplo de resposta
{"city":"New York","region":"New York","country_name":"United States","continent":"América do Norte"}

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.