API-dokumentaatio

Todennus

Kaikki API-pyynnöt tulee sisällyttää API-avaimesi otsikossa X-API-Key API-avaimesi löytyy konsolista.

X-API-Key: oip_your_api_key_here

Perus-URL

Kaikki API-pyynnöt tehdään seuraavaan perus-URL:iin HTTPS:n kautta:

https://api.openipapi.com

Koneluettava määritys (OpenAPI 3.1): /openapi.yaml.

Vastausmuoto

Kaikki vastaukset ovat JSON-muodossa. Onnistuneet vastaukset palauttavat HTTP 200. Virhevastauksissa palautetaan asianmukainen 4xx tai 5xx -tilakoodi kentällä error .

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

GET /v1/lookup/{ip}

Hae geolokalisaatio-, verkko- ja uhkadata yksittäiselle IP-osoitteelle.

Parametrit

Vastauksen kentät

Esimerkkipyyntö

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

Esimerkkivastaus

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

Hae useita IP-osoitteita yhdellä pyynnöllä. Eräkokorajoitukset riippuvat suunnitelmastasi.

Eräkokorajoitukset

Pyynnön runko

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

Vastaus

Palauttaa käärityn taulukon täydellisiä hakuobjekteja samassa järjestyksessä kuin pyyntö.

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

Palauttaa geolokalisaatio- ja uhkadatan pyynnön tehneelle IP-osoitteelle. Hyödyllinen "Mikä on IP-osoitteeni?" -ominaisuuksiin.

Vastaus on sama kuin GET /v1/lookup/{ip} pyytäjän IP:llä esitäytettynä.

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

GET /v1/asn/{asn}

Hae yksityiskohtaiset tiedot autonomisesta järjestelmästä. Vaatii Starter-suunnitelman tai korkeamman.

Parametri asn hyväksyy sekä muodon 13335 että AS13335 .

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

Esimerkkivastaus

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

Validoi IP-osoite ja määritä sen tyyppi. Ei kuluta hakukiintiötä.

Example response

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

GET /v1/fraud/{ip}

Yhdistelmäpetospisteet (0–100) riskitasolla ja toimintasuosituksella. Yhdistää VPN-, proxy-, Tor-, konesali- ja historiallisen väärinkäytön signaalit. Starter tai korkeampi

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

Riskitasot ja suositukset

GET /v1/probe/{ip}

Reaaliaikainen verkkotestausdata yli 60 aktiivisesta testaussolmustamme: avoimet TCP-portit, palvelubannerit, käänteinen DNS, täydellinen TLS-sertifikaatin tiedot (aihe, myöntäjä, SAN:t, voimassaolo) ja havaitut palvelukategoriat. Pro tai korkeampi

Miten se toimii

• · Tuore data (≤ 7 päivää vanha): palautetaan välittömästi välimuistista.
• · Vanhentunut data (> 7 päivää): palautetaan välittömästi ja taustalla käynnistetään uusintatestaus. Vastauksessa on mukana "stale": true.
• · Ei koskaan testattu: skannaus asetetaan jonoon välittömästi. Ensimmäiset tulokset saapuvat tyypillisesti 1–5 minuutissa.
• · Testauksen kiintiö on 10 % kuukausittaisesta hakukiintiöstäsi. Yksityisiä / varattuja IP-osoitteita ei voi testata.

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

Skannattavat portit

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

Käyttötapaukset

• · Petostorjunta — tunnista bottifarmit, joilla on identtiset SSH-versiot / TLS-sormenjäljet
• · Uhkatiedustelu — seuraa C2-palvelimia bannerin / sertifikaatin muutosten varalta
• · OSINT / bug bounty — luettele nopeasti palvelut millä tahansa julkisella IP:llä
• · Hosting / ISP-ops — löydä avoimet proxyt / Tor-poistumissolmut verkostasi

GET /v1/proxy-attribution/{ip}

Tunnistaa, kuuluuko IP tunnettuun asuinalueproxypooluun, kaupalliseen VPN:ään tai konesalialueeseen. Toisin kuin geneerisistä is_proxy indikaattoreista, tämä endpoint attribuoi IP:n tietylle palveluntarjoajalle (Bright Data, Oxylabs, NordVPN jne.) — kriittistä petostiimeille, joiden täytyy sallia jotkut palveluntarjoajat ja estää toiset. Proxy Intel -lisäosa

Esimerkkivastaus (IP VPN-alueella)

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

Verkkotyypit

• · residential — asuinalueproxypooluihin (Bright Data, Oxylabs, Smartproxy, IPRoyal, Hola, Honeygain, EarnApp, Peer2Profit, SOAX)
• · vpn — kaupalliset VPN-palveluntarjoajat (NordVPN, ExpressVPN, Surfshark, Mullvad, ProtonVPN, PIA, IPVanish, CyberGhost)
• · datacenter — hosting-palveluntarjoajat, joita käytetään usein kaupallisena proxy-poistumisena (AWS, DigitalOcean, OVH, Hetzner jne.)
• · tor — Tor-poistumis- / relaysolmut
• · mobile — mobiilioperaattorin proxypooluihin

Suositukset

GET /v1/account/usage

Palauttaa nykyisen laskutusjakson käyttötilastot tilillesi.

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

Listaa suunnitelmaasi kuuluvat MMDB-tietokannat. Suorat MaxMind .mmdb -korvikkeet offline- / edge-käyttöön — toimii minkä tahansa MaxMind DB -lukijan kanssa (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}

Lähettää MMDB-tiedoston streamina. Tukee ETag + If-None-Match ehdollisille GET-pyynnöille (304 Not Modified kun tiedosto ei ole muuttunut). Pyyntörajoitus: 10 latausta per lähde per päivä.

Saatavilla olevat lähteet

Esimerkki: lataa ja käytä PHP:ssä

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

Sanktioilmaisin

Jokainen /v1/lookup vastaus sisältää kaksi kenttää geo lohkossa, jotka kertovat, onko IP:n maa kansainvälisten pakotteiden alainen.

Katetut pakotelistat: OFAC (USA), EU, YK:n turvallisuusneuvosto, UK OFSI. Tällä hetkellä merkittyihin maihin kuuluvat Iran, Pohjois-Korea, Venäjä, Valko-Venäjä, Syyria, Kuuba, Venezuela, Sudan ja muut. Lista pidetään yllä ja päivitetään ohjelmien muuttuessa.

Esimerkki sanktioiden alaisesta maasta

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

Bottien tunnistus

OpenIPApi suorittaa kaksoiskäänteisen DNS-varmennuksen tunnistaakseen oikeutetut indeksointirobotit. Tulos on saatavilla threat.bot_type jokaisessa haussa.

Varmennusmenetelmä: (1) PTR-haku IP:lle → isäntänimi. (2) Isäntänimen tulee vastata botin verkkotunnusmallia (esim. *.googlebot.com). (3) Isäntänimen eteenpäin suuntautuvan DNS:n tulee ratkaista takaisin alkuperäiseen IP:hen. Tulokset välimuistitetaan 24 tunniksi.

Esimerkki vahvistetusta Googlebotista

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

Historiallinen haku

Lisää parametri ?date=YYYY-MM-DD mihin tahansa yksittäiseen IP-hakuun hakeaksesi tilannevedoksen kyseiseltä päivältä.

Esimerkkipyyntö

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

Vastauksen kuori

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

Virhe: tilannevedosta ei ole saatavilla

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

Virhekoodit

Pyyntörajoitukset

Kuukausittaisten hakukiintiöiden lisäksi pyyntöjä rajoitetaan API-avainkohtaisesti liukuvan ikkunan avulla. Ylitettäessä API palauttaa HTTP 429 otsikolla Retry-After .

Lisärajoitukset: /v1/validate (todentematon) rajoitettu 60 pyyntöön/min per pyytäjän IP; /v1/me 30 pyyntöön/min. MMDB-lataukset rajoitettu 10/päivä per lähde per tili. Pyyntörajoitusvastaukset sisältävät Retry-After.

Webhookit

Webhookit mahdollistavat reaaliaikaisten HTTP POST -ilmoitusten vastaanottamisen, kun seuraamasi IP:n tila muuttuu. Konfiguroi ne konsolissa → Webhookit, tai hallintapaneelin käyttöliittymässä — API-kutsuja ei tarvita.

Tapahtumat

Pyyntöotsikot

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

Esimerkkinuorma

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

Allekirjoituksen varmistaminen

Jokainen webhook on allekirjoitettu HMAC-SHA256:lla raakasta JSON-rungosta webhook-salaisuudellasi. Allekirjoitus lähetetään otsikossa X-OpenIPApi-Signature muodossa sha256=<hex>. Varmista aina ennen kuin toimit nuorman perusteella:

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

Uudelleenyritysperiaate

Endpointisi on vastattava 10 sekunnin sisällä HTTP 2xx -koodilla vastaanoton vahvistamiseksi. Mikä tahansa muu tila (tai aikakatkaisu) käynnistää eksponentiaaliset uudelleenyritykset: 1 min, 5 min, 30 min, 2 t, 12 t. Viimeisen yrityksen jälkeen webhook merkitään epäonnistuneeksi ja hallintapaneeliin luodaan hälytys.

Toimitushistoria ja uudelleenlähetys

konsolissa → Webhookit säilyttää viimeiset 100 toimitusyritystä per tili, näyttäen tapahtumatyypin, HTTP-tilakoodin ja endpointisi palauttaman vastaustekstin. Voit lähettää uudelleen minkä tahansa aiemman toimituksen lähettääksesi alkuperäisen allekirjoitetun nuorman uudelleen, ja käyttää sisäänrakennettua Allekirjoitusten virheenkorjaustyökalua HMAC-SHA256-allekirjoitusten varmistamiseen asiakaspuolella ilman salaisuuden jakamista palvelimelle.

Uudelleenlähetetyt toimitukset sisältävät lisäotsikon X-OpenIPApi-Replay: 1 jotta endpointisi pystyy erottamaan ne live-tapahtumista.

Koodiesimerkit — curl

Yksittäinen haku

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

Eräkyselyhaku

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

Oma IP

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

Koodiesimerkit — JavaScript

Yksittäinen haku (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

Eräkyselyhaku

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

Koodiesimerkit — Python

Yksittäinen haku (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

Eräkyselyhaku

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