Riferimento dell’API

Endpoint, formati di risposta ed errori HTTP per ricerche su un singolo IP.

Endpoint

URL di basehttps://api.ipquery.ioSenza chiave API

IP del chiamante

GET/Predefinito: text/plain

Restituisce l’indirizzo che effettua la richiesta. Un fetch dal browser identifica la connessione del browser; un fetch lato server identifica quella del server.

Richiesta

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

Un singolo IP

GET/:ipPredefinito: application/json

Inserisci un indirizzo IPv4 o IPv6 nel percorso. Il risultato descrive quell’indirizzo, indipendentemente dalla connessione del chiamante.

Richiesta

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. Aggiungi ?format=json quando l’applicazione richiede un risultato strutturato per il proprio IP.

Formati di risposta

Imposta il parametro format della query per scegliere la rappresentazione della risposta.

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

Il testo restituisce solo l’indirizzo. JSON, XML e YAML restituiscono il risultato strutturato della ricerca.

Errori e ricerche multiple

Verifica lo stato HTTP prima di leggere un risultato valido. Il corpo degli errori segue un valore riconosciuto del parametro format della query; se il formato è omesso o non supportato, viene restituito testo semplice.

Indirizzo non valido

HTTP 404

Verifica la sintassi dell’indirizzo. Il percorso accetta un solo indirizzo IPv4 o IPv6.

Richiesta

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 non supportato

HTTP 400

Usa json, xml, yaml o text. CSV non è un formato di risposta dell’API.

Richiesta

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

Ricerca multipla disabilitata

HTTP 400

Per un visitatore usa l’endpoint del proprio IP oppure cerca un singolo indirizzo. Ripetere la stessa richiesta multipla non la abiliterà.

Richiesta

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

Gestisci una richiesta non riuscita

Le richieste GET dal browser consentono l’accesso tra origini diverse. Un errore di rete rifiuta la Promise restituita da fetch; un errore HTTP restituisce comunque una risposta. Verifica response.ok prima di analizzare il JSON.

Verifica lo stato 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);

Errori di connessione e del server

Un timeout o una risposta 5xx non è un record IP. Mantieni uno stato esplicito di indisponibilità e limita i tentativi. Il corpo di un errore del servizio a monte può essere testo o HTML, quindi non presumere che ogni risposta contenga JSON.

Le stringhe assenti nei dati di origine possono essere vuote. Un indicatore false segnala una mancata corrispondenza, non un giudizio di sicurezza. Leggi le definizioni dei campi

Risposta reale

1.1.1.1

Risposta reale per un singolo 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-02T23:07:35"
  },
  "risk": {
    "is_mobile": false,
    "is_vpn": false,
    "is_tor": false,
    "is_proxy": false,
    "is_datacenter": true,
    "risk_score": 20
  }
}