Geo Lookup Plugin

Syntax Rules

Add %GEOLOOKUP{"host" format="..."}% anywhere in a TWiki page or skin template.

Parameters:

• "host": Host IP address (example: "75.52.124.86") or host name (example: "twiki.org")
• format="...": Format of geolocation, optional. Default is "$city, $region, $country_name". Supported variables:
  • $latitude: Latitude
  • $longitude: Longitude
  • $city: City name
  • $region: Region name
  • $country_name: Country name
  • $country_code: Two letter country code
  • $postal_code: Postal code (USA only)
  • $metro_code: Metropolitan code (USA only)
  • $area_code: Telephone area code (USA only)

Examples:

• %GEOLOOKUP{"75.52.124.86"}% shows default format Sunnyvale, CA, USA
• %GEOLOOKUP{"75.52.124.86" format="$latitude, $longitude"}% shows comma separated latitude and longitude

Usage Examples

Form to query geo-location by IP address

Example: (works properly if plugin is installed and enabled)

IP or domain:
Location:	Cambridge, MA, USA (map)

Where are people who register in TWiki?

As a TWiki administrator, you can get location information of people registering in TWiki. In twiki/templates/registernotifyadmin.tmpl write this:

%WIKINAME% has been registered with %EMAILADDRESS%, %REMOTE_ADDR%, %GEOLOOKUP{%REMOTE_ADDR%}%

Where am I connecting to the internet?

Show visitors where they connect to the internet. For example, write this:

http://maps.google.com/maps?z=12&ll=%ENCODE{%GEOLOOKUP{"%REMOTE_ADDR%" format="$latitude,$longitude"}%}%

http://maps.google.com/maps?z=12&ll=42.3646%2c-71.1028

Alternatively, in a similar way, show a map embedded in a TWiki page.

Plugin Settings

Plugin settings are stored as preferences variables. To reference a plugin setting write %<plugin>_<setting>%, such as %GEOLOOKUPPLUGIN_SHORTDESCRIPTION%

• One line description, is shown in the TextFormattingRules topic:
  • Set SHORTDESCRIPTION = Lookup geolocation by IP address or domain name

Plugin Installation Instructions

Note: You do not need to install anything on the browser to use this plugin. The following instructions are for the administrator who installs the plugin on the TWiki server.

• Download the ZIP file from the Plugin Home (see below)
• Unzip GeoLookupPlugin.zip in your twiki installation directory. Content:

  File:	Description:
  data/TWiki/GeoLookupPlugin.txt	Plugin topic
  data/TWiki/VarGEOLOOKUP.txt	Variable documentation
  lib/TWiki/Plugins/GeoLookupPlugin.pm	Plugin Perl module
  pub/TWiki/GeoLookupPlugin/twiki-logo-80x40-t.gif	Branding icon

• Configure the Plugin:
  • Run the configure script to enable the Plugin
• Install GeoIP C API and CPAN:Geo::IP (fast), or CPAN:Geo::IP::PurePerl (slower, no C API dependency)
• Download the free GeoIP database:
  cd /usr/local/share/GeoIP
wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCountry/GeoIP.dat.gz
gunzip GeoIP.dat.gz
wget http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz
gunzip GeoLiteCity.dat.gz
  
  • Hint: Install a cron to refresh the geo database once a month on the second day of the month
  • Note: The GeoIP database is assumed to be /usr/local/share/GeoIP/GeoLiteCity.dat. For non-standard location define a $TWiki::cfg{GeoLookupPlugin}{GeoDataFile} configure setting in twiki/lib/LocalSite.cfg
• Test if the installation was successful:
  • %GEOLOOKUP{"216.58.216.96"}% returns: Mountain View, CA, USA

Plugin Info

Plugin Author:	TWiki:Main.PeterThoeny, TWiki.org
Copyright:	© 2010-2015 TWiki:Main.PeterThoeny © 2010-2015 TWiki:TWiki.TWikiContributor
License:	GPL (GNU General Public License)
Plugin Version:	2015-01-09
Change History:
2015-01-09:	TWikibug:Item7604: Switch to GPL v3; doc fixes
2012-11-21:	TWikibug:Item7020: Categorize GEOLOOKUP TWiki Variable; doc fixes
2011-07-13:	TWikibug:Item6725: Change global package variables from "use vars" to "our"
2011-05-01:	TWikibug:Item6701: Doc improvements
2010-02-10:	Change country name "United States" to "USA"
2010-01-23:	Initial version
TWiki Dependency:	$TWiki::Plugins::VERSION 1.1
CPAN Dependencies:	CPAN:Geo::IP (fast), or CPAN:Geo::IP::PurePerl (no C API dependency)
Other Dependencies:	GeoIP C API if Geo::IP is used
Perl Version:	5.008
Benchmarks:	GoodStyle 99%, FormattedSearch 100%, GeoLookupPlugin 100%
Plugin Home:	http://TWiki.org/cgi-bin/view/Plugins/GeoLookupPlugin
Feedback:	http://TWiki.org/cgi-bin/view/Plugins/GeoLookupPluginDev
Appraisal:	http://TWiki.org/cgi-bin/view/Plugins/GeoLookupPluginAppraisal

This plugin refers to GeoLite data created by MaxMind, available from http://www.maxmind.com/.

Related Topics: VarGEOLOOKUP, TWikiPlugins, DeveloperDocumentationCategory, AdminDocumentationCategory, TWikiPreferences