In this section:

1. The default setup (Cloudflare and Maxmind Legacy)
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 us Maxmind’s GeoIP2 instead of Legacy

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 GeoLite Legacy Country Database, included with this plugin, will be used.

Both systems work with IPv4 and the new IPv6 addresses. Note: my server uses IPv4 so I have been unable to test the plugin for IPv6 functionality.

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

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 a country code/country name array:

CCAgeoip::get_country_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;

b. Get the country code for the visitor’s location:

CCAgeoip::get_visitor_country_code() OR
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.

c. Get the country name of the visitor’s location:

CCAgeoip::get_visitor_country_name()
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.
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 Maxmind’s GeoIP2 instead of Legacy

If you have, or wish to install, Maxmind’s GeoIP2 you can add a filter for the CCA plugin to use it (see section 4 above).
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 legacy 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 .