Track and analyse every visitor. Visualise traffic. Detect threats.
A WordPress plugin that enriches visitor IP addresses with real-time geolocation, ISP data, and risk intelligence — powered by the IpQuery API via guibranco/ipquery-php.
| Feature | Description | |
|---|---|---|
| 🗺️ | World heatmap | Interactive Leaflet.js map with a heat layer weighted by visit count |
| 📊 | Country & city charts | Horizontal bar chart of top countries; dedicated top-cities table with country flags |
| 🛡️ | Risk intelligence | Per-IP flags for VPN, proxy, Tor, datacenter, and mobile connections |
| 🔢 | Risk scoring | Numeric risk score (0–100) per IP with colour-coded indicators |
| 🔍 | Visitors table | Searchable, sortable, filterable table with full enrichment data for every IP |
| 🔎 | Manual lookup | Instantly enrich any IP address on demand from the admin panel |
| ⚡ | Non-blocking | API calls run at shutdown — visitor page load is never delayed |
| 🗄️ | Smart caching | WordPress transients cache each IP for 1 hour; only one API call per IP per hour |
| 🧹 | Auto-retention | Configurable data retention with daily WP-Cron cleanup |
| 🔒 | Privacy controls | Exclude IPs, skip logged-in users or admins, disable tracking at any time |
The plugin adds an IpQuery entry to the WordPress admin sidebar with three sub-pages.
Dashboard — a live overview built from four widgets:
- Stat cards — total visits, unique IPs, VPN/proxy/Tor count, and overall risk rate
- Visitor heatmap — world map with gradient heat layer (blue → yellow → red)
- Top countries — bar chart (Chart.js) and a flag-annotated data table
- Top cities — table with city name, country flag, visit count, and traffic share
- Risk breakdown — doughnut chart and individual cards for each risk type
Visitors — full paginated table of every tracked IP with search, type filters, per-row delete, manual lookup form, and bulk purge.
Settings — all tracking options, data retention, excluded IPs list, and a system status panel.
Visitor browser request
│
▼ WordPress bootstrap
│
[ init ] IpQuery_Tracker registered
│
[ wp ] maybe_track()
│ ├─ skip: AJAX / REST / Cron
│ ├─ skip: logged-in / admin (configurable)
│ ├─ resolve IP (Cloudflare → X-Real-IP → X-Forwarded-For → REMOTE_ADDR)
│ ├─ skip: private ranges, excluded IPs
│ ├─ transient hit → bump visit_count only
│ └─ transient miss → register shutdown callback
│
Page rendered & sent to browser ◄──── no latency added
│
[ shutdown ] lookup_and_store()
│
▼
IpQueryClient::getIpData($ip) ← guibranco/ipquery-php
│
▼
GET https://api.ipquery.io/{ip}?format=json
│
▼
IpQueryResponse { location, isp, risk }
│
▼
IpQuery_DB::upsert() → wp_ipquery_visitors
│
▼
set_transient( "ipq_{md5}", 1, HOUR_IN_SECONDS )
| Requirement | Minimum |
|---|---|
| WordPress | 6.0 |
| PHP | 8.2 |
| PHP extension | cURL |
| Database | MySQL 5.7+ / MariaDB 10.3+ |
No Composer or external package manager needed — guibranco/ipquery-php is bundled inside
includes/vendor/.
- Download the latest
.zipfrom the Releases page. - In your WordPress admin go to Plugins → Add New Plugin → Upload Plugin.
- Upload the
.zipand click Install Now, then Activate.
git clone https://github.com/guibranco/ipquery-wordpress.gitCopy the ipquery-wordpress/ folder into wp-content/plugins/, then activate it from Plugins in the WordPress admin.
The plugin automatically:
- Creates the
wp_ipquery_visitorsdatabase table - Writes default settings to
wp_options - Schedules a daily WP-Cron event for data retention cleanup
Navigate to IpQuery → Settings to configure:
| Setting | Default | Description |
|---|---|---|
| Enable Tracking | ✅ On | Master switch — disable to pause all tracking |
| Track Logged-in Users | ❌ Off | Whether authenticated visitors are tracked |
| Track Administrators | ❌ Off | Whether manage_options users are tracked |
| Look Up Private IPs | ❌ Off | Send private/LAN IPs to the API (useful for local dev) |
| Excluded IPs | (empty) | Newline-separated list of IPs to never track |
| Data Retention | 90 days | Records older than this are auto-deleted by cron |
Full documentation: guilherme.stracini.com.br/ipquery-wordpress/configuration
A single table wp_ipquery_visitors is created on activation:
id BIGINT UNSIGNED PRIMARY KEY AUTO_INCREMENT
ip VARCHAR(45) UNIQUE NOT NULL
country VARCHAR(100)
country_code VARCHAR(10)
city VARCHAR(100)
state VARCHAR(100)
zipcode VARCHAR(20)
latitude DECIMAL(10,7)
longitude DECIMAL(10,7)
timezone VARCHAR(100)
asn VARCHAR(50)
org VARCHAR(255)
isp VARCHAR(255)
is_mobile TINYINT(1)
is_vpn TINYINT(1)
is_tor TINYINT(1)
is_proxy TINYINT(1)
is_datacenter TINYINT(1)
risk_score SMALLINT(3)
first_seen DATETIME
last_seen DATETIME
visit_count BIGINT UNSIGNEDipquery-wordpress/
├── ipquery-wordpress.php # Plugin bootstrap & constants
├── includes/
│ ├── vendor/ # Bundled guibranco/ipquery-php
│ │ ├── IpQueryClient.php
│ │ ├── IpQueryException.php
│ │ ├── IIpQueryClient.php
│ │ └── Response/
│ │ ├── IpQueryResponse.php
│ │ ├── Isp.php
│ │ ├── Location.php
│ │ └── Risk.php
│ ├── class-ipquery-db.php # Table install, upsert, and query helpers
│ ├── class-ipquery-tracker.php # Visitor capture, IP resolution, caching
│ └── class-ipquery-admin.php # Admin menus, AJAX, action handlers
├── admin/views/
│ ├── dashboard.php # Heatmap, charts, stat cards, tables
│ ├── visitors.php # Searchable/sortable visitor log
│ └── settings.php # Settings form & system status
├── assets/
│ ├── css/admin.css
│ ├── js/ipquery-maps.js # Leaflet heatmap
│ └── js/ipquery-charts.js # Chart.js bar & doughnut charts
├── docs/ # Jekyll / Just the Docs site
│ ├── _config.yml
│ ├── index.md
│ ├── installation.md
│ ├── configuration.md
│ ├── dashboard.md
│ ├── visitors.md
│ ├── tracking.md
│ ├── api.md
│ └── privacy.md
└── .github/workflows/
└── docs.yml # GitHub Pages deployment
| Dependency | Role |
|---|---|
| guibranco/ipquery-php | PHP client library for the IpQuery API — bundled inside the plugin |
| IpQuery API | Free IP intelligence service providing geolocation, ISP, and risk data |
| Leaflet.js | Interactive world map rendering |
| Leaflet.heat | Heatmap layer for Leaflet |
| Chart.js | Bar and doughnut charts |
| OpenStreetMap | Map tile provider |
| Flag CDN | Country flag images |
Full documentation is available at guilherme.stracini.com.br/ipquery-wordpress.
| Page | Description |
|---|---|
| Installation | System requirements and install steps |
| Configuration | All settings explained |
| Dashboard | Widget reference |
| Visitors | Visitor table, filters, and lookup |
| How Tracking Works | Technical flow and caching |
| IpQuery API | API fields and PHP library reference |
| Privacy & GDPR | Data collected, controls, and policy guidance |
Contributions, issues, and feature requests are welcome.
- Fork the repository
- Create a feature branch:
git checkout -b feat/my-feature - Commit your changes:
git commit -m "feat: add my feature" - Push to the branch:
git push origin feat/my-feature - Open a Pull Request
Please follow the WordPress Coding Standards for PHP files.
Distributed under the MIT License. See LICENSE for full text.
Made with ❤️ by Guilherme Branco Stracini · Built on guibranco/ipquery-php