API Belgeleri

Kimlik Doğrulama

Tüm API istekleri, API anahtarınızı X-API-Key istek başlığına eklemelidir. API anahtarınızı konsolda.

X-API-Key: oip_your_api_key_here

Temel URL

Tüm API istekleri aşağıdaki temel URL'ye HTTPS üzerinden yapılır:

https://api.openipapi.com

Makine tarafından okunabilir spesifikasyon (OpenAPI 3.1): /openapi.yaml.

Yanıt formatı

Tüm yanıtlar JSON formatındadır. Başarılı yanıtlar HTTP 200. Hata yanıtları uygun bir 4xx veya 5xx durum kodu ve bir error alanı döndürür.

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

GET /v1/lookup/{ip}

Tek bir IP adresi için coğrafi konum, ağ ve tehdit verilerini sorgulayın.

Parametreler

Yanıt alanları

Örnek istek

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

Örnek yanıt

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

Tek bir istekte birden fazla IP adresini sorgulayın. Toplu boyut sınırları planınıza bağlıdır.

Toplu boyut sınırları

İstek gövdesi

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

Yanıt

İstekle aynı sırada tam sorgu nesnelerinden oluşan sarmalanmış bir dizi döndürür.

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

İsteği yapan IP adresinin coğrafi konumunu ve tehdit verilerini döndürür. "IP adresim nedir?" özellikleri için kullanışlıdır.

Yanıt, GET /v1/lookup/{ip} ile aynıdır; arayanın IP'si önceden doldurulmuştur.

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

GET /v1/asn/{asn}

Özerk Sistem Numarası hakkında ayrıntılı bilgi alın. Starter plan veya üstünü gerektirir.

asn parametresi hem 13335 hem de AS13335 biçimlerini kabul eder.

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

Örnek yanıt

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

Bir IP adresini doğrulayın ve türünü belirleyin. Sorgu kotasını tüketmez.

Example response

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

GET /v1/fraud/{ip}

VPN, proxy, Tor, veri merkezi ve geçmiş kötüye kullanım sinyallerini birleştiren risk seviyesi ve uygulanabilir öneri içeren bileşik dolandırıcılık puanı (0–100). Starter plan veya üstü

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

Risk seviyeleri ve öneriler

GET /v1/probe/{ip}

60'tan fazla aktif yoklama düğümümüzden gerçek zamanlı ağ prob verileri: açık TCP portları, servis banner'ları, ters DNS, tam TLS sertifika detayı (konu, veren, SAN'lar, geçerlilik) ve tespit edilen servis kategorileri. Pro plan veya üstü

Nasıl çalışır

• · Taze veri (≤ 7 gün eski): önbellekten hemen döndürülür.
• · Eski veri (> 7 gün): hemen döndürülür ve arka planda yeniden tarama kuyruğa alınır. Yanıt "stale": true.
• · Hiç yoklanmamış: anında tarama için bir prob kuyruğa alınır. İlk sonuçlar genellikle 1–5 dakika içinde gelir.
• · Prob kotası, aylık sorgu kotanızın %10'udur. Özel / ayrılmış IP'ler yoklanamaz.

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

Taradığımız portlar

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

Kullanım senaryoları

• · Dolandırıcılık karşıtı — özdeş SSH sürümleri / TLS parmak izleri çalıştıran bot çiftliklerini tespit edin
• · Tehdit istihbaratı — banner / sertifika değişiklikleri için C2 sunucularını izleyin
• · OSINT / hata ödülü — herhangi bir genel IP'deki servisleri hızlıca listeleyin
• · Barındırma / ISS operasyonları — ağınızdaki açık proxy'leri / Tor çıkışlarını bulun

GET /v1/proxy-attribution/{ip}

Bir IP'nin bilinen bir konut proxy havuzuna, ticari VPN'e veya veri merkezi aralığına ait olup olmadığını tanımlar. Genel is_proxy işaretlerinin aksine bu uç nokta IP'yi belirli sağlayıcıya (Bright Data, Oxylabs, NordVPN vb.) atfeder — bazı sağlayıcılara izin verip diğerlerini engellemesi gereken dolandırıcılık ekipleri için kritik. Proxy Intel eklentisi

Örnek yanıt (VPN aralığındaki IP)

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

Ağ türleri

• · residential — konut proxy havuzları (Bright Data, Oxylabs, Smartproxy, IPRoyal, Hola, Honeygain, EarnApp, Peer2Profit, SOAX)
• · vpn — ticari VPN sağlayıcıları (NordVPN, ExpressVPN, Surfshark, Mullvad, ProtonVPN, PIA, IPVanish, CyberGhost)
• · datacenter — ticari proxy çıkışı için sık kullanılan barındırma sağlayıcıları (AWS, DigitalOcean, OVH, Hetzner vb.)
• · tor — Tor çıkış / geçiş düğümleri
• · mobile — mobil operatör proxy havuzları

Öneriler

GET /v1/account/usage

Hesabınız için geçerli faturalama dönemi kullanım istatistiklerini döndürür.

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

Planınız için mevcut MMDB veritabanlarını listeler. Çevrimdışı / uç kullanım için MaxMind .mmdb alternatifleri — herhangi bir MaxMind DB okuyucusuyla çalışır (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}

Ham MMDB dosyasını akıtır. Koşullu GET'ler için ETag + If-None-Match destekler (dosya değişmediğinde 304 Not Modified). Hız sınırı: kaynak başına günde 10 indirme.

Mevcut kaynaklar

Örnek: PHP'de indirme + kullanma

# 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']

Yaptırım İşareti

Her /v1/lookup yanıtı, geo bloğunda IP adresinin ülkesinin uluslararası yaptırımlara tabi olup olmadığını bildiren iki alan içerir.

Kapsanan yaptırım listeleri: OFAC (ABD), AB, BM Güvenlik Konseyi, İngiltere OFSI. Şu anda işaretlenen ülkeler arasında İran, Kuzey Kore, Rusya, Belarus, Suriye, Küba, Venezuela, Sudan ve diğerleri bulunmaktadır. Liste, programlar değiştikçe güncellenmektedir.

Yaptırım uygulanan ülke örneği

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

Bot Tespiti

OpenIPApi, meşru tarayıcıları tanımlamak için çift ters DNS doğrulaması gerçekleştirir. Sonuç her sorguda threat.bot_type alanında mevcuttur.

Doğrulama yöntemi: (1) IP üzerinde PTR sorgusu → ana bilgisayar adı. (2) Ana bilgisayar adı botun etki alanı kalıbıyla eşleşmelidir (örn. *.googlebot.com). (3) Ana bilgisayar adı üzerindeki ileri DNS, orijinal IP'ye geri çözümlemelidir. Sonuçlar 24 saat önbelleklenir.

Doğrulanmış Googlebot örneği

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

Geçmiş Sorgu

Herhangi bir tek IP sorgusuna ?date=YYYY-MM-DD parametresi ekleyerek o tarihteki anlık görüntüyü alın.

Örnek istek

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

Yanıt zarfı

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

Hata: anlık görüntü yok

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

Hata kodları

Hız sınırları

Aylık sorgu kotalarına ek olarak, istekler kayan pencere kullanılarak API anahtarı başına hız sınırına tabidir. Aşıldığında API HTTP 429 ve bir Retry-After başlığıyla birlikte döndürür.

Ek sınırlar: /v1/validate (kimlik doğrulamasız), arayan IP başına dakikada 60 istekle sınırlandırılmıştır; /v1/me dakikada 30 istekle. MMDB indirmeleri kaynak ve hesap başına günde 10 ile sınırlıdır. Hız sınırı yanıtları Retry-After.

Webhooklar

Webhooklar, izlediğiniz bir IP'nin durumu değiştiğinde gerçek zamanlı HTTP POST bildirimleri almanızı sağlar. Bunları konsolda → Webhooklar, veya gösterge paneli arayüzü üzerinden yapılandırın — API çağrısı gerekmez.

Olaylar

İstek başlıkları

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

Örnek yük

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

İmzayı doğrulama

Her webhook, webhook sırrınızla ham JSON gövdesinin HMAC-SHA256'sı kullanılarak imzalanır. İmza X-OpenIPApi-Signature başlığında sha256=<hex>. olarak gönderilir. Yük üzerinde işlem yapmadan önce her zaman doğrulayın:

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

Yeniden deneme politikası

Uç noktanızın teslim alındığını onaylamak için 10 saniye içinde HTTP 2xx ile yanıt vermesi gerekir. Diğer durumlar (veya zaman aşımı), üstel geri çekilmeli yeniden denemeleri tetikler: 1 dak., 5 dak., 30 dak., 2 sa., 12 sa. Son girişimden sonra webhook başarısız olarak işaretlenir ve bir gösterge paneli uyarısı oluşturulur.

Teslim geçmişi ve tekrar oynatma

konsolda → Webhooklar hesap başına son 100 teslim girişimini saklar; olay türü, HTTP durum kodu ve uç noktanızın döndürdüğü yanıt gövdesi gösterilir. tekrar oynat önceki herhangi bir teslimatı orijinal imzalı yükü yeniden göndermek ve yerleşik İmza Hata Ayıklayıcısı ile sırrınızı herhangi bir sunucuyla paylaşmadan HMAC-SHA256 imzalarını tarayıcı içinde doğrulayın.

Tekrar oynatılan teslimatlar, uç noktanızın bunları canlı olaylardan ayırt etmesi için ek bir X-OpenIPApi-Replay: 1 başlığı içerir.

Kod örnekleri — curl

Tek sorgu

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

Toplu sorgu

$ 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'niz

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

Kod örnekleri — JavaScript

Tek sorgu (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

Toplu sorgu

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

Kod örnekleri — Python

Tek sorgu (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

Toplu sorgu

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