FlowData

Como consultar até 100 endereços IP de uma vez?

Publicado em 10. novembro 2026

Se você quer localizar muitos endereços IP de uma vez, por exemplo os acessos de um dia no log do seu servidor, não precisa consultar um por um. Uma consulta em lote aceita até 100 itens em uma única chamada.

Como é a requisição

A consulta em lote é um POST para https://api.flowdata.one/v1/geolocation/batch. O corpo é diretamente um array JSON, sem objeto em volta.

curl -X POST "https://api.flowdata.one/v1/geolocation/batch?lang=pt-BR" \
  -H "Authorization: Bearer fd_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '["8.8.8.8", "1.1.1.1", "example.com"]'

Cada item é um endereço IP ou domínio em texto, ou um objeto com configurações próprias:

[
  "8.8.8.8",
  {"query": "1.1.1.1", "lang": "en"},
  {"query": "example.com", "fields": "status,country,city,query"}
]
  • query: o endereço IP ou domínio.
  • lang: o idioma apenas deste item.
  • fields: nomes de campos separados por vírgula. O resultado deste item terá somente esses campos. Inclua status se quiser verificar se a consulta deu certo.

O parâmetro lang na URL define o idioma de todos os itens que não têm um próprio. Sem ele, os nomes vêm em alemão. Os idiomas disponíveis estão em Como consultar a localização de um endereço IP ou domínio?. Diferente da consulta individual, um código de idioma desconhecido aqui não é erro; o item simplesmente recebe o idioma padrão.

A resposta

Você recebe um array JSON com um objeto por item, na mesma ordem dos seus itens. Cada objeto tem os mesmos campos de uma consulta individual. A forma mais segura de associar os resultados aos seus dados é pela posição, porque em um domínio o campo query traz o endereço IP resolvido, e não o nome do domínio.

Um item também pode ter "status": "fail" com um motivo curto em message, como private range ou invalid query. Os demais itens não são afetados, então verifique o status de cada objeto. Um item que não seja texto nem objeto com query termina da mesma forma, com invalid query e query vazio.

Os domínios precisam ser resolvidos primeiro, e um lote tem dez segundos no total para isso. Quando o tempo acaba, os domínios restantes terminam com invalid query, enquanto os endereços IP continuam sendo localizados. Se você tiver muitos domínios, envie em lotes menores.

Mensagens de erro do lote

Antes de começar a consulta, o FlowData verifica o corpo. Esses erros têm o formato {"status":"fail","message":"..."}:

HTTP message Causa
400 Empty request body O corpo está vazio.
400 Invalid JSON format O corpo não é um JSON válido, muitas vezes por falta de aspas ou vírgula.
400 Request body must be a JSON array O corpo é um objeto como {"ips": [...]} em vez de um array.
400 At least one query required O array está vazio.
422 Maximum 100 queries allowed per batch request O array tem mais de 100 itens.
503 Geolocation database unavailable A localização está indisponível no momento. Tente de novo depois de uma breve pausa.

Se você tiver mais de 100 endereços, divida em lotes de no máximo 100 e envie um depois do outro.

No Registro da área, você encontra todas as consultas em lote rejeitadas ao colocar o filtro em Com falha. O ícone de olho na linha mostra a resposta de erro exata. Saiba mais em Estatísticas e registro de chamadas de uma área do FlowData.

Quanto custa um lote?

Cada item com status: success é cobrado. Itens com fail são gratuitos, e uma consulta rejeitada não custa nada. O preço a cada 1.000 consultas bem-sucedidas é o mesmo da consulta individual e está na página de preços.

Antes de começar, o FlowData reserva o valor de todos os itens e depois cobra apenas os bem-sucedidos. Se o saldo não cobrir todos os itens, a API responde com HTTP 402, mesmo que nem todos fossem dar certo no fim.

Bom saber

  • Uma consulta em lote conta como uma requisição nas estatísticas e aparece como uma linha no registro, não importa quantos itens tenha.
  • Remova endereços duplicados antes de enviar, assim cabem mais endereços diferentes em um lote.
  • Como em todas as chamadas do FlowData, envie a requisição do seu servidor para que a chave não vá parar no navegador.

Este artigo foi útil?

Voltar para Geolocalização de IP e Client Info