In this section:
1. The default setup (Cloudflare and Maxmind Geolite2)
2. Accuracy
3. Auto-updating Maxmind Country IP data
4. Using OTHER GeoLocation systems with the CCA plugin
5. How to use country GeoLocation in YOUR OWN PHP applications
6. I want to/am using Maxmind’s paid for data
7. I want to use Maxmind’s Geolite2 city instead of country db
Information on GeoLocation and caching is now on a separate page
1. The default setup
If you use Cloudflare and have “switched on” their GeoLocation option ( see Cloudflare’s instructions) then it will be used to identify visitor country. If not (or Cloudflare fails to identify country), then the Maxmind GeoLite2 Database will be used.
2. Accuracy
Cloudflare: No figures available. I assume Cloudflare buy-in GeoLocation from a specialist provider, these typically claim 99.x% accuracy. Cloudflare also use GeoLocation for security purposes, so high accuracy is in its own interest.
Maxmind: According to figures I have seen: 98%+ for the free GeoLite data (supplied with the plugin), and 99.8% if you opt to use their premium paid for GeoIP data files.
3. Updating
The allocation of IP ranges to countries will change slightly over time. To cater for this:
- Cloudflare will periodically update its data (frequency unknown)
- Maxmind issues new data files once a month (once a week for those who’ve paid for a license).
This plugin automatically updates Maxmind data files. (Dashboard->Settings->Category Country Goodies->Countries uncheck/check the “add to WP scheduler” box and save settings to disable/enable automatic update.)
4. Using other GeoLocation systems with the CCA plugin
CCA version 1.2.0 onwards: there is a new mechanism to do this requiring creation of one file with a single function which will also be used by the Country Caching plugins. (New documentation here).
Pre 1.2.0 instructions for reference (will not work for 1.2.0 onwards).
You can add a WordPress filter to hook in another GeoLocation system. I recommend you make it into a plugin rather than add it to functions.php.
Example of plugin to use IP2Location’s script and their free IP Lite Database already installed on my site:
001<?php
002/*
003Plugin Name: CCA use IP2Location
004Description: filter for CCA geolocation
006Version: 0.0.1
007*/008function your_get_ccode_function($countryCode) {
009 include_once 'path_to_script/' . 'IP2Location.php';
010 $loc = new IP2Location('path_to_script/' . 'databases/IP2LOCATION-LITE-DB1.BIN', IP2Location::FILE_IO);
011
012 $ip = $_SERVER['REMOTE_ADDR'];
013 $result=$loc->lookup($ip, IP2Location::ALL);
014 $countryCode = $result->countryCode;
015 if (ctype_alpha($countryCode) && strlen($countryCode) == 2) return $countryCode;
016 return '';
017}
018add_filter('cca_country_code_from_other_geoip', 'your_get_ccode_function');
You should not attempt adding your own filters unless you are an experienced PHP coder. The simplified example above works for IP2Location; BUT if the database file does not exist then the site will display fatal error messages instead of posts! Make sure your function includes adequate error handling e.g. pre-check if files exist, and if not return with an error message immediately.
The filter should return either:
- the 2 character alphabetic Country code for the visitor’s location; OR
- an empty string ”, if visitor location cannot be identified; OR
- an error message string of at least 3 characters in length
If your filter returns an empty string the CCA plugin will attempt to identify user location via i. Cloudflare & ii. Maxmind. The current version of CCA plugin treats returned error messages the same as empty strings, however a means of notifying you of problems reported by your filter may be added to a later release.
5. How to use GeoLocation in your own non-CCA applications
i. Within your own WordPress code:
Remember shortcodes are available as well
a. Get the country code for the visitor’s location:
CCAgeoip::get_visitor_country_code(‘lower’)
Returns the alphabetic 2 character ISO country code for the visitor, or an empty string if not found.
Use the ‘lower’ argument if you want the country code in lowercase.
b. Get the country name of the visitor’s location:
Returns the country name (see dropdown box above for actual text used for a country). For compactness small less visited “countries” e.g. “British Antartic Territiories” are omitted.
c. Determine whether or not visitor is from the European Union:
Returns true if visitor is from the EU; or false otherwise. The list of “is EU” country codes user modifiable via the “Countries” tab of CCA settings.
d. Determine whether visitor is from one or more specified countries:
“‘AA,BB'” is a comma separated list of country codes. The function returns true if the visitor is from one of the countries in this list (otherwise false is returned).
e. Determine whether visitor is NOT from one of the specified countries:
“‘AA,BB'” is a comma separated list of country codes. The function returns true if the visitor is NOT from one of the countries in this list (otherwise false is returned).
f. Get a country code/country name array:
You can use this array to create a country/ISO Code selection box e.g.:
$country_array = CCAgeoip::get_country_array();
$selected = 'US';
foreach($country_array as $country_code=>$country_name ) :
echo '<option value="' . $country_code .'" ' .
selected($selected, $country_code, FALSE ) . '>' .
$country_name .'</option>';
endforeach;
ii. Using Maxmind functions directly Within your own WordPress code:
You can include (your WP plugins dir path/category-country-aware/maxmind/geoip.inc) Maxmind’s legacy script, and use its functions in your own code. Google for guides on usage.
6. I want to use Maxmind’s paid for data, or Geolite City instead of Geolite Country
Likewise if you are paying for Maxmind’s premium data, do a completely separate install and connect the CCA plugin via a filter (section 4 above). If you install Maxminds premium databases in the CCA plugin’s ‘maxmind’ directory they will work – but new versions of the plugin will overwrite these with the Maxmind Lite data.
This product includes GeoLite data created by MaxMind, available from http://www.maxmind.com .
Leave a Reply