Com o IP Geolocation você descobre aproximadamente onde um endereço IP ou domínio está localizado: país, região, cidade, coordenadas, fuso horário e a operadora de rede por trás dele. Os usos mais comuns são pré-selecionar país e idioma em um formulário ou ter uma ideia aproximada da origem dos pedidos.
Em todos os exemplos, substitua fd_SUA_CHAVE pela sua própria chave do FlowData. Veja como obter uma em Criar uma chave de API do FlowData.
Consultar um endereço IP ou domínio
Coloque o endereço IP ou o domínio no final do caminho. IPv4, IPv6 e nomes de domínio funcionam da mesma forma.
curl "https://api.flowdata.one/v1/geolocation/8.8.8.8?lang=pt-BR" \
-H "Authorization: Bearer fd_SUA_CHAVE"
A resposta tem este formato:
{
"status": "success",
"continent": "América do Norte",
"continentCode": "NA",
"country": "Estados Unidos",
"countryCode": "US",
"region": "CA",
"regionName": "Califórnia",
"city": "Mountain View",
"district": null,
"zip": "94043",
"lat": 37.4192,
"lon": -122.0574,
"timezone": "America/Los_Angeles",
"offset": -25200,
"currency": "USD",
"isp": "Google LLC",
"org": "Google LLC",
"as": "AS15169 Google LLC",
"asname": "Google LLC",
"reverse": null,
"mobile": null,
"proxy": null,
"hosting": null,
"query": "8.8.8.8"
}
Sem IP no caminho, ou seja, com GET https://api.flowdata.one/v1/geolocation, você recebe os dados do endereço IP de onde sua requisição vem. O artigo Por que o IP Geolocation mostra o local do meu servidor e não o do meu visitante? explica por que isso raramente é o que você quer em chamadas feitas pelo servidor.
Depois, cada consulta aparece no painel em Áreas › IP Geolocation, com indicadores, os últimos 30 dias e o Registro das requisições individuais. Veja como ler em Estatísticas e registro de chamadas de uma área do FlowData.
Os campos em resumo
- continent, continentCode: o continente por nome e por código.
- country, countryCode: o país por nome e pelo código ISO de duas letras, por exemplo
BR. - region, regionName: código e nome do estado ou da região.
- city, zip: cidade e código postal. Os dois podem vir vazios se apenas o país for conhecido.
- lat, lon: latitude e longitude. Atenção: aqui a longitude se chama
lon, nãolngcomo no Maps. - timezone, offset: um fuso horário como
America/Sao_Pauloe a diferença atual em relação ao UTC em segundos, então3600significa uma hora. - currency: a moeda do país em código ISO, por exemplo
BRL. - isp, org, asname: o nome da operadora de rede. Os três têm o mesmo valor.
- as: número da rede com o nome, por exemplo
AS15169 Google LLC. - query: o endereço IP consultado. Se você consultou um domínio, aqui vem o endereço IP para o qual ele foi resolvido.
Os campos district, reverse, mobile, proxy e hosting continuam na resposta para não quebrar integrações existentes, mas são sempre null. Não baseie nenhuma lógica neles.
Idioma dos nomes
Os nomes de continentes, países, regiões e cidades vêm em alemão por padrão. Use o parâmetro lang para escolher outro idioma: de, en, es, pt-BR, fr, ja, zh-CN ou ru. Se um nome não existir no idioma escolhido, ele vem em inglês.
Use a grafia exata. Qualquer outro valor é rejeitado com HTTP 400:
{"status":"fail","message":"Invalid parameters: ..."}
O texto depois dos dois-pontos está em alemão no momento.
Quando algo dá errado
Se um endereço não puder ser localizado, a API ainda responde com HTTP 200, então verifique sempre o campo status. Com fail, message traz o motivo e os campos de localização não aparecem:
{"status":"fail","message":"private range","query":"192.168.1.20"}
| HTTP | status e message |
Significado |
|---|---|---|
| 200 | fail, invalid query |
Nem um endereço IP válido, nem um domínio que possa ser resolvido. |
| 200 | fail, private range |
Endereço privado de uma rede local. |
| 200 | fail, reserved range |
Endereço reservado, por exemplo 127.0.0.1. |
| 200 | fail, not found |
O endereço não consta nos dados de localização. |
| 400 | fail, Invalid parameters: ... |
O valor de lang é inválido. |
| 500 | fail, Internal server error |
Erro inesperado. Tente de novo depois de uma breve pausa. |
| 503 | fail, Geolocation database unavailable |
A localização está indisponível no momento. Tente de novo depois de uma breve pausa. |
Os erros relacionados a chaves e saldo estão em Erros e limites de requisições.
Quanto custa uma consulta?
O IP Geolocation é cobrado a cada 1.000 consultas bem-sucedidas. Só contam as respostas com status: success; fail e todos os erros são gratuitos. Os valores estão na página de preços, e os preços válidos para sua equipe ficam no painel, em Cobrança. Se o saldo não for suficiente, a API responde com HTTP 402. Saiba mais em Entender os preços do FlowData.
Bom saber
- A localização por IP é sempre uma estimativa. Em redes móveis e VPNs, o local mostrado costuma estar longe do real.
- Para consultar muitos endereços de uma vez, veja Como consultar até 100 endereços IP de uma vez?.
- A referência completa está na documentação da API.