Documentazione API

Autenticazione

Tutte le richieste API devono includere la tua chiave API nell'header X-API-Key Puoi trovare la tua chiave API nella console.

X-API-Key: oip_your_api_key_here

URL base

Tutte le richieste API vengono effettuate al seguente URL base tramite HTTPS:

https://api.openipapi.com

Specifica leggibile dalla macchina (OpenAPI 3.1): /openapi.yaml.

Formato risposta

Tutte le risposte sono JSON. Le risposte di successo restituiscono HTTP 200. Le risposte di errore restituiscono un codice di stato 4xx o 5xx appropriato con un campo error .

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or has been revoked.",
  "status": 401
}

GET /v1/lookup/{ip}

Cerca geolocalizzazione, rete e dati di minaccia per un singolo indirizzo IP.

Parametri

Campi della risposta

Esempio di richiesta

$ curl https://api.openipapi.com/v1/lookup/185.220.101.45 \
     -H "X-API-Key: oip_your_api_key_here"

Esempio di risposta

{
  "ip": "185.220.101.45",
  "type": "IPv4",
  "geo": {
    "country_code": "DE",
    "country": "Germany",
    "region": "Hessen",
    "region_code": "HE",
    "city": "Frankfurt am Main",
    "postal_code": "60313",
    "latitude": 50.1109,
    "longitude": 8.6821,
    "timezone": "Europe/Berlin",
    "is_sanctioned": false,
    "sanction_lists": []
  },
  "network": {
    "asn": 205100,
    "as_name": "F3 Netze e.V.",
    "as_domain": "f3netze.de",
    "isp": "F3 Netze",
    "organization": "F3 Netze e.V.",
    "connection_type": "datacenter"
  },
  "threat": {
    "is_vpn": true,
    "is_proxy": false,
    "is_tor": true,
    "is_relay": false,
    "is_hosting": true,
    "threat_score": 85,
    "threat_categories": ["tor_exit_node", "known_abuser"],
    "bot_type": null
  },
  "abuse": {
    "contact_email": "abuse@f3netze.de"
  }
}

POST /v1/lookup/batch

Cerca più indirizzi IP in una singola richiesta. I limiti di dimensione del batch dipendono dal piano.

Limiti di dimensione del batch

Corpo della richiesta

{
  "ips": [
    "185.220.101.45",
    "8.8.8.8",
    "1.1.1.1"
  ]
}

Risposta

Restituisce un array incapsulato di oggetti di ricerca completi, nello stesso ordine della richiesta.

{
  "results": [
    { "ip": "185.220.101.45", /* full lookup object */ },
    { "ip": "8.8.8.8",          /* full lookup object */ },
    { "ip": "1.1.1.1",          /* full lookup object */ }
  ],
  "count": 3
}

GET /v1/me

Restituisce geolocalizzazione e dati di minaccia per l'indirizzo IP che effettua la richiesta. Utile per le funzionalità "Qual è il mio IP?".

La risposta è identica a GET /v1/lookup/{ip} con l'IP del chiamante pre-compilato.

$ curl https://api.openipapi.com/v1/me \
     -H "X-API-Key: oip_your_api_key_here"

GET /v1/asn/{asn}

Recupera informazioni dettagliate su un Autonomous System Number. Richiede il piano Starter o superiore.

Il asn parametro accetta sia 13335 che AS13335 formati.

$ curl https://api.openipapi.com/v1/asn/13335 \
     -H "X-API-Key: oip_your_api_key_here"

Esempio di risposta

{
  "asn": 13335,
  "as_name": "Cloudflare, Inc.",
  "as_domain": "cloudflare.com",
  "organization": "Cloudflare, Inc.",
  "country_code": "US",
  "ip_ranges_count": 1284,
  "total_ips": 2359296
}

GET /v1/validate/{ip}

Valida un indirizzo IP e determina il suo tipo. Non consuma quota di ricerca.

Example response

{
  "ip": "185.220.101.45",
  "valid": true,
  "type": "IPv4",
  "private": false,
  "bogon": false
}

GET /v1/fraud/{ip}

Fraud score composito (0–100) con livello di rischio e raccomandazione operativa. Combina segnali VPN, proxy, Tor, datacenter e abusi storici. Piano Starter o superiore

Example response

{
  "ip": "185.220.101.45",
  "fraud_score": 92,
  "risk_level": "critical",
  "signals": {
    "is_vpn": true,
    "is_proxy": false,
    "is_tor": true,
    "is_datacenter": true,
    "is_known_attacker": true,
    "high_risk_country": false
  },
  "recommendation": "block"
}

Livelli di rischio e raccomandazioni

GET /v1/probe/{ip}

Dati di probe di rete in tempo reale dai nostri 60+ nodi di probing attivo: porte TCP aperte, banner di servizio, reverse DNS, dettaglio completo del certificato TLS (soggetto, emittente, SAN, validità) e categorie di servizio rilevate. Piano Pro o superiore

Come funziona

• · Dati freschi (≤ 7 giorni): restituiti immediatamente dalla cache.
• · Dati obsoleti (> 7 giorni): restituiti immediatamente più un re-probe in background viene accodato. La risposta include "stale": true.
• · Mai sondato: un probe viene accodato per la scansione immediata. I primi risultati arrivano tipicamente entro 1–5 minuti.
• · La quota probe è il 10% della quota di ricerca mensile. Gli IP privati / riservati non possono essere sondati.

Example response

{
  "ip": "185.220.101.45",
  "reachable": true,
  "last_probed": "2026-04-18T14:23:11+00:00",
  "age_hours": 2.3,
  "stale": false,
  "refresh_queued": false,
  "probe_count_24h": 14,
  "probed_from_nodes": 8,
  "open_ports": [
    { "port": 22,   "service": "ssh",       "banner": "SSH-2.0-OpenSSH_8.9p1" },
    { "port": 80,   "service": "http",      "banner": "nginx/1.24.0" },
    { "port": 443,  "service": "https",     "banner": null },
    { "port": 9001, "service": "tor-relay", "banner": null }
  ],
  "reverse_dns": "tor-exit.f3netze.de",
  "tls": {
    "subject_cn":  "*.f3netze.de",
    "issuer":      "Let's Encrypt",
    "valid_from":  "2026-02-10T00:00:00Z",
    "valid_to":    "2026-05-10T00:00:00Z",
    "sans":        ["f3netze.de", "*.f3netze.de"],
    "fingerprint": "7e:4f:...:b2:e1"
  },
  "banners": {
    "22": "SSH-2.0-OpenSSH_8.9p1",
    "80": "nginx/1.24.0"
  },
  "detected_services": {
    "is_tor_relay":  true,
    "is_ssh_open":   true,
    "is_web_server": true,
    "is_vpn":        false,
    "is_proxy":      false
  }
}

Porte che scansionamo

22 (ssh), 80 / 8080 (http), 443 / 8443 (https), 1080 (socks5), 3128 / 8888 (http-proxy), 9001 / 9030 (tor-relay / tor-dir), 9050 / 9150 (tor-socks), 1194 (openvpn), 4500 (ipsec-nat-t), 51820 (wireguard).

Casi d'uso

• · Anti-frode — rileva bot farm con versioni SSH / fingerprint TLS identici
• · Threat intel — monitora server C2 per cambiamenti di banner / certificato
• · OSINT / bug bounty — enumera rapidamente i servizi su qualsiasi IP pubblico
• · Hosting / ISP ops — trova proxy aperti / nodi Tor nella tua rete

GET /v1/proxy-attribution/{ip}

Identifica se un IP appartiene a un pool di proxy residenziali noto, a una VPN commerciale o a un range datacenter. A differenza dei generici flag is_proxy questo endpoint attribuisce l'IP al provider specifico (Bright Data, Oxylabs, NordVPN, ecc.) — fondamentale per i team antifrode che devono consentire alcuni provider e bloccare altri. Add-on Proxy Intel

Esempio di risposta (IP in range VPN)

{
  "ip": "2.56.16.42",
  "detected": true,
  "primary_provider": {
    "provider":     "unknown_vpn",
    "display_name": "Unknown VPN",
    "network_type": "vpn",
    "confidence":   0.75
  },
  "networks": [
    {
      "provider":    "unknown_vpn",
      "network_type": "vpn",
      "confidence":   0.75,
      "source":       "x4bnet-vpn",
      "cidr":         "2.56.16.0/22"
    },
    {
      "provider":    "unknown_datacenter",
      "network_type": "datacenter",
      "confidence":   0.75,
      "source":       "x4bnet-datacenter"
    }
  ],
  "recommendation": "treat_as_vpn"
}

Tipi di rete

• · residential — pool di proxy residenziali (Bright Data, Oxylabs, Smartproxy, IPRoyal, Hola, Honeygain, EarnApp, Peer2Profit, SOAX)
• · vpn — provider VPN commerciali (NordVPN, ExpressVPN, Surfshark, Mullvad, ProtonVPN, PIA, IPVanish, CyberGhost)
• · datacenter — provider di hosting frequentemente usati per uscita proxy commerciale (AWS, DigitalOcean, OVH, Hetzner, ecc.)
• · tor — nodi di uscita / relay Tor
• · mobile — pool di proxy degli operatori mobile

Raccomandazioni

GET /v1/account/usage

Restituisce le statistiche di utilizzo del periodo di fatturazione corrente per il tuo account.

Example response

{
  "plan": "Pro",
  "period_start": "2026-03-01",
  "period_end": "2026-03-31",
  "lookups_used": 184320,
  "lookups_limit": 500000,
  "lookups_remaining": 315680,
  "reset_at": "2026-04-01T00:00:00Z"
}

GET /v1/database/list

Elenca i database MMDB disponibili per il tuo piano. Sostituti drop-in MaxMind .mmdb per uso offline / edge — funziona con qualsiasi lettore MaxMind DB (PHP, Go, Python, Node.js, Rust, Java).

Example response

{
  "plan": "Business",
  "sources": [
    {
      "source": "country",
      "filename": "geo-whois-asn-country.mmdb",
      "size_bytes": 8225621,
      "updated_at": "2026-04-18T02:00:00+00:00",
      "etag": "\"fa2b851f9155838b\"",
      "download_url": "https://api.openipapi.com/v1/database/download/country"
    }
  ]
}

GET /v1/database/download/{source}

Trasmette il file MMDB grezzo. Supporta ETag + If-None-Match per GET condizionali (304 Not Modified quando il file è invariato). Limite: 10 download per fonte al giorno.

Fonti disponibili

Esempio: download e utilizzo in PHP

# Download latest MMDB
$ curl -H "X-API-Key: YOUR_KEY" \
    -o asn.mmdb \
    https://api.openipapi.com/v1/database/download/asn

# Use with maxmind-db/reader
$ composer require maxmind-db/reader

<?php
use MaxMind\Db\Reader;
$reader = new Reader('asn.mmdb');
$record = $reader->get('8.8.8.8');
// ['autonomous_system_number' => 15169,
//  'autonomous_system_organization' => 'Google LLC']

Flag sanzioni

Ogni /v1/lookup risposta include due campi nel blocco geo che indicano se il paese dell'IP è soggetto a sanzioni internazionali.

Liste di sanzioni coperte: OFAC (USA), UE, Consiglio di Sicurezza ONU, UK OFSI. I paesi attualmente contrassegnati includono Iran, Corea del Nord, Russia, Bielorussia, Siria, Cuba, Venezuela, Sudan e altri. La lista è mantenuta e aggiornata al variare dei programmi.

Esempio di paese sanzionato

"geo": {
  "country_code": "IR",
  "country": "Iran",
  ...
  "is_sanctioned": true,
  "sanction_lists": ["OFAC", "EU", "UN"]
}

Rilevamento bot

OpenIPApi esegue verifica DNS inverso doppio per identificare i crawler legittimi. Il risultato è disponibile in threat.bot_type per ogni ricerca.

Metodo di verifica: (1) lookup PTR sull'IP → hostname. (2) L'hostname deve corrispondere al pattern di dominio del bot (es. *.googlebot.com). (3) Il DNS forward sull'hostname deve risolvere all'IP originale. I risultati sono in cache per 24 ore.

Esempio di Googlebot verificato

"threat": {
  "is_vpn": false,
  "is_proxy": false,
  "is_tor": false,
  "threat_score": 0,
  "bot_type": "googlebot"
}

Ricerca storica

Aggiungi un parametro ?date=YYYY-MM-DD a qualsiasi ricerca IP singola per recuperare lo snapshot di quella data.

Esempio di richiesta

$ curl "https://api.openipapi.com/v1/lookup/185.220.101.45?date=2026-01-15" \
     -H "X-API-Key: oip_your_api_key_here"

Envelope della risposta

{
  "ip": "185.220.101.45",
  "snapshot_date": "2026-01-15",
  "is_historical": true,
  "data": {
    /* standard lookup response */
  }
}

Errore: nessuno snapshot disponibile

{
  "error": "No historical snapshot available for this IP on 2026-01-15",
  "code": "no_snapshot"
}

Codici di errore

Limiti di frequenza

Oltre alle quote mensili di ricerca, le richieste sono limitate per chiave API con una finestra scorrevole. Quando superato, l'API restituisce HTTP 429 con un header Retry-After .

Limiti aggiuntivi: /v1/validate (non autenticato) ha un limite di 60 req/min per IP chiamante; /v1/me a 30 req/min. I download MMDB sono limitati a 10/giorno per fonte per account. Le risposte al limite di frequenza includono Retry-After.

Webhook

I webhook ti consentono di ricevere notifiche HTTP POST in tempo reale quando lo stato di un IP che stai monitorando cambia. Configurali nella console → Webhook, o tramite la dashboard — nessuna chiamata API richiesta.

Eventi

Header della richiesta

POST https://your-endpoint.example.com/webhook
Content-Type: application/json
User-Agent: OpenIPApi-Webhook/1.0
X-OpenIPApi-Event: high_threat
X-OpenIPApi-Signature: sha256=8c7f1a...b2e

Esempio di payload

{
  "event": "high_threat",
  "delivered_at": "2026-04-18T12:34:56Z",
  "webhook_id": 142,
  "data": {
    "ip": "185.220.101.45",
    "threat_score": 92,
    "previous_score": 45,
    "is_tor": true,
    "is_vpn": true
  }
}

Verifica della firma

Ogni webhook è firmato tramite HMAC-SHA256 del corpo JSON grezzo con il tuo segreto webhook. La firma viene inviata nell'header X-OpenIPApi-Signature come sha256=<hex>. Verifica sempre prima di agire sul payload:

$body = file_get_contents('php://input');
$hdr  = $_SERVER['HTTP_X_OPENIPAPI_SIGNATURE'] ?? '';
$expected = 'sha256=' . hash_hmac(
    'sha256', $body, $webhookSecret
);
if (!hash_equals($expected, $hdr)) {
    http_response_code(401);
    exit;
}
// Safe to process $body now

const crypto = require('crypto');

app.post('/webhook',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const hdr = req.headers['x-openipapi-signature'];
    const expected = 'sha256=' + crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(req.body).digest('hex');
    if (expected !== hdr) return res.status(401).end();
    // Process JSON.parse(req.body)
  });

Policy di retry

Il tuo endpoint deve rispondere entro 10 secondi con HTTP 2xx per confermare la ricezione. Qualsiasi altro stato (o timeout) attiva retry con back-off esponenziale: 1 min, 5 min, 30 min, 2 h, 12 h. Dopo l'ultimo tentativo il webhook viene contrassegnato come fallito e viene generato un alert nella dashboard.

Cronologia delle consegne e replay

La console → Webhook conserva gli ultimi 100 tentativi di consegna per account, mostrando il tipo di evento, il codice di stato HTTP e il corpo della risposta restituito dal tuo endpoint. Puoi ripetere qualsiasi consegna precedente per reinviare il payload firmato originale, e usare il Debugger di firma per verificare le firme HMAC-SHA256 lato client senza condividere il tuo segreto con nessun server.

Le consegne ripetute includono un header aggiuntivo X-OpenIPApi-Replay: 1 affinché il tuo endpoint possa distinguerle dagli eventi live.

Esempi di codice — curl

Ricerca singola

$ curl https://api.openipapi.com/v1/lookup/8.8.8.8 \
     -H "X-API-Key: oip_your_api_key_here"

Ricerca batch

$ curl -X POST https://api.openipapi.com/v1/lookup/batch \
     -H "X-API-Key: oip_your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{"ips": ["8.8.8.8", "1.1.1.1", "185.220.101.45"]}'

Il tuo IP

$ curl https://api.openipapi.com/v1/me \
     -H "X-API-Key: oip_your_api_key_here"

Esempi di codice — JavaScript

Ricerca singola (fetch)

const response = await fetch('https://api.openipapi.com/v1/lookup/8.8.8.8', {
  headers: {
    'X-API-Key': 'oip_your_api_key_here'
  }
});

const data = await response.json();
console.log(data.geo.country);       // "United States"
console.log(data.threat.is_vpn);     // false
console.log(data.threat.threat_score); // 0

Ricerca batch

const response = await fetch('https://api.openipapi.com/v1/lookup/batch', {
  method: 'POST',
  headers: {
    'X-API-Key': 'oip_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    ips: ['8.8.8.8', '1.1.1.1', '185.220.101.45']
  })
});

const { results } = await response.json();
for (const info of results) {
  console.log(info.ip, info.geo.city, info.threat.threat_score);
}

Esempi di codice — Python

Ricerca singola (requests)

import requests

API_KEY = "oip_your_api_key_here"
headers = {"X-API-Key": API_KEY}

r = requests.get(
    "https://api.openipapi.com/v1/lookup/8.8.8.8",
    headers=headers
)
r.raise_for_status()
data = r.json()

print(data["geo"]["country"])       # United States
print(data["threat"]["is_vpn"])     # False
print(data["threat"]["threat_score"]) # 0

Ricerca batch

import requests

API_KEY = "oip_your_api_key_here"
headers = {
    "X-API-Key": API_KEY,
    "Content-Type": "application/json"
}

payload = {
    "ips": ["8.8.8.8", "1.1.1.1", "185.220.101.45"]
}

r = requests.post(
    "https://api.openipapi.com/v1/lookup/batch",
    json=payload,
    headers=headers
)
r.raise_for_status()

for info in r.json()["results"]:
    print(info["ip"], info["geo"]["city"], info["threat"]["threat_score"])