create new tag
view all tags

Geo Lookup Plugin

Lookup geolocation by IP address or domain name

Syntax Rules

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

Write this: Renders as: (if installed) Simulated example:
%GEOLOOKUP{""}% , , USA Sunnyvale, CA, USA


  • "host": Host IP address (example: "") 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)


  • %GEOLOOKUP{""}% shows default format Sunnyvale, CA, USA
  • %GEOLOOKUP{"" 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: Egham, N7, United Kingdom (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:


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"}%}%
to get this link: (renders properly if plugin is installed and enabled)

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{""}% 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

Physics WebpagesRHUL WebpagesCampus Connect • Royal Holloway, University of London, Egham, Surrey TW20 0EX; Tel/Fax +44 (0)1784 434455/437520

Topic revision: r0 - 10 Jan 2015 - TWikiContributor

This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2024 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding RHUL Physics Department TWiki? Send feedback
Note: Please contribute updates to this topic on TWiki.org at TWiki:TWiki.GeoLookupPlugin.