API de geolocalização IP

Início rápido

1. Crie uma conta independente em ip.uk.app e confirme o seu email.
2. Abra Chaves no painel de controlo e crie uma chave. Copie-a de imediato: só é apresentada uma vez.
3. Envie a chave a partir do seu servidor no cabeçalho Authorization.

curl 'https://ip.uk.app/api/v1/lookup?ip=1.1.1.1' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Nunca inclua a chave API num URL, código público do navegador, capturas de ecrã ou registos partilhados. Guarde-a numa variável de ambiente no seu servidor.

Endpoints

Adicione o parâmetro opcional lang para o idioma dos nomes: en, uk, es, pt, de ou fr. Se faltar uma tradução, é usado o nome em inglês.

curl 'https://ip.uk.app/api/v1/bulk?lang=uk' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"ips":["1.1.1.1","2001:4860:4860::8888"]}'

Formato da resposta

O campo data contém um objeto para lookup e me, e uma lista para bulk. Os valores indisponíveis são null. Os valores do exemplo ilustram a estrutura e não garantem uma localização real.

{
  "data": {
    "ip": "1.1.1.1",
    "version": 4,
    "country": {"code": "AU", "name": "Australia"},
    "region": "New South Wales",
    "city": "Sydney",
    "location": {"latitude": -33.8688, "longitude": 151.209, "accuracy": "approximate"},
    "asn": {"number": 13335, "organization": "Cloudflare, Inc.", "prefix_length": 24},
    "source": {"name": "DB-IP Lite", "url": "https://db-ip.com/", "license": "CC BY 4.0", "updated": "2026-10"}
  }
}

Quota gratuita e limites

• 10 000 consultas IP bem-sucedidas por conta e mês civil. A quota é renovada às 00:00 UTC do primeiro dia do mês.
• 60 consultas IP por minuto, partilhadas por todas as suas chaves.
• Até cinco chaves ativas, com validade de 30, 90 ou 365 dias.
• Cada endereço consultado com sucesso consome um crédito, incluindo repetições num lote. Um lote de 50 consome 50 créditos.
• Os dados inválidos e as consultas falhadas não consomem créditos mensais. As falhas temporárias podem contar para o limite por minuto.
• Antes do processamento, todos os dados do lote são validados e a quota disponível é verificada. Não há cobrança parcial de créditos por um lote.
• Limites de rede adicionais protegem a disponibilidade do serviço.

As respostas incluem X-Quota-Limit, X-Quota-Remaining e X-Quota-Reset. A data de renovação é uma marca temporal Unix. X-Request-ID identifica um pedido autenticado. As respostas 429 incluem Retry-After com o tempo de espera em segundos.

Os planos mensais pagos estão disponíveis no painel. As quotas seguem o período da subscrição. Sem cobranças automáticas por excesso.

Tratamento de erros

{"error":{"code":"invalid_ip","message":"Provide a public IPv4 or IPv6 address."}}

JavaScript · no servidor

const response = await fetch(
  'https://ip.uk.app/api/v1/lookup?ip=1.1.1.1',
  { headers: { Authorization: `Bearer ${process.env.IP_API_KEY}` } }
);
const result = await response.json();
if (!response.ok) throw new Error(result.error.message);
console.log(result.data);

Python

import json, os
from urllib.request import Request, urlopen
from urllib.error import HTTPError

request = Request('https://ip.uk.app/api/v1/lookup?ip=1.1.1.1',
    headers={'Authorization': 'Bearer ' + os.environ['IP_API_KEY']})
try:
    with urlopen(request, timeout=15) as response:
        print(json.load(response)['data'])
except HTTPError as error:
    print(error.code, json.load(error))

PHP

$ch = curl_init('https://ip.uk.app/api/v1/lookup?ip=1.1.1.1');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer '.getenv('IP_API_KEY')],
]);
$body = curl_exec($ch);
if ($body === false) { throw new RuntimeException(curl_error($ch)); }
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);
$result = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($status !== 200) { throw new RuntimeException($result['error']['message']); }

Qualidade dos dados e atribuição

A geolocalização é aproximada. Um IP pode corresponder a uma porta de ligação ou centro de dados, sobretudo em redes móveis, anycast, VPN e proxies. As coordenadas não indicam a localização exata de uma pessoa. A organização do ASN identifica o operador da rede e não comprova que se trate de um fornecedor de internet residencial.

Os dados provêm da base mensal DB-IP Lite com licença CC BY 4.0. Mantenha a atribuição adequada nas aplicações que utilizem estes dados. A versão v1 não classifica VPN, proxies ou fraude.

Privacidade e segurança das chaves

As chaves API completas são apresentadas uma vez e guardadas apenas como hashes com segredo do servidor. As estatísticas conservam a rota da API, estado, duração, créditos e identificador mascarado da chave durante 30 dias. Este histórico não guarda os IP consultados nem as chaves completas. Os contadores mensais agregados são conservados por 12 meses. Os registos de infraestrutura separados seguem a nossa Política de privacidade.

Revogue de imediato as chaves expostas no painel de controlo. Bloquear ou eliminar uma conta desativa as suas chaves. A sua conta é independente de outros projetos uk.app.

Política de privacidade · Condições · support@uk.app