%META:TOPICINFO{author="TWikiContributor" date="1557011955" format="1.1" version="$Rev$"}%
---+!! Geo Lookup Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/GeoLookupPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/GeoLookupPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div></sticky>
%SHORTDESCRIPTION%

---++ Syntax Rules

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

| *Write this:* | *Renders as: (if installed)* | *Simulated example:* |
| =%<nop>GEOLOOKUP{"75.52.124.86"}%= | %GEOLOOKUP{"75.52.124.86"}% | Sunnyvale, CA, USA |

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=: [[http://code.google.com/apis/adwords/docs/developer/adwords_api_us_metros.html][Metropolitan code]] (USA only)
      * =$area_code=: Telephone area code (USA only)

Examples:
   * =%<nop>GEOLOOKUP{"75.52.124.86"}%= shows default format =Sunnyvale, CA, USA=
   * =%<nop>GEOLOOKUP{"75.52.124.86" format="$latitude, $longitude"}%= shows comma separated latitude and longitude

---++ Usage Examples

#WhereIs
---+++ Form to query geo-location by IP address

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

<form action="%SCRIPTURL{view}%/%WEB%/%TOPIC%#WhereIs">
| IP or domain: | <input type="text" name="ip" value="%URLPARAM{"ip" encode="entity" default="%REMOTE_ADDR%"}%" class="twikiInputField" /> <input type="submit" value="Lookup" class="twikiSubmit" /> |
| Location: | %GEOLOOKUP{%URLPARAM{"ip" encode="quotes" default="%REMOTE_ADDR%"}%}% ([[http://maps.google.com/maps?z=12&ll=%ENCODE{%GEOLOOKUP{"%URLPARAM{"ip" encode="quotes" default="%REMOTE_ADDR%"}%" format="$latitude,$longitude"}%}%][map]]) |
</form>

---+++ 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:
<verbatim>
%WIKINAME% has been registered with %EMAILADDRESS%, %REMOTE_ADDR%, %GEOLOOKUP{%REMOTE_ADDR%}%
</verbatim>

---+++ Where am I connecting to the internet?

Show visitors where they connect to the internet. For example, write this:
<verbatim>
http://maps.google.com/maps?z=12&ll=%ENCODE{%GEOLOOKUP{"%REMOTE_ADDR%" format="$latitude,$longitude"}%}%
</verbatim>
to get this link: (renders properly if plugin is installed and enabled)%BR%
http://maps.google.com/maps?z=12&ll=%ENCODE{%GEOLOOKUP{"%REMOTE_ADDR%" format="$latitude,$longitude"}%}%

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 ==%<nop>&lt;plugin&gt;_&lt;setting&gt;%==, such as ==%<nop>GEOLOOKUPPLUGIN_SHORTDESCRIPTION%==

   * One line description, is shown in the %SYSTEMWEB%.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 ==%TOPIC%.zip== in your twiki installation directory. Content:
     | *File:* | *Description:* |
     | ==data/TWiki/%TOPIC%.txt== | Plugin topic |
     | ==data/TWiki/VarGEOLOOKUP.txt== | Variable documentation |
     | ==lib/TWiki/Plugins/%TOPIC%.pm== | Plugin Perl module |
     | ==pub/TWiki/%TOPIC%/twiki-logo-80x40-t.gif== | Branding icon |
   * Configure the Plugin:
      * Run the [[%SCRIPTURL%/configure%SCRIPTSUFFIX%][configure]] script to enable the Plugin
   * Install CPAN:MaxMind::DB::Reader
   * Download the free !GeoIP database:<br />
     Visit https://dev.maxmind.com/geoip/geoip2/geolite2/ and download !GeoLite2 City !MaxMind DB binary, gzipped, or: <br />
     =cd /usr/share/GeoIP= <br />
     =wget <nop>https://geolite.maxmind.com/download/geoip/database/GeoLite2-City.tar.gz= <br />
     =tar -xzf <nop>GeoLite2-City.tar.gz= <br />
     =cp -p <nop>GeoLite2-City_20190430/GeoLite2-City.mmdb .= <br />
     =wget <nop>https://geolite.maxmind.com/download/geoip/database/GeoLite2-Country.tar.gz= <br />
     =tar -xzf <nop>GeoLite2-Country.tar.gz= <br />
     =cp -p <nop>GeoLite2-Country_20190430/GeoLite2-City.mmdb .= <br />
      * __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/share/GeoIP/GeoLite2-City.mmdb=. For non-standard location define a =$TWiki::cfg{GeoLookupPlugin}{GeoDataFile}= configure setting in =twiki/lib/LocalSite.cfg=
   * Test if the installation was successful:
      * =%<nop>GEOLOOKUP{"216.58.216.96"}%= returns: %GEOLOOKUP{"216.58.216.96"}%

---++ Plugin Info

|  Plugin Author: | TWiki:Main.PeterThoeny, [[http://twiki.org/][TWiki.org]] |
|  Copyright: | &copy; 2010-2019 TWiki:Main.PeterThoeny <br /> &copy; 2010-2019 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Plugin Version: | 2019-05-04 |
|  Change History: | <!-- versions below in reverse order -->&nbsp; |
|  2019-05-04: | TWikibug:Item7863: Support new !MaxMind::DB::Reader using new !GeoLite2-City.mmdb |
|  2016-01-17: | TWikibug:Item7708: Copyright update to 2016 |
|  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<br /> CPAN:Geo::IP::PurePerl (no C API dependency) |
|  Other Dependencies: | [[http://www.maxmind.com/app/c][GeoIP C API]] if Geo::IP is used |
|  Perl Version: | 5.008 |
|  [[TWiki:Plugins/Benchmark][Benchmarks]]: | %SYSTEMWEB%.GoodStyle 99%, %SYSTEMWEB%.FormattedSearch 100%, %TOPIC% 100% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC% |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Dev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/%TOPIC%Appraisal |

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

__Related Topics:__ VarGEOLOOKUP, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.DeveloperDocumentationCategory, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences

%META:FILEATTACHMENT{name="twiki-logo-80x40-t.gif" attachment="twiki-logo-80x40-t.gif" attr="h" comment="" date="1264233115" path="twiki-logo-80x40-t.gif" size="1999" user="TWikiContributor" version="1"}%
