verifip 0.2.0

Official Python SDK for the VerifIP IP fraud scoring API

VerifIP Python SDK

Official Python SDK for the VerifIP IP fraud risk scoring API.

Installation

pip install verifip

Quick Start

from verifip import VerifIPClient

client = VerifIPClient("vip_your_api_key")
result = client.check("185.220.101.1")

print(result.fraud_score)       # 70
print(result.is_tor)            # True
print(result.signal_breakdown)  # {"tor_exit": 25, "vpn_detected": 20, ...}

Methods

check(ip: str) -> CheckResponse

Check a single IPv4 or IPv6 address.

result = client.check("185.220.101.1")

result.request_id       # UUID
result.ip               # "185.220.101.1"
result.fraud_score      # 0-100
result.is_proxy         # bool
result.is_vpn           # bool
result.is_tor           # bool
result.is_datacenter    # bool
result.country_code     # "DE"
result.country_name     # "Germany"
result.region           # "Brandenburg"
result.city             # "Brandenburg"
result.isp              # "Stiftung Erneuerbare Freiheit"
result.asn              # 60729
result.connection_type  # "Data Center"
result.hostname         # "tor-exit.example.org"
result.signal_breakdown # {"tor_exit": 25, ...}

check_batch(ips: list[str]) -> BatchResponse

Check up to 100 IPs in a single request. Requires Starter plan or higher.

batch = client.check_batch(["185.220.101.1", "8.8.8.8", "49.36.128.1"])
for result in batch.results:
    print(f"{result.ip}: score={result.fraud_score}")

Results with invalid IPs include an error field instead of raising.

health() -> HealthResponse

Check API server health (no authentication required).

health = client.health()
print(health.status)          # "ok" or "degraded"
print(health.uptime_seconds)  # 3600

Error Handling

from verifip import (
    VerifIPClient,
    VerifIPError,
    AuthenticationError,
    RateLimitError,
    InvalidRequestError,
)

try:
    result = client.check("1.2.3.4")
except AuthenticationError:
    # 401/403: invalid or disabled API key
    pass
except RateLimitError as e:
    # 429: daily limit exceeded
    print(f"Retry after {e.retry_after} seconds")
except InvalidRequestError:
    # 400: malformed or private IP
    pass
except VerifIPError as e:
    # Catch-all for any API error
    print(f"Error {e.status_code}: {e.error_code} - {e}")

Rate Limits

Rate limit info is available after any authenticated request:

result = client.check("8.8.8.8")
if client.rate_limit:
    print(f"{client.rate_limit.remaining}/{client.rate_limit.limit} requests left")
    print(f"Resets at {client.rate_limit.reset}")

Configuration

client = VerifIPClient(
    api_key="vip_your_key",
    base_url="https://api.verifip.com",  # default
    timeout=30.0,                         # seconds, default 30
    max_retries=3,                        # retries on 429/5xx, default 3
)

Option	Default	Description
api_key	required	Your VerifIP API key
base_url	https://api.verifip.com	API base URL
timeout	30.0	Request timeout in seconds
max_retries	3	Max retries on 429/5xx with exponential backoff

Retry Behavior

The SDK automatically retries on HTTP 429 and 5xx errors with exponential backoff:

• Delay: min(retry_after or 0.5 * 2^attempt, 30) + jitter
• Respects retry_after from rate limit responses
• Connection errors are also retried

Requirements

• Python 3.10+
• Zero runtime dependencies (uses urllib stdlib)

Links

• API Documentation
• GitHub
• PyPI
• Changelog