Referencia de la API

Endpoints, formatos de respuesta y errores HTTP para consultas de una sola IP.

Endpoints

URL basehttps://api.ipquery.ioSin clave de API

IP del solicitante

GET/Por defecto: text/plain

Devuelve la dirección que realiza la solicitud. Un fetch desde el navegador identifica la conexión del navegador; desde el servidor identifica al servidor.

Solicitud

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

Una sola IP

GET/:ipPor defecto: application/json

Pon una IPv4 o IPv6 en la ruta. El resultado describe esa dirección, independientemente de la conexión del solicitante.

Solicitud

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"

Usa HTTPS. Añade ?format=json cuando tu aplicación necesite un resultado estructurado de la IP del cliente.

Formatos de respuesta

Establece el valor del parámetro format de la consulta para elegir la representación de la respuesta.

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

El formato de texto devuelve solo la dirección. JSON, XML y YAML devuelven el resultado estructurado de la consulta.

Errores y consultas masivas

Comprueba el estado HTTP antes de leer un resultado correcto. El cuerpo de los errores respeta un valor admitido del parámetro format de la consulta; si el formato se omite o no se admite, se devuelve texto sin formato.

Dirección no válida

HTTP 404

Comprueba la sintaxis de la dirección. La ruta acepta una sola IPv4 o IPv6.

Solicitud

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 no admitido

HTTP 400

Usa json, xml, yaml o text. CSV no es un formato de respuesta de la API.

Solicitud

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

Consultas masivas deshabilitadas

HTTP 400

Usa el endpoint de la IP del cliente para un visitante o consulta una dirección individual. Repetir la misma solicitud masiva no la habilitará.

Solicitud

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>."}

Gestionar una solicitud fallida

Las solicitudes GET del navegador permiten acceso entre orígenes. Un fallo de red rechaza la promesa de fetch; un error HTTP sigue devolviendo una respuesta. Comprueba response.ok antes de analizar el JSON.

Comprobar el estado 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);

Errores de conexión y fallos del servidor

Un tiempo de espera agotado o una respuesta 5xx no es un registro IP. Mantén un estado explícito de indisponibilidad y limita los reintentos. El cuerpo de un error del servicio de origen puede ser texto o HTML; no des por hecho que todas las respuestas contienen JSON.

Las cadenas de origen ausentes pueden estar vacías. Un indicador false significa que no hay coincidencia, no que la dirección sea segura. Leer las definiciones de los campos

Respuesta real

1.1.1.1

Respuesta real de una consulta individual

{
  "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
  }
}