Todo listo para conectar.

Primeros pasos

1. Crea tu cuenta y verifica tu correo electrónico.
2. Genera una clave en tu panel. Se muestra completa una sola vez.
3. Envía la clave en la cabecera de cada petición.

curl 'https://iplumo.com/api/v1/lookup?ip=8.8.8.8' \
  -H 'Authorization: Bearer YOUR_API_KEY'

URL base: https://iplumo.com/api/v1. Todas las fechas de consumo del panel utilizan UTC.

Autenticación

Authorization: Bearer YOUR_API_KEY

La clave es obligatoria en Free, Pro y Business. Guárdala como variable de entorno en tu servidor. No se admiten claves en la URL. Una clave revocada deja de autorizar nuevas peticiones.

La prueba pública de la página de inicio permite consultas individuales sin cuenta y comparte el límite gratuito de la IP de origen. No sustituye a los endpoints autenticados.

Consultar una IP o dominio

ip es obligatorio. Acepta una IP pública o un dominio sin protocolo ni ruta. Para un dominio se consulta una de sus direcciones públicas; no todas sus direcciones ni su contenido web.

curl 'https://iplumo.com/api/v1/lookup?ip=example.com&fields=countryCode,city,as,security' -H 'Authorization: Bearer YOUR_API_KEY'

{
  "status": "success",
  "query": "8.8.8.8",
  "country": "Estados Unidos",
  "countryCode": "US",
  "as": "AS15169 GOOGLE",
  "asname": "GOOGLE"
}

Los campos sin información se devuelven como null. Los datos pueden cambiar y no constituyen una ubicación exacta.

Hasta 100 IP en un lote

curl -X POST 'https://iplumo.com/api/v1/batch' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '["8.8.8.8", "1.1.1.1", "2606:4700:4700::1111"]'

El cuerpo debe ser un array de entre 1 y 100 IP. También admite objetos con opciones por elemento:

[
  "8.8.8.8",
  {
    "query": "1.1.1.1",
    "fields": "country,as",
    "lang": "en"
  }
]

Los resultados mantienen el orden de entrada. Los lotes aceptan IP, no dominios. Una IP inválida o privada produce un resultado con status: "fail", sin impedir las demás consultas. Un lote con formato incorrecto o más de 100 elementos devuelve HTTP 422.

[
  {
    "status": "success",
    "query": "8.8.8.8",
    "country": "Estados Unidos"
  },
  {
    "status": "fail",
    "query": "192.168.1.1",
    "message": "La IP pertenece a un rango privado o reservado."
  }
]

Campos e idiomas

Usa ?fields=country,city,as&lang=es para reducir la respuesta. Idiomas disponibles: es y en; el predeterminado es inglés. Las opciones de cada elemento del lote tienen prioridad sobre las de la URL.

status y query siempre se incluyen. En las respuestas con datos también se conservan source, dataUpdatedAt, fetchedAt y attribution, incluso al seleccionar campos. En los errores se conserva también message.

La base de datos de IPLumo utiliza registros almacenados y actualizaciones periódicas, sin mezclar ubicaciones en una respuesta. Los resultados caducados se actualizan mediante una cola. Consulta fuentes y frecuencia. Esta API no incluye detección del DNS del visitante.

Límites y reintentos

Sin cuota mensual. Ventana móvil de 60 segundos. Las claves comparten el límite de la cuenta; también se aplica por clave e IP de origen dentro del plan. Un lote de N IP consume una petición, un turno batch y N IP. Los rechazos 429 no consumen capacidad adicional. Las peticiones admitidas pueden consumir capacidad aunque la consulta posterior falle.

El panel combina consumo histórico de consultas completadas con métricas nuevas por minuto y clave, incluyendo errores y rechazos 429 después de autenticar la clave. No vincula intentos sin clave válida a un usuario. Las métricas por minuto son aproximadas; usa las cabeceras de la API para el margen exacto de la ventana móvil.

Errores predecibles

Ejemplo en JavaScript

// Run this code on your server, never in the browser.
const response = await fetch(
  'https://iplumo.com/api/v1/batch?lang=es',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.IP_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(['8.8.8.8', '1.1.1.1']),
  }
);

if (!response.ok) {
  const error = await response.json();
  throw new Error(error.message);
}
const results = await response.json();

Python

import os
import requests

r = requests.get(
    "https://iplumo.com/api/v1/lookup",
    params={"ip": "8.8.8.8", "fields": "countryCode,city,as,security"},
    headers={"Authorization": "Bearer " + os.environ["IP_API_KEY"]},
    timeout=15,
)
r.raise_for_status()
print(r.json())

PHP

<?php
$ch = curl_init('https://iplumo.com/api/v1/batch');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 15,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('IP_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['8.8.8.8', '1.1.1.1']),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($body === false || $status !== 200) {
    throw new RuntimeException('IPLumo request failed: ' . $status);
}
print_r(json_decode($body, true, 512, JSON_THROW_ON_ERROR));
curl_close($ch);

Seguridad de las claves

Guarda las claves en el servidor. Puedes renombrarlas, regenerarlas, revocarlas y limitar sus permisos en tu panel. Todas las claves admiten hasta 30 IP o rangos CIDR de origen; Business añade orígenes web exactos (por ejemplo https://example.com). Una lista vacía no restringe. IPLumo obtiene la IP de la cabecera sobrescrita por su proxy de confianza y rechaza la petición antes de ejecutar la consulta si no coincide. Si defines orígenes, una petición sin Origin se rechaza. Origin puede falsificarse fuera de un navegador y no sustituye a la autenticación; esta opción no habilita CORS.

Para respuestas 429, espera el tiempo indicado en Retry-After. Ante errores 503, utiliza reintentos limitados con espera progresiva.