Τεκμηρίωση API

Πιστοποίηση

Όλα τα αιτήματα API πρέπει να περιλαμβάνουν το κλειδί API σας στην X-API-Key κεφαλίδα αιτήματος. Μπορείτε να βρείτε το κλειδί API σας στην κονσόλα.

X-API-Key: oip_your_api_key_here

Βασικό URL

Όλα τα αιτήματα API γίνονται στο παρακάτω βασικό URL μέσω HTTPS:

https://api.openipapi.com

Μηχαναγνώσιμη προδιαγραφή (OpenAPI 3.1): /openapi.yaml.

Μορφή απόκρισης

Όλες οι αποκρίσεις είναι JSON. Επιτυχείς αποκρίσεις επιστρέφουν HTTP 200. Οι αποκρίσεις σφαλμάτων επιστρέφουν κατάλληλο κωδικό κατάστασης 4xx ή 5xx με ένα error πεδίο.

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

GET /v1/lookup/{ip}

Αναζητήστε γεωεντοπισμό, δίκτυο και δεδομένα απειλής για μία μεμονωμένη διεύθυνση IP.

Παράμετροι

Πεδία απόκρισης

Παράδειγμα αιτήματος

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

Παράδειγμα απόκρισης

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

Αναζητήστε πολλαπλές διευθύνσεις IP σε ένα μόνο αίτημα. Τα όρια μεγέθους μαζικής επεξεργασίας εξαρτώνται από το πλάνο σας.

Όρια μεγέθους μαζικής επεξεργασίας

Σώμα αιτήματος

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

Απόκριση

Επιστρέφει ένα τυλιγμένο array πλήρων αντικειμένων αναζήτησης, με την ίδια σειρά όπως στο αίτημα.

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

Επιστρέφει γεωεντοπισμό και δεδομένα απειλής για τη διεύθυνση IP που κάνει το αίτημα. Χρήσιμο για λειτουργίες «Ποια είναι η IP μου;».

Η απόκριση είναι πανομοιότυπη με GET /v1/lookup/{ip} με προσυμπληρωμένη την IP του καλούντος.

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

GET /v1/asn/{asn}

Ανακτήστε λεπτομερείς πληροφορίες για έναν Αριθμό Αυτόνομου Συστήματος. Απαιτεί πλάνο Starter ή υψηλότερο.

Η asn παράμετρος αποδέχεται τόσο 13335 όσο και AS13335 μορφές.

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

Παράδειγμα απόκρισης

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

Επαληθεύστε μια διεύθυνση IP και προσδιορίστε τον τύπο της. Δεν καταναλώνει ποσόστωση αναζητήσεων.

Example response

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

GET /v1/fraud/{ip}

Σύνθετη βαθμολογία απάτης (0–100) με επίπεδο κινδύνου και εφαρμόσιμη σύσταση. Συνδυάζει σήματα VPN, proxy, Tor, κέντρου δεδομένων και ιστορικής κατάχρησης. Πλάνο Starter ή υψηλότερο

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

Επίπεδα κινδύνου & συστάσεις

GET /v1/probe/{ip}

Δεδομένα δικτυακής ανίχνευσης σε πραγματικό χρόνο από τους 60+ ενεργούς κόμβους ανίχνευσής μας: ανοιχτές TCP θύρες, banners υπηρεσιών, reverse DNS, πλήρης λεπτομέρεια TLS πιστοποιητικού (subject, issuer, SANs, ισχύς) και ανιχνευμένες κατηγορίες υπηρεσιών. Πλάνο Pro ή υψηλότερο

Πώς λειτουργεί

• · Νέα δεδομένα (≤ 7 ημέρες παλιά): επιστρέφονται αμέσως από κεφαλίδα.
• · Παλαιά δεδομένα (> 7 ημέρες): επιστρέφονται αμέσως συν έναν background re-probe που τίθεται σε ουρά. Η απόκριση περιλαμβάνει "stale": true.
• · Ποτέ δεν έχει γίνει probe: ένα probe τίθεται σε ουρά για άμεση σάρωση. Τα πρώτα αποτελέσματα φτάνουν συνήθως εντός 1–5 λεπτών.
• · Η ποσόστωση probe είναι 10% της μηνιαίας ποσόστωσης αναζητήσεών σας. Δεν είναι δυνατή η ανίχνευση ιδιωτικών/δεσμευμένων IPs.

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

Θύρες που σαρώνουμε

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

Περιπτώσεις χρήσης

• · Anti-fraud — ανίχνευση bot farms που εκτελούν πανομοιότυπες εκδόσεις SSH / fingerprints TLS
• · Threat intel — παρακολούθηση C2 servers για αλλαγές banner/πιστοποιητικού
• · OSINT / bug bounty — γρήγορη απαρίθμηση υπηρεσιών σε οποιαδήποτε δημόσια IP
• · Hosting / ISP ops — εύρεση ανοιχτών proxy / εξόδων Tor στο δίκτυό σας

GET /v1/proxy-attribution/{ip}

Αναγνωρίζει αν μια IP ανήκει σε γνωστό pool οικιακών proxy, εμπορικό VPN ή εύρος κέντρου δεδομένων. Σε αντίθεση με γενικές is_proxy σημαίες, αυτό το endpoint αποδίδει την IP στον συγκεκριμένο πάροχο (Bright Data, Oxylabs, NordVPN, κ.λπ.) — κρίσιμο για ομάδες απάτης που πρέπει να επιτρέπουν ορισμένους παρόχους και να αποκλείουν άλλους. Add-on Proxy Intel

Παράδειγμα απόκρισης (IP σε εύρος 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"
}

Τύποι δικτύου

• · residential — pools οικιακών proxy (Bright Data, Oxylabs, Smartproxy, IPRoyal, Hola, Honeygain, EarnApp, Peer2Profit, SOAX)
• · vpn — εμπορικοί πάροχοι VPN (NordVPN, ExpressVPN, Surfshark, Mullvad, ProtonVPN, PIA, IPVanish, CyberGhost)
• · datacenter — πάροχοι hosting που χρησιμοποιούνται συχνά για εμπορική έξοδο proxy (AWS, DigitalOcean, OVH, Hetzner, κ.λπ.)
• · tor — κόμβοι εξόδου/relay Tor
• · mobile — pools proxy κινητής τηλεφωνίας

Συστάσεις

GET /v1/account/usage

Επιστρέφει στατιστικά χρήσης τρέχουσας περιόδου χρέωσης για τον λογαριασμό σας.

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

Παραθέτει βάσεις δεδομένων MMDB διαθέσιμες για το πλάνο σας. Drop-in MaxMind .mmdb αντικαταστάτες για offline/edge χρήση — λειτουργεί με οποιονδήποτε αναγνώστη 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}

Μεταδίδει ροή το αρχείο MMDB. Υποστηρίζει ETag + If-None-Match για υπό όρους GETs (304 Not Modified όταν το αρχείο είναι αναλλοίωτο). Rate limit: 10 λήψεις ανά πηγή ανά ημέρα.

Διαθέσιμες πηγές

Παράδειγμα: λήψη + χρήση σε 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']

Σημαία Κυρώσεων

Κάθε /v1/lookup απόκριση περιλαμβάνει δύο πεδία στο μπλοκ geo που υποδεικνύουν αν η χώρα της IP υπόκειται σε διεθνείς κυρώσεις.

Καλυπτόμενες λίστες κυρώσεων: OFAC (ΗΠΑ), ΕΕ, Συμβούλιο Ασφαλείας ΟΗΕ, UK OFSI. Χώρες που επισημαίνονται περιλαμβάνουν Ιράν, Βόρεια Κορέα, Ρωσία, Λευκορωσία, Συρία, Κούβα, Βενεζουέλα, Σουδάν και άλλες. Η λίστα διατηρείται και ενημερώνεται καθώς τα προγράμματα αλλάζουν.

Παράδειγμα χώρας υπό κυρώσεις

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

Ανίχνευση Bot

Το OpenIPApi εκτελεί διπλή επαλήθευση reverse DNS για αναγνώριση νόμιμων crawlers. Το αποτέλεσμα είναι διαθέσιμο στο threat.bot_type σε κάθε αναζήτηση.

Μέθοδος επαλήθευσης: (1) Αναζήτηση PTR της IP → hostname. (2) Το hostname πρέπει να αντιστοιχεί στο μοτίβο domain του bot (π.χ. *.googlebot.com). (3) Το forward DNS στο hostname πρέπει να αναλύει πίσω στην αρχική IP. Τα αποτελέσματα αποθηκεύονται στη cache για 24 ώρες.

Παράδειγμα επαληθευμένου Googlebot

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

Ιστορική Αναζήτηση

Προσθέστε μια ?date=YYYY-MM-DD παράμετρο σε οποιαδήποτε μεμονωμένη αναζήτηση IP για να ανακτήσετε το snapshot από εκείνη την ημερομηνία.

Παράδειγμα αιτήματος

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

Φάκελος απόκρισης

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

Σφάλμα: δεν υπάρχει διαθέσιμο snapshot

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

Κωδικοί σφαλμάτων

Rate limits

Επιπλέον των μηνιαίων ποσοστώσεων αναζητήσεων, τα αιτήματα περιορίζονται ανά κλειδί API χρησιμοποιώντας κυλιόμενο παράθυρο. Όταν υπερβαίνεται, το API επιστρέφει HTTP 429 με κεφαλίδα Retry-After .

Πρόσθετα όρια: /v1/validate (μη πιστοποιημένο) περιορίζεται σε 60 αιτ./λεπτό ανά IP καλούντος· /v1/me σε 30 αιτ./λεπτό. Οι λήψεις MMDB περιορίζονται σε 10/ημέρα ανά πηγή ανά λογαριασμό. Οι αποκρίσεις rate-limit περιλαμβάνουν Retry-After.

Webhooks

Τα webhooks σάς επιτρέπουν να λαμβάνετε ειδοποιήσεις HTTP POST σε πραγματικό χρόνο όταν αλλάζει η κατάσταση μιας IP που παρακολουθείτε. Διαμορφώστε τα στην κονσόλα → Webhooks, ή μέσω του dashboard UI — δεν απαιτείται κλήση API.

Συμβάντα

Κεφαλίδες αιτήματος

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

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

Επαλήθευση υπογραφής

Κάθε webhook υπογράφεται με HMAC-SHA256 του ακατέργαστου σώματος JSON με το μυστικό webhook σας. Η υπογραφή αποστέλλεται στην X-OpenIPApi-Signature κεφαλίδα ως sha256=<hex>. Πάντα να επαληθεύετε πριν ενεργήσετε βάσει του 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)
  });

Πολιτική επανάληψης

Το endpoint σας πρέπει να απαντά εντός 10 δευτερολέπτων με HTTP 2xx για να επιβεβαιώσει τη λήψη. Οποιαδήποτε άλλη κατάσταση (ή timeout) ενεργοποιεί επαναλήψεις με εκθετική καθυστέρηση: 1 λεπτό, 5 λεπτά, 30 λεπτά, 2 ώρες, 12 ώρες. Μετά την τελική απόπειρα το webhook επισημαίνεται ως αποτυχημένο και εγείρεται ειδοποίηση στο dashboard.

Ιστορικό αποστολής & replay

Η κονσόλα → Webhooks διατηρεί τις τελευταίες 100 απόπειρες αποστολής ανά λογαριασμό, εμφανίζοντας τύπο συμβάντος, κωδικό κατάστασης HTTP και το σώμα απόκρισης που επέστρεψε το endpoint σας. Μπορείτε να αναπαράγετε οποιαδήποτε προηγούμενη αποστολή για να στείλετε ξανά το πρωτότυπο υπογεγραμμένο payload, και να χρησιμοποιήσετε τον ενσωματωμένο Αποσφαλματωτή Υπογραφής για επαλήθευση υπογραφών HMAC-SHA256 στον browser χωρίς να μοιράζεστε το μυστικό σας με κανένα διακομιστή.

Οι αναπαραγόμενες αποστολές περιλαμβάνουν επιπλέον κεφαλίδα X-OpenIPApi-Replay: 1 ώστε το endpoint σας να μπορεί να τις διακρίνει από ζωντανά συμβάντα.

Παραδείγματα κώδικα — curl

Μεμονωμένη αναζήτηση

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

Μαζική αναζήτηση

$ 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 σας

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

Παραδείγματα κώδικα — JavaScript

Μεμονωμένη αναζήτηση (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

Μαζική αναζήτηση

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

Παραδείγματα κώδικα — Python

Μεμονωμένη αναζήτηση (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

Μαζική αναζήτηση

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