Honeill Visitor Country Detection

Honeill Visitor Country Detection detects a visitor’s country (ISO 3166-1 alpha-2, e.g. GB) from their IP address using MaxMind’s GeoLite2 database, and exposes it through a single WordPress filter so your theme or plugin can use it with no hard dependency.

The GeoLite2 database is not bundled — MaxMind’s licence does not allow redistribution. Instead you enter your own free MaxMind account ID and licence key once on the settings screen. The plugin then:

• downloads the GeoLite2 country database immediately,
• stores it in wp-content/uploads (so it survives plugin updates),
• and refreshes it automatically every week via WP-Cron, checking every download before it replaces the current database.

You never download or upload a database by hand.

If your site is behind Cloudflare, the plugin uses Cloudflare’s own country header for visitors who come through it — exact, and no lookup needed — and only falls back to the database otherwise.

Use it in your code

$country = apply_filters( 'honeill_visitor_country_detection_country_code', '' );

Returns a two-letter country code, or an empty string when it can’t be determined (local IP, missing database, etc.) — your code decides the fallback. Results are cached per IP, so it’s cheap to call on every request.

Prefer REST? GET /wp-json/honeill-visitor-country-detection/v1/country returns { "country": "GB" } for the caller.

This product includes GeoLite2 Data created by MaxMind, available from https://www.maxmind.com. This plugin is an independent project and is not affiliated with, endorsed, or sponsored by MaxMind, Inc. GeoIP and GeoLite2 are trademarks of MaxMind, Inc.

External services

This plugin connects to MaxMind to download the GeoLite2 country database, which it needs to resolve countries. The database is not shipped with the plugin because MaxMind’s licence prohibits redistribution.

• Service: MaxMind GeoLite2 database download (https://download.maxmind.com/geoip/databases/GeoLite2-Country/download). MaxMind redirects the download to its own file storage, which is fetched without your credentials. If no account ID is set, MaxMind’s older endpoint (https://download.maxmind.com/app/geoip_download) is used instead.
• When it connects: when you save your licence key, when you click “Update database now”, and automatically once per week.
• What is sent: your MaxMind account ID and licence key (as HTTP Basic authentication, or as a request parameter on the older endpoint) and, by nature of any outbound HTTPS request, your server’s IP address. No website visitor data is ever sent to MaxMind or anywhere else — every lookup happens on your own server.

By using this plugin you agree to MaxMind’s GeoLite2 End User License Agreement and Privacy Policy:

• Terms: https://www.maxmind.com/en/geolite2/eula
• Privacy: https://www.maxmind.com/en/privacy_policy

Optional usage statistics:

• Service: Honeill plugin usage statistics (https://honeill-plugin-telemetry.vercel.app/api/v1/report and /api/v1/forget), run by the plugin’s author.
• Only if you opt in. Honeill Visitor Country Detection sends nothing until an administrator clicks “Allow” on the one-time notice (or turns it on in the plugin settings). It is off by default and can be turned off at any time.
• When it connects: once shortly after you opt in, then once a week. When you opt out or delete the plugin, it asks for your site’s data to be erased.
• What is sent: the plugin name and version, a random ID created for your site, your site address, WordPress/PHP/database versions, site language, whether it is a multisite, the number of users, published posts, published pages and media items, the web server software, the active theme’s name and the PHP memory limit. No personal data or content is sent.
• Privacy and terms: https://honeill-plugin-telemetry.vercel.app/privacy