FlowData

Como consultar a localização de um endereço IP ou domínio?

Publicado em 10. novembro 2026

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ão lng como no Maps.
  • timezone, offset: um fuso horário como America/Sao_Paulo e a diferença atual em relação ao UTC em segundos, então 3600 significa 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

Este artigo foi útil?

Voltar para Geolocalização de IP e Client Info