Documentation

Docs

Everything you need to integrate GeoIPHub or self-host it on your own infrastructure.

Part 1 — API Reference

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[], blocklist_count, blocklist_sources[], dnsbl_sources[], botnet_family, botnet_role, 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: 5,000 requests per month

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

Sponsor tier: Unlimited requests

Self-hosted: No limits

Part 2 — Self-Hosting Guide

Requirements

RAM
512 MB min, 1 GB recommended
CPU
1 vCPU min, 2+ recommended
Disk
10 GB (SSD recommended)

You also need PostgreSQL 16 and Redis 7 (included in Docker Compose).

Quick Start with Docker Compose

git clone https://github.com/xhusnain/geoiphub-core.git
cd geoiphub-core
cp .env.example .env

# Edit .env — set INTERNAL_SECRET to a random string:
# openssl rand -hex 32

docker compose up -d

# Scanner API available at http://localhost:8080
# Database auto-migrates on first run

Standalone Docker Run

docker run -d \
  --name geoiphub-scanner \
  --restart unless-stopped \
  -p 8080:8080 \
  -e DATABASE_URL=postgres://USER:PASS@HOST:5432/DB \
  -e REDIS_URL=redis://HOST:6379 \
  -e INTERNAL_SECRET=$(openssl rand -hex 32) \
  -e RUST_LOG=info \
  husnainbabar/geoiphub-core:latest

Environment Variables

VariableRequiredDescription
DATABASE_URLYesPostgreSQL connection string
REDIS_URLYesRedis connection string
INTERNAL_SECRETYesHMAC secret for API authentication
RUST_LOGNoLog level (default: info)
API_BINDNoBind address (default: 0.0.0.0:8080)
RIPE_ATLAS_API_KEYNoFor geo-triangulation (optional)
PROBE_CONCURRENCYNoConcurrent port scans (default: 100)
PROBE_MAX_PER_RUNNoMax IPs to probe per cycle (default: 5000)

How the Pipeline Works

The scanner runs a 6-step pipeline on a configurable cycle (default: every 2 hours):

  1. 1
    IP Backbone

    Downloads ~700K CIDR ranges from iptoasn.com, loads 5 RIR delegation files and BGP routes (~30 seconds)

  2. 2
    Threat Feeds

    22 feed modules run in 8 parallel groups: datacenter ranges, Tor nodes, blocklists, VPN servers, proxy lists, abuse.ch, crawlers, relay services (~2-5 min)

  3. 3
    Active Scanning

    rDNS lookups, RDAP/WHOIS, and 109-port probes across 13+ protocols on priority IPs (~5 sec per IP, 50 concurrent)

  4. 4
    Geo-Triangulation

    RIPE Atlas ping measurements from 10 countries to estimate real IP location (optional, requires API key)

  5. 5
    Confidence Decay

    TTL-based flag expiration: VPN/proxy flags decay after 30 days, spam after 7 days, botnets after 14 days

  6. 6
    Cleanup

    Removes stale and redundant data. The database self-heals — can rebuild from public feeds in ~24 hours

For more detailed guides, visit the GitHub repository.

View on GitHub