Documentation

API Reference

Everything you need to integrate the GeoIPHub IP intelligence API into your application.

Getting Started

Authentication

All API requests require a Bearer token. Get your API key from the dashboard.

Authorization: Bearer YOUR_API_KEY

Lookup an IP

Send a GET request with any IPv4 or IPv6 address.

GET https://api.geoiphub.com/v1/lookup/{ip}

# Example
curl -H "Authorization: Bearer YOUR_KEY" \
  https://api.geoiphub.com/v1/lookup/8.8.8.8

Response Format

The API returns a JSON object with 140+ fields organized by category.

{
  "ip": "8.8.8.8",
  "country_code": "US",
  "country_name": "United States",
  "region_name": "California",
  "city": "Mountain View",
  "latitude": 37.386,
  "longitude": -122.0838,
  "timezone": "America/Los_Angeles",
  "accuracy_radius_km": 1000,
  "asn": 15169,
  "asn_org": "Google LLC",
  "asn_type": "hosting",
  "connection_type": "datacenter",
  "is_vpn": false,
  "is_proxy": false,
  "is_tor": false,
  "is_datacenter": true,
  "is_botnet": false,
  "is_spammer": false,
  "threat_score": 12,
  "confidence": 0.95,
  "recommended_action": "allow",
  "detection_methods": ["asn_classification", "datacenter_feed"],
  "open_ports": [],
  "ptr_record": "dns.google",
  "blocklist_count": 0,
  ...
}

Response Fields

Geolocation

country_code, country_name, region_name, city, latitude, longitude, timezone, accuracy_radius_km

Network / ASN

asn, asn_org, asn_type (isp/hosting/mobile/vpn/cdn/edu/gov), connection_type, isp_name, domain

Classification Flags

is_vpn, is_proxy, is_tor, is_datacenter, is_relay, is_residential_proxy, is_crawler, is_botnet, is_spammer, is_scanner, is_bogon

VPN/Proxy Details

vpn_provider, vpn_confidence, proxy_type (socks5/http_connect/http_forward/shadowsocks/openvpn/wireguard/...), proxy_anonymity

Threat Data

threat_types[], threat_score, botnet_family, botnet_role, spam_severity, scanner_verification, honeypot_hits_30d

Scoring

threat_score (0-100), confidence (0.0-1.0), recommended_action (allow/review/stepup/block), detection_methods[]

DNS / Network

ptr_record, fcrdns_valid, open_ports[], has_wireguard, has_openvpn, has_socks5, has_http_proxy

Rate Limits

Free tier: 2,000 requests per day

Pro plan: 100,000 requests per month

Business plan: Unlimited requests, custom rate limits

Public (no key): 30 requests per IP per hour

Errors

The API uses conventional HTTP status codes. Errors include a JSON body with error and message fields.

200 — Success

400 — Invalid IP address or request

401 — Missing or invalid API key

429 — Rate limit exceeded

5xx — Server error — please retry with exponential backoff

Ready to start? Get your free API key — no credit card required.

Get Started Free