API 문서

인증

모든 API 요청에는 X-API-Key 요청 헤더에 API 키를 포함해야 합니다. API 키는 콘솔.

X-API-Key: oip_your_api_key_here

기본 URL

모든 API 요청은 HTTPS를 통해 다음 기본 URL로 이루어집니다:

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

응답

요청과 동일한 순서로 전체 조회 객체의 래핑된 배열을 반환합니다.

{
  "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, 프록시, 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 포트, 서비스 배너, 역방향 DNS, 전체 TLS 인증서 세부 정보(주체, 발급자, SAN, 유효 기간), 탐지된 서비스 카테고리. Pro 플랜 이상

작동 방식

• · 최신 데이터(7일 이하): 캐시에서 즉시 반환됩니다.
• · 오래된 데이터(7일 초과): 즉시 반환되며 백그라운드 재프로브가 대기열에 추가됩니다. 응답에는 "stale": true.
• · 한 번도 프로빙되지 않음: 즉각적인 스캔을 위해 프로브가 대기열에 추가됩니다. 첫 번째 결과는 일반적으로 1–5분 내에 도착합니다.
• · 프로브 할당량은 월 조회 할당량의 10%입니다. 사설 / 예약 IP는 프로빙할 수 없습니다.

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

사용 사례

• · 사기 방지 — 동일한 SSH 버전 / TLS 핑거프린트를 실행하는 봇 팜 탐지
• · 위협 인텔리전스 — 배너 / 인증서 변경을 위한 C2 서버 모니터링
• · OSINT / 버그 바운티 — 공개 IP의 서비스 빠르게 열거
• · 호스팅 / ISP 운영 — 네트워크에서 개방형 프록시 / Tor 출구 찾기

GET /v1/proxy-attribution/{ip}

IP가 알려진 일반 사용자 프록시 풀, 상업용 VPN, 또는 데이터센터 범위에 속하는지 식별합니다. 일반적인 is_proxy 플래그와 달리, 이 엔드포인트는 IP를 특정 제공업체(Bright Data, Oxylabs, NordVPN 등)에 귀속합니다 — 일부 제공업체는 허용하고 다른 제공업체는 차단해야 하는 사기 팀에 매우 중요합니다. Proxy Intel 애드온

응답 예제(VPN 범위의 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"
}

네트워크 유형

• · residential — 일반 사용자 프록시 풀(Bright Data, Oxylabs, Smartproxy, IPRoyal, Hola, Honeygain, EarnApp, Peer2Profit, SOAX)
• · vpn — 상업용 VPN 제공업체(NordVPN, ExpressVPN, Surfshark, Mullvad, ProtonVPN, PIA, IPVanish, CyberGhost)
• · datacenter — 상업용 프록시 출구로 자주 사용되는 호스팅 제공업체(AWS, DigitalOcean, OVH, Hetzner 등)
• · tor — Tor 출구 / 릴레이 노드
• · mobile — 모바일 통신사 프록시 풀

권고사항

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 데이터베이스를 나열합니다. 오프라인 / 엣지 사용을 위한 MaxMind .mmdb 대체품 — 모든 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 조건부 GET 지원(파일이 변경되지 않은 경우 304 Not Modified). 속도 제한: 소스당 하루 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 응답에는 IP의 국가가 국제 제재를 받는지 알려주는 두 필드가 geo 블록에 포함됩니다.

지원 제재 목록: OFAC(미국), EU, UN 안전보장이사회, 영국 OFSI. 현재 표시된 국가에는 이란, 북한, 러시아, 벨라루스, 시리아, 쿠바, 베네수엘라, 수단 등이 포함됩니다. 목록은 프로그램 변경에 따라 유지 및 업데이트됩니다.

제재 국가 예제

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

봇 탐지

OpenIPApi는 이중 역방향 DNS 검증 을 수행하여 합법적인 크롤러를 식별합니다. 결과는 모든 조회의 threat.bot_type 에서 확인할 수 있습니다.

검증 방법: (1) IP에 대한 PTR 조회 → 호스트명. (2) 호스트명이 봇의 도메인 패턴과 일치해야 합니다(예: *.googlebot.com). (3) 호스트명에 대한 정방향 DNS가 원래 IP로 다시 확인되어야 합니다. 결과는 24시간 동안 캐시됩니다.

검증된 Googlebot 예제

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

과거 조회

단일 IP 조회에 ?date=YYYY-MM-DD 파라미터를 추가하여 해당 날짜의 스냅샷을 검색합니다.

요청 예제

$ 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 */
  }
}

오류: 스냅샷 없음

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

오류 코드

속도 제한

월별 조회 할당량 외에도, 요청은 슬라이딩 윈도우를 사용하여 API 키별로 속도가 제한됩니다. 초과 시 API는 HTTP 429 와 Retry-After 헤더를 반환합니다.

추가 제한: /v1/validate (미인증)은 호출자 IP당 분당 60개 요청으로 제한됩니다; /v1/me 는 분당 30개. MMDB 다운로드는 계정당 소스당 하루 10회로 제한됩니다. 속도 제한 응답에는 Retry-After.

Webhook

Webhook을 통해 감시 중인 IP의 상태가 변경될 때 실시간 HTTP POST 알림을 받을 수 있습니다. 에서 설정하세요 콘솔 → Webhook, 또는 대시보드 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

페이로드 예제

{
  "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은 webhook 시크릿으로 원시 JSON 본문의 HMAC-SHA256을 사용하여 서명됩니다. 서명은 X-OpenIPApi-Signature 헤더에 sha256=<hex>. 로 전송됩니다. 페이로드에 따른 조치 전에 항상 검증하세요:

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

재시도 정책

엔드포인트는 수신을 확인하기 위해 10초 이내에 HTTP 2xx로 응답해야 합니다. 다른 상태(또는 타임아웃)는 지수 백오프 재시도를 트리거합니다: 1분, 5분, 30분, 2시간, 12시간. 최종 시도 후 webhook이 실패로 표시되고 대시보드 알림이 발생합니다.

배달 내역 및 재전송

콘솔 → Webhook 에서 계정당 최근 100개의 배달 시도를 보여주며, 이벤트 유형, HTTP 상태 코드, 엔드포인트가 반환한 응답 본문을 표시합니다. 원본 서명 페이로드를 재전송하려면 재전송 이전 배달을 재전송하고 내장된 서명 디버거 를 사용하여 시크릿을 서버와 공유하지 않고 브라우저에서 HMAC-SHA256 서명을 검증할 수 있습니다.

재전송된 배달에는 추가 X-OpenIPApi-Replay: 1 헤더가 포함되어 엔드포인트가 라이브 이벤트와 구별할 수 있습니다.

코드 예제 — 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"])