Gecka Geolocation for WordPress

Plugins keep asking where an IP address comes from: to name the country of a visitor, to show where an attack originates, to let WooCommerce guess the location of a customer. Gecka Geolocation answers that question on your server, from the IP geolocation databases of MaxMind, DB-IP or IPinfo, which it downloads and keeps up to date. No address of a visitor leaves the server.

On its own, the plugin changes nothing on your site. It serves the plugins that ask it, Gecka Security and Gecka Antispam among them, and WooCommerce when you turn that on. Until one of them asks, it keeps the databases ready.

🧭 Principles

• Everything stays on your server. The lookups read files on disk. Nothing about the site or its visitors goes to a provider: the only requests are the downloads of the databases.
• The provider is your choice. MaxMind, DB-IP or IPinfo, one or several, free or paid. A plugin asking a question gets the best database installed for it.
• The licences are handled for you. The plugins that show the data get the credit the free databases ask for, an outdated GeoLite release is reported before its 30 days are out, and the files are kept out of reach of browsers.
• One download for the whole network. On a multisite, every site shares the settings and the databases.
• Nothing is downloaded until you ask. No database is fetched before you tick it and enter the credentials of its provider.

🗺️ Databases

The MaxMind tab asks MaxMind which databases your account has access to, and marks them. When several databases of a provider answer the same question, the paid one wins over the free one, and the most detailed over the others.

📊 Choosing a provider

The three free offers compared. The paid GeoIP databases of MaxMind are GeoLite with more detail, more fields and daily releases.

What each database answers, as the plugin reads it:

A region or a city is only as good as the database. For taxes or anything binding, the paid databases are the ones made for it.

⚙️ Setting up

1. Activate the plugin, for the network on a multisite.
2. Under Settings > Geolocation (network admin on a multisite), open the tab of a provider:
   • MaxMind: open a free GeoLite account at maxmind.com, or use your GeoIP account, create a licence key on the licence keys page of the account, and enter the account ID and the key.
   • DB-IP: nothing to enter.
   • IPinfo: open a free account at ipinfo.io and enter the access token of its dashboard.
3. Tick the databases and save. The Databases tab downloads them with a progress bar, shows their release and lets you try an address with any provider.
4. In the Settings tab, choose the provider the plugins and WooCommerce get when they name none. By default it is the first one with databases in place, in the order MaxMind, DB-IP, IPinfo.

To keep the credentials out of the database, define them in wp-config.php. The settings then show the field disabled, with the name of its constant:

define('GECKA_GEOLOCATION_MAXMIND_ACCOUNT_ID', '123456');
define('GECKA_GEOLOCATION_MAXMIND_LICENSE_KEY', 'your_licence_key');
define('GECKA_GEOLOCATION_IPINFO_TOKEN', 'your_token');

🔄 Updates

A daily task asks each provider for its latest releases and downloads only what changed. A download is checked against the checksum the provider publishes, then opened to make sure it holds the database expected, and moved in place of the old one in one step: a request never reads half a file. A database you untick is deleted. When a download fails, the task tries again within the hour, and Site Health tells you why.

Asking MaxMind for its latest releases does not count in the daily download limit of your account. DB-IP publishes one release a month. IPinfo limits the downloads of a token to a few a day, so the plugin downloads only when the checksum it publishes changed.

⚖️ Licence of the databases

• MaxMind. The GeoLite databases are under the GeoLite End User License Agreement, the GeoIP ones under your agreement with MaxMind. GeoLite asks for the credit "This product includes GeoLite Data created by MaxMind, available from https://www.maxmind.com", and that a release be deleted within 30 days of a newer one. The plugin updates every day, and when it cannot, past that delay, Site Health turns critical and an error shows in the admin. The lookups go on: updating or removing the database is up to you.
• DB-IP. The Lite databases are under the Creative Commons Attribution 4.0 licence, which asks for a link "IP Geolocation by DB-IP" to https://db-ip.com on the pages that show or use their results.
• IPinfo. IPinfo Lite is under the Creative Commons Attribution-ShareAlike 4.0 licence, which asks for the credit "IP address data powered by IPinfo", linking to https://ipinfo.io.

The plugins showing the locations get the wording and the link of each credit from gecka_geolocation_credit().

The MaxMind licence forbids handing the files to third parties. They live in uploads/gecka-geolocation-<random key>/, with a .htaccess denying access, which Apache honours. On Nginx or another server, deny that directory in the configuration, or move the databases out of the web root with the GECKA_GEOLOCATION_DIRECTORY constant. Site Health checks that the directory cannot be reached from outside.

🖼️ Logos of the networks

A switch in the Settings tab, off by default, gives the plugins the logo of the network of an address, as a small PNG image. The server downloads each logo once from asn-data, a mirror of PeeringDB with the favicon of the site of each network, and serves it from uploads/gecka-geolocation-logos/: browsers never ask the source. Many networks have no logo there; the plugins then show a generic icon. Turning the switch off deletes the logos.

🛒 WooCommerce

A switch in the Settings tab has WooCommerce locate its customers with the default provider, through its woocommerce_get_geolocation filter and ahead of its own MaxMind integration. The default customer location set to Geolocate, taxes and shipping then read the country, the state, the city and the postal code from here, and WooCommerce needs no licence key of its own. A country a CDN header gives WooCommerce wins. A state is filled in only when WooCommerce lists the subdivision under the same code.

🩺 Site Health

The test of the databases turns critical for a database outdated past the limit of its licence or a data directory reachable from outside, and recommended for no provider set up, a database missing, a failed update, or a daily task that has not run for two days. The Info tab sums up, for each provider, the credentials in use (never their value), the databases, their release, size and errors. Both show to whoever manages the plugin only.

🌍 Multisite

On a network, the plugin is activated network-wide and set up from the network admin. Every site shares the settings and the files: one download serves the network. The daily task is scheduled on the main site.

🔒 Privacy

Nothing about the site or its visitors goes to the providers. The requests download files, from download.maxmind.com and the storage it redirects to (with the account ID and the licence key, to MaxMind only), from download.db-ip.com, and from ipinfo.io and the storage it redirects to (with the token, to IPinfo only). With the logos of the networks on, the server asks tiagozip.github.io for the logo of a network number, once. The plugin keeps no address.

🧩 Works with

• Gecka Security uses the locations for its country rules on logins, its alert on a login from a new network, the country and the network under each address of its journal, and its statistics of where the attempts come from.
• Gecka Antispam breaks the submissions it refuses down by country and network.
• WooCommerce, as above.
• Your own plugin or theme, through a few functions available once the plugin is loaded: the country of an address, a full record, the flag, the logo of the network, the credit to show. Another plugin can also add a provider of its own. See docs/DEVELOPERS.md.

🙅 Out of scope

Gecka Geolocation locates addresses and stops there. It does not block visitors by country, redirect them to a language or a store, or change the content of a page: those are for the plugins that ask it, Gecka Security for the country rules on logins. It shows no map and keeps no history of the addresses looked up.

📋 Requirements

• WordPress 6.8 or later, single site or multisite
• PHP 8.2 or later, with zlib, which reads the archives. With intl, the countries are named in the language of the site; without it, in English or French from the list of the plugin
• For MaxMind, an account: a free GeoLite one, or a paid GeoIP subscription. For IPinfo, the access token of a free account. For DB-IP, nothing
• Composer 2, if you install the plugin with Composer

The functions, the record, the providers, the hooks, the files and the work on the plugin itself are documented in docs/DEVELOPERS.md.

📜 Licence

Copyright 2026 Gecka. GPL-3.0-or-later. The MaxMind reader in inc/vendor-prefixed/ is under the Apache License 2.0, the flags in assets/flags/ (flag-icons) under the MIT licence.

Built with 🥥 and ☕ by Gecka — Kanaky-New Caledonia 🇳🇨