Geo-IP Tracking

⭐ Pro

Geo-IP tracking is a Burst Statistics Pro feature. Learn more about geographic insights

Burst Statistics Pro uses the MaxMind GeoLite2 database to determine visitor location from their IP address. No data is sent to external services at tracking time — lookups happen entirely on your server using a locally stored database file.

---

How It Works

When a visit is recorded, Burst resolves the visitor's IP address against the local MaxMind database. Depending on which database type is configured, it can return country, state/region, and city information.

The database file is downloaded automatically on plugin activation and refreshed every two months via the burst_daily cron job.

---

Database Types

Two database variants are supported:

Type	File	Data Available
country	GeoLite2-Country.tar.gz	Country code only
city	GeoLite2-City.tar.gz	Country, continent, state/region, city, accuracy radius

The active database type is controlled by the geo_ip_database_type plugin option. If a mismatch is detected between the option value and the actual downloaded file, the database is re-downloaded automatically.

---

Location Data

A successful lookup returns the following fields:

Field	Type	Description
country_code	string	ISO 3166-1 alpha-2 country code (e.g. US)
continent_code	string	Two-letter continent code (e.g. EU) — city DB only
state	string	Most specific subdivision name — city DB only
state_code	string	ISO subdivision code — city DB only
city	string	City name — city DB only
city_code	int	GeoNames ID for the city — city DB only
accuracy_radius	int	Accuracy radius in kilometres — city DB only

All fields are present in the returned array regardless of database type; fields unavailable in the country database are returned as empty strings or 0.

---

Database Update Process

Automatic updates

The database is checked daily via the burst_daily action. If the database has never been downloaded, or was last downloaded more than two months ago, it is re-downloaded automatically.

The download process:

1. Downloads GeoLite2-City.tar.gz (or GeoLite2-Country.tar.gz) from Burst's CDN.
2. Extracts the .mmdb file using PHP's PharData extension.
3. Moves the .mmdb to the wp-content/uploads/burst/maxmind/ directory.
4. Cleans up all temporary files (.tar.gz, .tar, extracted folder).
5. Stores the path to the .mmdb file in the burst_geo_ip_file option.

Manual upload

If automatic download fails you can upload the .mmdb file manually to the maxmind upload directory. Burst will detect the file on the next page load and clear any existing import error.

Preventing automatic updates

To disable automatic database updates (for example, when managing the file manually), define the following constant in wp-config.php:

define( 'BURST_DO_NOT_UPDATE_GEO_IP', true );

---

Requirements

Requirement	Notes
PHP PharData extension	Required to extract the .tar.gz archive. If unavailable, an admin notice is shown.
Writable uploads directory	Burst must be able to write to wp-content/uploads/burst/maxmind/.
No open_basedir restriction on the download path	If detected, an admin notice is shown with manual upload instructions.

caution

If the PharData PHP extension is not enabled on your server, the database cannot be extracted automatically. Contact your hosting provider to enable it, or upload the .mmdb file manually.

---

Hooks & Filters

burst_geo_ip_enabled

Controls whether Geo-IP tracking and database management are active. Return false to disable all Geo-IP functionality, including the daily database check and the initialization routine.

Parameters:

Parameter	Type	Description
$enabled	bool	Whether Geo-IP is enabled. Default true.

Example:

add_filter( 'burst_geo_ip_enabled', function( $enabled ) {
    // Disable Geo-IP tracking entirely.
    return false;
} );

---

burst_zip_file_path

Filters the full path used when saving the downloaded .tar.gz archive before extraction.

Parameters:

Parameter	Type	Description
$zip_file_path	string	Absolute path to the zip file destination.

Example:

add_filter( 'burst_zip_file_path', function( $zip_file_path ) {
    // Override the download destination path.
    return '/custom/path/GeoLite2-City.tar.gz';
} );

---

burst_localhost_location_data

Filters the fallback location data returned when a localhost IP address (::1) is detected. Useful during local development to simulate a specific location.

Parameters:

Parameter	Type	Description
$location_data	array	Associative array of location fields. Default values represent Groningen, NL.

Example:

add_filter( 'burst_localhost_location_data', function( $location_data ) {
    // Simulate a US visitor during local development.
    return [
        'city'            => 'New York',
        'city_code'       => 5128581,
        'state'           => 'New York',
        'state_code'      => 'NY',
        'country_code'    => 'US',
        'continent_code'  => 'NA',
        'accuracy_radius' => 5,
    ];
} );

---

burst_tasks (filter)

Burst registers a task notice for Geo-IP import errors via this filter. If the database download fails, an admin notice is added to the Burst tasks list with the error message and a link to the troubleshooting guide.

The notice is suppressed immediately after plugin activation (while the database may still be downloading) and is automatically cleared once a valid database file is detected.

---

WordPress Options

The following options are used internally by the Geo-IP system:

Option	Description
burst_geo_ip_file	Absolute path to the active .mmdb database file.
burst_last_update_geo_ip	Unix timestamp of the last successful database download.
burst_geo_ip_last_attempt	Unix timestamp of the last download attempt (throttled to once per 5 minutes).
burst_geo_ip_import_error	Error message from the last failed download attempt, or absent if healthy.
burst_import_geo_ip_on_activation	Flag that triggers a fresh database download on the next admin page load after activation.

---

GDPR Considerations

caution

IP addresses are personal data under GDPR. Review your privacy policy and consent setup before enabling Geo-IP tracking.

• IP address lookups are performed server-side using a local database. No IP address is transmitted to MaxMind or any third party at tracking time.
• The MaxMind database itself is downloaded from Burst's CDN (burst.ams3.cdn.digitaloceanspaces.com). No visitor data is involved in this download.
• Burst resolves an IP to a location and then discards the raw IP address (subject to your anonymisation settings). Only the resolved location fields (country, city, etc.) are stored.
• If you operate under a strict consent model, use the burst_geo_ip_enabled filter to disable location tracking until consent is granted.

add_filter( 'burst_geo_ip_enabled', function( $enabled ) {
    // Only enable Geo-IP when the visitor has given consent.
    return (bool) my_consent_check();
} );