Description
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 license does not allow redistribution. Instead you enter your own free MaxMind license 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.
You never download or upload a database by hand.
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 license prohibits redistribution.
- Service: MaxMind GeoLite2 database download (
https://download.maxmind.com/app/geoip_download). - When it connects: when you save your license key, when you click “Update database now”, and automatically once per week.
- What is sent: your MaxMind license key (as a request parameter) and, by nature of any outbound HTTPS request, your server’s IP address. No website visitor data is ever sent to MaxMind.
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
Installation
- Upload the
honeill-visitor-country-detectionfolder to/wp-content/plugins/, or install the ZIP via Plugins Add New Upload Plugin. - Activate the plugin.
- Create a free MaxMind account and generate a license key (Account Manage License Keys): https://www.maxmind.com/en/geolite2/signup
- Go to Settings Honeill Visitor Country Detection, paste your license key, and click Save & download database.
- That’s it — the database downloads now and auto-updates weekly.
Advanced: instead of the settings field you can define the key in wp-config.php with define( 'HONEILL_VISITOR_COUNTRY_DETECTION_LICENSE_KEY', 'your-key' ); to keep it out of the database.
FAQ
-
Is it allowed to use GeoLite2 this way?
-
Yes. You use your own license key to download your own copy of the database — nothing is redistributed, which is what MaxMind’s license restricts. Attribution to MaxMind is included as required.
-
Where is the database stored?
-
In
wp-content/uploads/honeill-visitor-country-detection/. It is kept out of the plugin folder so plugin updates don’t wipe it. The plugin also drops an.htaccessto block direct web access on Apache. -
Can it detect city or region, not just country?
-
It ships with the lighter GeoLite2-Country database. City is a small change (the edition id and filename) but needs more disk space and exposes additional fields.
-
My site is behind Cloudflare / a load balancer. Will it still work?
-
Yes — it reads the left-most public IP from
X-Forwarded-For, falling back toREMOTE_ADDR. -
Downloads fail. Why?
-
Most often an incorrect license key (MaxMind returns 401/403), or the PHP
Pharextension is disabled (needed to unpack the download). The settings screen shows both.
Reviews
There are no reviews for this plugin.
Contributors & Developers
“Honeill Visitor Country Detection” is open source software. The following people have contributed to this plugin.
Contributors
Translate “Honeill Visitor Country Detection” into your language.
Interested in development?
Browse the code, check out the SVN repository, or subscribe to the development log by RSS.
Changelog
1.2.4
- Per-IP lookup results are now cached with the object cache API instead of transients. Spoofed X-Forwarded-For values could previously create unbounded per-IP transient rows in the options table.
1.2.3
- Renamed the plugin to “Honeill Visitor Country Detection” (slug
honeill-visitor-country-detection). No functional changes; filter, REST namespace, options, and constant names now use the new prefix.
1.2.2
- Tidied the plugin description (now mentions the REST endpoint).
1.2.1
- “Remove key” is now a button instead of a checkbox. The settings screen also documents the REST endpoint.
1.2.0
- License key field is now write-only and masked — the saved key is never rendered back to the browser. Added a “Remove the saved key” option.
- REST endpoint now sends no-cache headers so a per-visitor result is never cached by a CDN or page cache.
1.1.0
- Added a REST endpoint: GET /wp-json/honeill-visitor-country-detection/v1/country returns the caller’s country code.
1.0.0
- Initial release: country detection via the
honeill_visitor_country_detection_country_codefilter, license-key-based download, weekly auto-update, and a settings screen.