MaxMind
Find a visitor's country from their IP address, so XPAC popups and forms can target by country.
MaxMind finds a visitor's country from their IP address, using MaxMind's free GeoLite2 data. User Targeting uses it to show a popup only in some countries, or a form section only to some visitors. Install and activate XPAC User Targeting first.
Connect MaxMind
Sign up for a free GeoLite account.
In your MaxMind account, open Manage License Keys. Note the account ID shown there and choose Generate new license key.
Click Test connection. It looks up this server's address and shows the country MaxMind gives it and the lookups you have left today. It uses one of them.
Admins can see the saved keys on this screen. It also has:
- Lookup source: MaxMind web service (the default) asks MaxMind about each new visitor, with 1,000 free lookups a day. After that, country rules stop matching until midnight UTC. Downloaded GeoLite2 database answers on your server with no daily limit.
- GeoLite2 database: Download now fetches the free GeoLite2 Country database. Save your keys first. It updates weekly while it is the lookup source, and switching back to the web service deletes it.
- Lookup detail: Country (the default), or City, region and country for custom code. Rules match on country only, and city works with the web service only.
Test connection also warns when this site can't see your real address, for example behind a proxy or Cloudflare, because visitors then get no country or the wrong one. Ask your host to pass the visitor's address to WordPress.
If WooCommerce has its own MaxMind license key, lookups go through WooCommerce and its account instead, and Lookup source and Lookup detail are not used. The fields on this screen say so. To use the XPAC keys, clear the key under WooCommerce → Settings → Integration.
Use it in a popup or form
- Popups: in a popup's display rule, under User Conditions, choose Add rule, pick User Country (MaxMind), then is or isn't and a country.
- Forms: with conditional logic, add a condition on User Country (MaxMind).
The condition appears once the keys are saved, or when WooCommerce has its own key.
Only pages that need the country look the visitor up: a page whose popups have a country rule, or a page with a form when that form, or any form on the site, has a country condition. Those pages are kept out of full-page caches, because each visitor's country is written into the page. Every other page stays cacheable. If your CDN caches pages whatever the site says, exclude those pages there.
Web service answers are kept for 12 hours per address, or 10 minutes when the lookup failed. Search engines and monitoring tools don't use up lookups.
When a lookup fails
MaxMind doesn't send submissions anywhere, so it never appears on the Deliveries screen. A failed lookup gives no country:
- A popup's country rule then matches nobody, whether it says is or isn't.
- A form condition set to is not Germany still matches, so don't rely on it alone to keep a country out.
If MaxMind refuses a lookup because of wrong keys, no lookups left or too many requests, web service lookups pause for the whole site: until midnight UTC when the day's lookups are used up, as long as MaxMind asks after too many requests, and an hour otherwise. The reason and the restart time show under Test connection, and a passing test ends the pause.
When the downloaded database is the source but no file is there yet, nothing is sent to MaxMind and visitors get no country. Admins see a notice until a database is downloaded, and again if it is more than 14 days old.
Country rules suit regional offers, not security. A VPN or proxy changes the country, and MaxMind's answer is an estimate.
Privacy
With the web service, each new visitor's IP address is sent to MaxMind, a US company. With the downloaded database, it stays on your server. The country is written into the page, and saved answers are stored under a scrambled key, not the address. With city detail they also hold the city, region and postcode. No cookie is set. Mention the lookup in your privacy notice.
Deleting the standalone MaxMind plugin removes its settings, the database and the saved answers. Deactivating it stops the weekly update.
For developers
| Hook | Use |
|---|---|
xpac_maxmind_pre_place | Answer without a lookup, for example until the visitor consents. Return ['country' => ''] for no country. |
xpac_maxmind_source | web_service or database. |
xpac_maxmind_database_fallback | Return true to use the web service while the chosen database is missing. |
xpac_maxmind_lookup_level | country or city. |
xpac_maxmind_request_timeout | Seconds to wait for the web service. Default 3. |
xpac_maxmind_database_edition | Edition to download. Default GeoLite2-Country. |
xpac_maxmind_database_download_url | Where the database is downloaded from. |
xpac_maxmind_download_timeout | Seconds to wait for the download. Default 60. |
xpac_maxmind_update_database | Action. The weekly database update. |
With city detail, the userCity and userRegion data providers hold the city and
region. No rule uses them yet.
Behind a proxy or load balancer, forwarded address headers are read only if you
define XPAC_TRUST_PROXY or return true from xpac_trust_proxy_headers. Do that
only when visitors can reach the server through the proxy alone. In WooCommerce
mode, WooCommerce also trusts country headers such as CF-IPCountry.
Settings are saved in the xpac option under keys starting max_mind_.