Referência da API

Endpoints, formatos de resposta e erros HTTP para consultas de um único IP.

Endpoints

URL basehttps://api.ipquery.ioSem chave de API

IP de quem faz a chamada

GET/Padrão: text/plain

Retorna o endereço que faz a requisição. Um fetch no navegador identifica a conexão do navegador; um fetch no servidor identifica o servidor.

Requisição

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/?format=json"

Um único IP

GET/:ipPadrão: application/json

Coloque um IPv4 ou IPv6 no caminho. O resultado descreve esse endereço, independentemente da conexão de quem faz a chamada.

Requisição

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/1.1.1.1"

curl --fail --silent --show-error --max-time 5 \
  "https://api.ipquery.io/2606:4700:4700::1111"

Use HTTPS. Adicione ?format=json quando sua aplicação precisar de um resultado estruturado do próprio IP.

Formatos de resposta

Defina o parâmetro format da consulta para escolher a representação da resposta.

JSON: ?format=jsonapplication/json
XML: ?format=xmlapplication/xml
YAML: ?format=yamlapplication/x-yaml
Texto: ?format=texttext/plain

O formato texto retorna apenas o endereço. JSON, XML e YAML retornam o resultado estruturado da consulta.

Erros e consultas em lote

Verifique o status HTTP antes de ler um resultado bem-sucedido. O corpo dos erros segue um valor reconhecido do parâmetro format da consulta; um formato ausente ou não suportado retorna texto simples.

Endereço inválido

HTTP 404

Verifique a sintaxe do endereço. O caminho aceita apenas um IPv4 ou IPv6.

Requisição

curl -i "https://api.ipquery.io/not-an-ip?format=json"

HTTP 404

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error":"IP address not-an-ip not found"}

Formato não suportado

HTTP 400

Use json, xml, yaml ou text. CSV não é um formato de resposta da API.

Requisição

curl -i "https://api.ipquery.io/1.1.1.1?format=csv"

HTTP 400

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Invalid format

Consulta em lote desativada

HTTP 400

Use o endpoint do próprio IP para um visitante ou consulte um único endereço. Repetir a mesma requisição em lote não a habilitará.

Requisição

curl -i "https://api.ipquery.io/1.1.1.1,8.8.8.8?format=json"

HTTP 400

HTTP/1.1 400 Bad Request
Content-Type: application/json

{"error":"Bulk lookups are disabled due to abuse. For your own IP, embed fetch(\"https://api.ipquery.io/?format=json\") in your app, or use a single-IP lookup at https://api.ipquery.io/<ip>."}

Tratar uma requisição com falha

As requisições GET do navegador permitem acesso entre origens. Uma falha de rede rejeita a promessa de fetch; um erro HTTP ainda retorna uma resposta. Verifique response.ok antes de analisar o JSON.

Verificar o status HTTP

const response = await fetch(
  "https://api.ipquery.io/1.1.1.1?format=json",
  { signal: AbortSignal.timeout(5000) }
);
if (!response.ok) {
  const message = await response.text();
  throw new Error("IPQuery " + response.status + ": " + message);
}
const data = await response.json();
console.log(data.ip);

Erros de conexão e falhas do servidor

Um tempo limite excedido ou uma resposta 5xx não é um registro de IP. Mantenha um estado explícito de indisponibilidade e limite as novas tentativas. O corpo de um erro do serviço de origem pode ser texto ou HTML; não presuma que toda resposta contém JSON.

As strings ausentes na origem podem estar vazias. Um indicador false significa ausência de correspondência, não uma garantia de segurança. Ler as definições dos campos

Resposta real

1.1.1.1

Resposta real de um único IP

{
  "ip": "1.1.1.1",
  "isp": {
    "asn": "AS13335",
    "org": "Cloudflare, Inc.",
    "isp": "Cloudflare, Inc."
  },
  "location": {
    "country": "Australia",
    "country_code": "AU",
    "city": "Brisbane",
    "state": "Queensland",
    "zipcode": "",
    "latitude": -27.474848400186662,
    "longitude": 153.00996200912815,
    "timezone": "Australia/Brisbane",
    "localtime": "2026-11-03T10:24:52"
  },
  "risk": {
    "is_mobile": false,
    "is_vpn": false,
    "is_tor": false,
    "is_proxy": false,
    "is_datacenter": true,
    "risk_score": 20
  }
}