This article explains how to add an IP geolocator to your website using the MaxMind GeoLite City database.
IP Geolocation is the process of finding the geographical location of a website visitor. Finding the location of your website visitors enables you to serve location-specific content. This article explains how to add an IP geolocator to your web pages with the MaxMind GeoLite City database. MaxMind GeoLite City provides the following information for an IP address:
I’ll add the following country information:
I’ll also add the following time information:
Before explaining how to add the extra continent and time zone information, I’ll introduce a more consistent and easy-to-use interface to the GeoLite City database.
Given a reference to the GeoLite City database and an IP address, MaxMind’s
geoip_record_by_addr function returns a PHP object that contains country and city information for the IP address:
The following table lists the references to the
$record object required to access each piece of information:
|Two-Letter Country Code||
|Three-Letter Country Code||
To get the name of the region we need to look it up in
$GEOIP_REGION_NAME, the MaxMind array that maps the two-letter code of the country and a MaxMind region code onto the name of the region. Even at this early stage, accessing information from MaxMind’s object structure is becoming untidy. Furthermore, the GeoLite City database doesn’t provide continent or time zone information.
The geolocation.php file contains the
ip2c_geolocation function that retrieves MaxMind’s information and adds the country and time zone information. This function returns an array that provides a consistent interface to the GeoLite City information and the extra continent and time zone information. For example, the following PHP statement retrieves the geolocation information for the IP address 126.96.36.199 and stores it in the
To retrieve the geolocation information for your website visitors, use PHP’s
The following table lists the array elements that hold each piece of geolocation information:
|Two-Letter Continent Code||
|Two-Letter Country Code||
|Three-Letter Country Code||
The continents.php file contains two arrays,
$IP2C_CONTINENT_NAME, that provide the continent information for a country. The
ip2c_geolocation function looks up the name of a continent and its two-letter code in these two arrays.
(All of the arrays used in this article start with
IP2C_ to follow the naming convention of the functions used in this article, which all start with
ip2c_, a shortened form of the phrase IP to country.)
$IP2C_CONTINENT array maps a two-letter country code onto a two-letter continent code:
$IP2C_CONTINENT_NAME array maps a two-letter continent code onto the name of the continent:
For example, the following PHP statements return the name of the continent that contains the United Kingdom, which is Europe:
The countries.php file contains the
$IP2C_COUNTRY_LOCATION array that maps a two-letter country code onto a two-element array containing the longitude and latitude of the centre of the country:
For example, the following PHP statements return the latitude and longitude of the centre of the USA, which has two-letter country code, US:
The timeZones.php file contains the
$IP2C_TIME_ZONES array that maps a two-letter country code onto a string or an array:
A two-letter country code maps onto a string when the country has a single time zone. The value of the string is the name of the time zone. For example, the two-letter country code of the United Kingdom, GB, maps onto a string containing the name of the UKs single time zone:
When a country has more than one time zone, its two-letter country code maps onto an array, each element of which is a two-element array that contains the name of one of the country’s time zones and the longitude of the centre of the time zone. For example, the two-letter country code of Australia, AU, maps onto an array that represents Australia’s twelve time zones:
The localTime.php file contains the following functions that together return the local time in a country:
Given a two-letter country code and a longitude, the
ip2c_getTimeZone function returns the time zone for the specified country. If the country has more than one time zone, this function returns the time zone nearest to the specified longitude. If
ip2c_getTimeZone can’t identify the time zone, it returns “Unknown”.
Given an array containing the time zones of a country and a longitude, the
_ip2c_getNearestTimeZone function returns the time zone nearest to the specified longitude. This function is prefixed with an underscore to indicate that it is a utility function used by the
ip2c_getTimeZone function; it is not designed to be called directly.
After retrieving the name of the time zone with the
ip2c_getTimeZone function, use the
ip2c_getLocalTime function to return the local time. Given the name of a time zone, the
ip2c_getLocalTime function returns the local time in unix epoch seconds, or zero if the name of the time zone is “Unknown”.
ip2c_getLocalTime function calls the localTime.pl Perl script to return the local time in unix epoch seconds:
For example, to return the local time in the capital of Malaysia, Kuala Lumpur, type the following at the command line:
The geolocatorTemplate.php file contains a template for creating your own IP geolocator. This template assumes that the following files are located in the same directory as the template:
Additionally, the template assumes that the following MaxMind files are in the same directory as the template:
You need to download these files from MaxMind.
The template produces a web page that displays the following information for the visitor: