Setting Up Visitor Geolocation

SlimStat resolves visitor locations through one of three providers, DB-IP City Lite, MaxMind GeoLite2, or the Cloudflare header, selected under SlimStat → Settings → Tracker in the Third-party Libraries section. Fresh installs default to DB-IP, which needs no license key. Lookups run only when PII consent permits them, because location data is personally identifiable.

Choose a provider

The Geolocation Provider select offers exactly four values: Disabled, MaxMind GeoLite2 (recommended), DB-IP City Lite (free), and Cloudflare Header. DB-IP and MaxMind keep a local .mmdb file and resolve arbitrary IP addresses, including ones entered as a report filter. Cloudflare Header reads request headers instead, so only the current visitor is resolved.

Cloudflare Header requires a CF-Ray header on the request; without that header the provider returns nothing, so a site that is not genuinely proxied through Cloudflare records no country at all. A test address such as 8.8.8.8 never resolves under Cloudflare Header, because no database is consulted. DB-IP City Lite is the least demanding option: the file downloads from cdn.jsdelivr.net with no account and no key.

Add a MaxMind license key

MaxMind GeoLite2 requires a free license key pasted into the MaxMind License Key field. SlimStat accepts 16 to 40 characters made of letters, numbers, and underscores; any other value is logged as an invalid license key format and no download is attempted. The key is sent to MaxMind’s geoip_download endpoint.

1. Register a free MaxMind account and generate a license key there.
2. Open SlimStat → Settings → Tracker in wp-admin.
3. Set Geolocation Provider to MaxMind GeoLite2 (recommended).
4. Paste the key into the MaxMind License Key field.
5. Click Save Changes, which schedules a background download ten seconds later.
6. Click Update Database to run that download immediately instead.
7. Click Check Database to confirm the .mmdb file is present at the expected path.

MaxMind archives arrive as tar.gz and are unpacked with PHP’s Phar extension. If the PharData class is unavailable, extraction fails and the .mmdb file has to be uploaded by hand to wp-content/uploads/wp-slimstat/.

Country or city precision

Geolocation Precision is a single toggle, labelled Country when on and City when off, and it defaults to Country. City precision stores city, subdivision, latitude, and longitude for every pageview; the tracker writes those values into the city and location columns of the wp_slim_stats table, alongside the two-letter country code.

Cloudflare city data depends on the Add visitor location headers Managed Transform, found under Rules → Transform Rules → Managed Transforms in the Cloudflare dashboard. Without that transform only the country code is available, whatever the SlimStat toggle says.

Where the database file lives

The path wp-content/uploads/wp-slimstat/ holds the .mmdb file, resolved from wp_upload_dir() and then passed through the slimstat_maxmind_path filter. Multisite installs strip the /sites/ID segment so one network shares a single copy. Filenames are fixed per provider: dbip-city-lite.mmdb, GeoLite2-Country.mmdb, and GeoLite2-City.mmdb. Point the filter at a shared directory to keep one file for several sites.

Disk cost tracks the provider more than the precision toggle. The DB-IP updater always fetches dbip-city-lite.mmdb, rejects a download under 1 MB or a decompressed file under 5 MB, and validates the result with a live lookup before moving it into place. MaxMind is the only provider where Country precision saves space, because GeoLite2-Country.mmdb is a smaller edition than GeoLite2-City.mmdb. Cloudflare Header and Disabled write nothing to disk. The path filter itself is documented in slimstat_maxmind_path.

Update, check, and schedule

Two buttons sit under Geolocation Database: Update Database downloads a fresh copy immediately, and Check Database tests only that the .mmdb file exists at the resolved path, reporting either that the GeoIP Database is present and ready or that the GeoIP Database was not found. It does not open the file or run a lookup, so a present-but-damaged database still reports as ready. SlimStat also registers wp_slimstat_update_geoip_database as a weekly WP-Cron event.

Saving the settings page schedules a one-off update ten seconds later whenever the database file is missing or the provider has changed. With DISABLE_WP_CRON defined, an administrator loading wp-admin triggers a non-blocking update, but only when the file is missing or the last recorded download predates the most recent update window. Both buttons check a nonce and require the SlimStat admin capability. Under Cloudflare Header, Update Database answers that Cloudflare geolocation does not require a database.

When no country is recorded

An empty country column has four causes: Geolocation Provider set to Disabled, PII consent withheld, a missing .mmdb file in wp-content/uploads/wp-slimstat/, or Cloudflare Header on a site without the CF-Ray header. Check Database separates the missing-file case from the other three in one click.

Consent gates the lookup rather than the pageview: with PII consent absent, the tracker writes the row to wp_slim_stats and leaves country empty. Banner wiring is covered in integrating with GDPR banner plugins. Country codes are stored lowercase, and the slimstat_filter_pageview_stat filter runs after the lookup, so a custom value can replace the one resolved from the database.