Documentație API

Autentificare

Toate cererile API trebuie să includă cheia API în antetul X-API-Key . Poți găsi cheia API în consolă.

X-API-Key: oip_your_api_key_here

URL de bază

Toate cererile API sunt făcute la următorul URL de bază prin HTTPS:

https://api.openipapi.com

Specificație care poate fi citită de mașini (OpenAPI 3.1): /openapi.yaml.

Format răspuns

Toate răspunsurile sunt JSON. Răspunsurile de succes returnează HTTP 200. Răspunsurile de eroare returnează un cod de stare 4xx sau 5xx corespunzător cu un câmp error .

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

GET /v1/lookup/{ip}

Interoghează geolocalizarea, rețeaua și datele de amenințare pentru o singură adresă IP.

Parametri

Câmpuri răspuns

Exemplu de cerere

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

Exemplu de răspuns

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

Interoghează mai multe adrese IP într-o singură cerere. Limitele de dimensiune ale lotului depind de planul tău.

Limite de dimensiune lot

Corpul cererii

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

Răspuns

Returnează un array încapsulat de obiecte complete de interogare, în aceeași ordine ca cererea.

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

Returnează geolocalizarea și datele de amenințare pentru adresa IP care face cererea. Util pentru funcționalitățile „Care este IP-ul meu?".

Răspunsul este identic cu GET /v1/lookup/{ip} cu IP-ul apelantului completat.

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

GET /v1/asn/{asn}

Recuperează informații detaliate despre un Număr de Sistem Autonom. Necesită planul Starter sau superior.

Parametrul asn acceptă formatele 13335 și AS13335 .

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

Exemplu de răspuns

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

Validează o adresă IP și determină tipul acesteia. Nu consumă cota de interogare.

Example response

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

GET /v1/fraud/{ip}

Scor de fraudă compus (0–100) cu nivel de risc și recomandare acționabilă. Combină semnale de VPN, proxy, Tor, datacenter și abuz istoric. Plan Starter sau superior

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

Niveluri de risc și recomandări

GET /v1/probe/{ip}

Date de sondare a rețelei în timp real de la cele peste 60 de noduri active de probing: porturi TCP deschise, bannere de servicii, DNS invers, detalii complete ale certificatelor TLS (subiect, emitent, SAN-uri, valabilitate) și categorii de servicii detectate. Plan Pro sau superior

Cum funcționează

• · Date recente (≤ 7 zile): returnate imediat din cache.
• · Date depășite (> 7 zile): returnate imediat și o rescanare în fundal este pusă în coadă. Răspunsul include "stale": true.
• · Niciodată sondat: o sondare este pusă în coadă pentru scanare imediată. Primele rezultate apar de obicei în 1–5 minute.
• · Cota de sondare este 10% din cota lunară de interogări. IP-urile private / rezervate nu pot fi sondate.

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

Porturile pe care le scanăm

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).

Cazuri de utilizare

• · Antifraudă — detectează ferme de boți care rulează versiuni SSH identice / amprente TLS
• · Threat intel — monitorizează servere C2 pentru modificări de banner / certificat
• · OSINT / bug bounty — enumeră rapid serviciile pe orice IP public
• · Hosting / operațiuni ISP — găsește proxy-uri deschise / ieșiri Tor în rețeaua ta

GET /v1/proxy-attribution/{ip}

Identifică dacă un IP aparține unui pool de proxy rezidențial cunoscut, VPN comercial sau interval de datacenter. Spre deosebire de semnalele generice is_proxy , acest endpoint atribuie IP-ul furnizorului specific (Bright Data, Oxylabs, NordVPN, etc.) — esențial pentru echipele de fraudă care trebuie să permită unii furnizori și să blocheze alții. Add-on Proxy Intel

Exemplu de răspuns (IP în interval 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"
}

Tipuri de rețea

• · residential — pool-uri de proxy rezidențial (Bright Data, Oxylabs, Smartproxy, IPRoyal, Hola, Honeygain, EarnApp, Peer2Profit, SOAX)
• · vpn — furnizori VPN comerciali (NordVPN, ExpressVPN, Surfshark, Mullvad, ProtonVPN, PIA, IPVanish, CyberGhost)
• · datacenter — furnizori de hosting utilizați frecvent pentru ieșire de proxy comercial (AWS, DigitalOcean, OVH, Hetzner, etc.)
• · tor — noduri de ieșire / relay Tor
• · mobile — pool-uri de proxy ale operatorilor mobili

Recomandări

GET /v1/account/usage

Returnează statistici de utilizare pentru perioada de facturare curentă a contului tău.

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

Listează bazele de date MMDB disponibile pentru planul tău. Înlocuitori drop-in MaxMind .mmdb pentru utilizare offline / de margine — funcționează cu orice cititor 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}

Transmite fișierul MMDB brut. Suportă ETag + If-None-Match pentru GET-uri condiționale (304 Not Modified când fișierul nu s-a schimbat). Limită de rată: 10 descărcări per sursă pe zi.

Surse disponibile

Exemplu: descărcare + utilizare în 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']

Semnal Sancțiuni

Fiecare răspuns /v1/lookup include două câmpuri în blocul geo care indică dacă țara IP-ului este supusă sancțiunilor internaționale.

Liste de sancțiuni acoperite: OFAC (SUA), UE, Consiliul de Securitate ONU, OFSI Regatul Unit. Țările semnalate în prezent includ Iran, Coreea de Nord, Rusia, Belarus, Siria, Cuba, Venezuela, Sudan și altele. Lista este menținută și actualizată pe măsură ce programele se schimbă.

Exemplu de țară sancționată

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

Detecție Boți

OpenIPApi efectuează verificare DNS invers dublu pentru a identifica crawlerele legitime. Rezultatul este disponibil în threat.bot_type la fiecare interogare.

Metodă de verificare: (1) căutare PTR pe IP → hostname. (2) Hostname-ul trebuie să corespundă cu modelul de domeniu al botului (ex.: *.googlebot.com). (3) DNS direct pe hostname trebuie să rezolve înapoi la IP-ul original. Rezultatele sunt stocate în cache timp de 24 de ore.

Exemplu de Googlebot verificat

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

Interogare Istorică

Adaugă un parametru ?date=YYYY-MM-DD la orice interogare de IP unic pentru a recupera instantaneul de la acea dată.

Exemplu de cerere

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

Plic de răspuns

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

Eroare: instantaneu indisponibil

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

Coduri de eroare

Limite de rată

Pe lângă cotele lunare de interogare, cererile sunt limitate ca rată per cheie API folosind o fereastră glisantă. Când este depășit, API-ul returnează HTTP 429 cu un antet Retry-After .

Limite suplimentare: /v1/validate (neautentificat) este limitat la 60 cereri/min per IP apelant; /v1/me la 30 cereri/min. Descărcările MMDB sunt limitate la 10/zi per sursă per cont. Răspunsurile cu limită de rată includ Retry-After.

Webhooks

Webhook-urile îți permit să primești notificări HTTP POST în timp real când starea unui IP pe care îl urmărești se schimbă. Configurează-le în consolă → Webhooks, sau prin interfața panoului — nu este necesară o apelare API.

Evenimente

Antetele cererii

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

Payload exemplu

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

Verificarea semnăturii

Fiecare webhook este semnat folosind HMAC-SHA256 al corpului JSON brut cu secretul tău de webhook. Semnătura este trimisă în antetul X-OpenIPApi-Signature ca sha256=<hex>. Verifică întotdeauna înainte de a acționa pe baza payload-ului:

$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)
  });

Politica de reîncercare

Endpoint-ul tău trebuie să răspundă în 10 secunde cu HTTP 2xx pentru a confirma primirea. Orice alt status (sau timeout) declanșează reîncercări cu backoff exponențial: 1 min, 5 min, 30 min, 2 h, 12 h. După ultima tentativă, webhook-ul este marcat ca eșuat și o alertă în panou este ridicată.

Istoricul livrărilor și retrimitere

consolă → Webhooks păstrează ultimele 100 de tentative de livrare per cont, afișând tipul de eveniment, codul de status HTTP și corpul de răspuns returnat de endpoint-ul tău. Poți retrimite orice livrare anterioară pentru a re-trimite payload-ul semnat original, și folosi Debuggerul de Semnătură integrat pentru a verifica semnăturile HMAC-SHA256 pe partea clientului fără a-ți împărtăși secretul cu niciun server.

Livrările retrimise includ un antet suplimentar X-OpenIPApi-Replay: 1 pentru ca endpoint-ul tău să le poată distinge de evenimentele live.

Exemple de cod — curl

Interogare unică

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

Interogare în lot

$ 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"]}'

IP-ul tău

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

Exemple de cod — JavaScript

Interogare unică (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

Interogare în lot

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);
}

Exemple de cod — Python

Interogare unică (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

Interogare în lot

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"])