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{""}% GEOLOOKUP error: Geo data file /usr/local/share/GeoIP/GeoLiteCity.dat not found Sunnyvale, CA, USA


  • "host": Host IP address (example: "") or host name (example: "")
  • 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: GEOLOOKUP error: Geo data file /usr/local/share/GeoIP/GeoLiteCity.dat not found (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:{%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 in your twiki installation directory. Content:
    File: Description:
    data/TWiki/GeoLookupPlugin.txt Plugin topic
    data/TWiki/VarGEOLOOKUP.txt Variable documentation
    lib/TWiki/Plugins/ 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
    gunzip GeoIP.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: GEOLOOKUP error: Geo data file /usr/local/share/GeoIP/GeoLiteCity.dat not found

Plugin Info

Plugin Author: TWiki:Main.PeterThoeny,
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:

This plugin refers to GeoLite data created by MaxMind, available from

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

Edit | Attach | Watch | Print version | History: r2 < r1 | Backlinks | Raw View | More topic actions...
Topic revision: r1 - 2015-06-17 - TWikiAdminUser
  • Edit
  • Attach
This site is powered by the TWiki collaboration platform Powered by PerlCopyright © 1999-2020 by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
Note: Please contribute updates to this topic on at TWiki:TWiki.GeoLookupPlugin.