API-Dokumentation

Authentifizierung

Alle API-Anfragen müssen Ihren API-Schlüssel im X-API-Key Anfrage-Header enthalten. Ihren API-Schlüssel finden Sie in der Konsole.

X-API-Key: oip_your_api_key_here

Basis-URL

Alle API-Anfragen werden an folgende Basis-URL über HTTPS gesendet:

https://api.openipapi.com

Maschinenlesbare Spezifikation (OpenAPI 3.1): /openapi.yaml.

Antwortformat

Alle Antworten sind JSON. Erfolgreiche Antworten geben HTTP 200. Fehlerantworten geben einen passenden 4xx- oder 5xx-Statuscode mit einem error Feld zurück.

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

GET /v1/lookup/{ip}

Geolokalisierung, Netzwerk- und Threat-Daten für eine einzelne IP-Adresse abfragen.

Parameter

Antwortfelder

Beispielanfrage

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

Beispielantwort

{
  "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": [],
    "is_eu": true,
    "continent": { "code": "EU", "name": "Europe" },
    "currency": "EUR",
    "calling_code": "+49",
    "languages": ["de"],
    "flag": { "emoji": "🇩🇪", "url": "https://flagcdn.com/de.svg" },
    "current_time": "2026-07-26T14:32:00+02:00"
  },
  "network": {
    "asn": 205100,
    "as_name": "F3 Netze e.V.",
    "as_domain": "f3netze.de",
    "isp": "F3 Netze",
    "organization": "F3 Netze e.V.",
    "connection_type": "datacenter",
    "hostname": "tor-exit.f3netze.de"
  },
  "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"
  },
  "verification": {
    "probe_verified": true,
    "last_probed": "2026-07-15T09:14:03+00:00"
  }
}

POST /v1/lookup/batch

Mehrere IP-Adressen in einer einzigen Anfrage nachschlagen. Die Batch-Größenlimits hängen von Ihrem Plan ab.

Batch-Größenlimits

Anfrage-Body

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

Antwort

Gibt ein umschlossenes Array vollständiger Lookup-Objekte zurück, in derselben Reihenfolge wie die Anfrage.

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

Gibt Geolokalisierung und Threat-Daten für die IP-Adresse der Anfrage zurück. Nützlich für „Was ist meine IP?"-Features.

Die Antwort ist identisch mit GET /v1/lookup/{ip} mit der vorausgefüllten IP des Aufrufers.

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

GET /v1/asn/{asn}

Detaillierte Informationen zu einer Autonomous-System-Nummer abrufen. Erfordert Starter-Plan oder höher.

Der asn Parameter akzeptiert sowohl 13335 als auch AS13335 Formate.

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

Beispielantwort

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

Eine IP-Adresse validieren und ihren Typ bestimmen. Verbraucht kein Abfragekontingent.

Example response

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

GET /v1/fraud/{ip}

Zusammengesetzter Fraud Score (0–100) mit Risikolevel und Handlungsempfehlung. Kombiniert VPN-, Proxy-, Tor-, Rechenzentrum- und historische Missbrauchs-Signale. Starter-Plan oder höher

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

Risikolevel & Empfehlungen

GET /v1/probe/{ip}

Probe data is currently not configured for production collection. This endpoint remains documented for compatibility; check the public status page before relying on freshness. Pro-Plan oder höher

Funktionsweise

• · Aktuelle Daten (≤ 7 Tage alt): sofort aus dem Cache zurückgegeben.
• · Veraltete Daten (> 7 Tage): sofort zurückgegeben, plus ein Hintergrund-Re-Probe wird eingereiht. Antwort enthält "stale": true.
• · Noch nie geprobt: ein Probe wird für sofortiges Scanning eingereiht. Erste Ergebnisse kommen typischerweise innerhalb von 1–5 Minuten.
• · Probe-Kontingent beträgt 10 % Ihres monatlichen Abfragekontingents. Private/reservierte IPs können nicht geprobt werden.

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

Gescannte Ports

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

Anwendungsfälle

• · Anti-Fraud — Bot-Farmen erkennen, die identische SSH-Versionen / TLS-Fingerprints verwenden
• · Threat-Intel — C2-Server auf Banner-/Zertifikatsänderungen überwachen
• · OSINT / Bug-Bounty — Dienste auf beliebigen öffentlichen IPs schnell enumerieren
• · Hosting / ISP-Ops — offene Proxys / Tor-Exits im eigenen Netzwerk finden

GET /v1/proxy-attribution/{ip}

Identifiziert, ob eine IP zu einem bekannten Wohngebiet-Proxy-Pool, kommerziellen VPN oder Rechenzentrum-Range gehört. Im Gegensatz zu generischen is_proxy Flags ordnet dieser Endpunkt die IP dem spezifischen Provider zu (Bright Data, Oxylabs, NordVPN usw.) — entscheidend für Fraud-Teams, die bestimmte Provider erlauben und andere blockieren müssen. Proxy-Intel-Add-on

Beispielantwort (IP in VPN-Range)

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

Netzwerktypen

• · residential — Wohngebiet-Proxy-Pools (Bright Data, Oxylabs, Smartproxy, IPRoyal, Hola, Honeygain, EarnApp, Peer2Profit, SOAX)
• · vpn — Kommerzielle VPN-Provider (NordVPN, ExpressVPN, Surfshark, Mullvad, ProtonVPN, PIA, IPVanish, CyberGhost)
• · datacenter — Hosting-Provider, die häufig für kommerzielle Proxy-Exits genutzt werden (AWS, DigitalOcean, OVH, Hetzner usw.)
• · tor — Tor-Exit-/Relay-Nodes
• · mobile — Mobile-Carrier-Proxy-Pools

Empfehlungen

GET /v1/account/usage

Gibt Nutzungsstatistiken des aktuellen Abrechnungszeitraums für Ihr Konto zurück.

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

Listet MMDB-Datenbanken auf, die für Ihren Plan verfügbar sind. Drop-in-MaxMind .mmdb Ersatz für Offline-/Edge-Nutzung — funktioniert mit jedem MaxMind-DB-Reader (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}

Streamt die rohe MMDB-Datei. Unterstützt ETag + If-None-Match für bedingte GETs (304 Not Modified, wenn die Datei unverändert ist). Rate-Limit: 10 Downloads pro Quelle pro Tag.

Verfügbare Quellen

Der Data-Plan ($99/Monat) schaltet alle oben genannten Datenbanken frei — einschließlich openipapi-full — plus ein kleines API-Kontingent zum Testen. Preise →

Beispiel: Download + Verwendung 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']

Sanktions-Flag

Jede /v1/lookup Antwort enthält zwei Felder im geo Block, die angeben, ob das Land der IP internationalen Sanktionen unterliegt.

Erfasste Sanktionslisten: OFAC (USA), EU, UN-Sicherheitsrat, UK OFSI. Derzeit gekennzeichnete Länder umfassen Iran, Nordkorea, Russland, Belarus, Syrien, Kuba, Venezuela, Sudan und andere. Die Liste wird bei Programmänderungen gepflegt und aktualisiert.

Beispiel für ein sanktioniertes Land

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

Bot-Erkennung

OpenIPApi führt doppelte Reverse-DNS-Verifizierung durch, um legitime Crawler zu identifizieren. Das Ergebnis ist in threat.bot_type bei jeder Abfrage verfügbar.

Verifizierungsmethode: (1) PTR-Lookup der IP → Hostname. (2) Hostname muss dem Bot-Domainmuster entsprechen (z. B. *.googlebot.com). (3) Forward-DNS auf dem Hostname muss zur ursprünglichen IP auflösen. Ergebnisse werden 24 Stunden gecacht.

Verifiziertes Googlebot-Beispiel

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

Historische Abfrage

Fügen Sie einen ?date=YYYY-MM-DD Parameter zu einer einzelnen IP-Abfrage hinzu, um den Snapshot von diesem Datum abzurufen.

Beispielanfrage

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

Antwort-Envelope

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

Fehler: kein Snapshot verfügbar

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

Fehlercodes

Rate-Limits

Zusätzlich zu den monatlichen Abfragekontingenten werden Anfragen pro API-Schlüssel mit einem gleitenden Fenster begrenzt. Bei Überschreitung gibt die API HTTP 429 mit einem Retry-After Header zurück.

Weitere Limits: /v1/validate (nicht authentifiziert) ist auf 60 Req/Min pro Aufrufer-IP begrenzt; /v1/me auf 30 Req/Min. MMDB-Downloads sind auf 10/Tag pro Quelle pro Konto begrenzt. Rate-Limit-Antworten enthalten Retry-After.

Webhooks

Webhooks ermöglichen Ihnen, Echtzeit-HTTP-POST-Benachrichtigungen zu empfangen, wenn sich der Status einer beobachteten IP ändert. Konfigurieren Sie sie in der Konsole → Webhooks, oder über die Dashboard-UI — kein API-Aufruf erforderlich.

Ereignisse

Anfrage-Header

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

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

watchlist.threat_changed

{
  "ip": "185.220.101.45",
  "changes": [
    { "type": "threat_score", "old": 40, "new": 85 },
    { "type": "tor", "old": 0, "new": 1 }
  ],
  "checked_at": "2026-07-15T10:00:00Z"
}

Lieferformate

Jeder Webhook liefert in einem von drei Formaten. JSON (Standard) ist die oben gezeigte rohe signierte Payload. Slack und Discord senden stattdessen eine sofort veröffentlichbare Nachricht an ihre eingehende Webhook-URL — wählen Sie das Format pro Webhook in der Konsole.

{
  "text": "Watchlist alert: 185.220.101.45",
  "blocks": [ … ]
}

{
  "embeds": [
    { "title": "Watchlist alert: …",
      "color": 14431258 }
  ]
}

Signatur verifizieren

Jeder Webhook wird mit HMAC-SHA256 des rohen JSON-Bodys mit Ihrem Webhook-Secret signiert. Die Signatur wird im X-OpenIPApi-Signature Header als sha256=<hex>. gesendet. Immer vor dem Handeln auf Basis des Payloads verifizieren:

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

Wiederholungsrichtlinie

Ihr Endpunkt muss innerhalb von 10 Sekunden mit HTTP 2xx antworten, um den Empfang zu bestätigen. Jeder andere Status (oder Timeout) löst exponentielle Backoff-Wiederholungen aus: 1 Min., 5 Min., 30 Min., 2 Std., 12 Std. Nach dem letzten Versuch wird der Webhook als fehlgeschlagen markiert und ein Dashboard-Alert ausgelöst.

Lieferverlauf & Replay

Die Konsole → Webhooks speichert die letzten 100 Lieferversuche pro Konto mit Ereignistyp, HTTP-Statuscode und der von Ihrem Endpunkt zurückgegebenen Antwort. Sie können wiederholen jede frühere Lieferung, um den originalen signierten Payload erneut zu senden, und den eingebauten Signatur-Debugger verwenden, um HMAC-SHA256-Signaturen clientseitig zu verifizieren, ohne Ihr Secret mit einem Server zu teilen.

Wiederholte Lieferungen enthalten einen zusätzlichen X-OpenIPApi-Replay: 1 Header, damit Ihr Endpunkt sie von Live-Ereignissen unterscheiden kann.

Codebeispiele — curl

Einzelne Abfrage

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

Batch-Abfrage

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

Ihre IP

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

Codebeispiele — JavaScript

Einzelne Abfrage (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

Batch-Abfrage

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

Codebeispiele — Python

Einzelne Abfrage (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

Batch-Abfrage

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