🌍 Stracini Visitor Analytics with IpQuery

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.

📖 Documentation · 🐛 Report a Bug · ✨ Request a Feature

Plugin renamed for WordPress.org directory compliance The WordPress.org Plugin Review Team flagged "IpQuery" as a trademark that belongs to the IpQuery API service. The plugin has been renamed to Stracini Visitor Analytics with IpQuery to make it clear this is an independent, third-party integration and is not officially affiliated with IpQuery. The repository name, internal class names, database table, and option keys are unchanged.

✨ Features

🖥️ Admin screens

Dashboard

The plugin adds a Visitor Analytics 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.

🏗️ Architecture

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 )

📋 Requirements

No Composer or external package manager needed — guibranco/ipquery-php is bundled inside includes/vendor/.

🚀 Installation

From GitHub releases

1. Download the latest .zip from the Releases page.
2. In your WordPress admin go to Plugins → Add New Plugin → Upload Plugin.
3. Upload the .zip and click Install Now, then Activate.

Manually

git clone https://github.com/guibranco/ipquery-wordpress.git

Copy the ipquery-wordpress/ folder into wp-content/plugins/, then activate it from Plugins in the WordPress admin.

On activation

The plugin automatically:

• Creates the wp_ipquery_visitors database table
• Writes default settings to wp_options
• Schedules a daily WP-Cron event for data retention cleanup

⚙️ Configuration

Navigate to Visitor Analytics → Settings to configure:

Full documentation: guilherme.stracini.com.br/ipquery-wordpress/configuration

🗃️ Database schema

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 UNSIGNED

📦 Project structure

ipquery-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

🔌 Powered by

📖 Documentation

Full documentation is available at guilherme.stracini.com.br/ipquery-wordpress.

🤝 Contributing

Contributions, issues, and feature requests are welcome.

1. Fork the repository
2. Create a feature branch: git checkout -b feat/my-feature
3. Commit your changes: git commit -m "feat: add my feature"
4. Push to the branch: git push origin feat/my-feature
5. Open a Pull Request

Please follow the WordPress Coding Standards for PHP files.

📄 License

Distributed under the MIT License. See LICENSE for full text.

Made with ❤️ by Guilherme Branco Stracini · Built on guibranco/ipquery-php