Visitor Geolocation - Documentation topics on: geoip,geolocation,viewtools,.

Visitor Geolocation

You can retrieve geolocation information for the current visitor using the MaxMind GeoLite2 database. The GeoLite2 database allows you to identify the user's location based on the user's IP address, and to retrieve specific location information such as the user's latitude and longitude.

Note:

Setup

To retrieve the GeoLite2 information for the current user, you must include the following code on your page (either in the page header or in your content):

#set($geolocationFromSession = $session.getAttribute("geolocation"))
#if(!$UtilMethods.isSet($geolocationFromSession))
    #set($locationURL = "http://www.geoplugin.net/json.gp?ip=$request.getRemoteAddr()")
    #set($geolocation = $json.fetch("$!locationURL"))
    $session.setAttribute("geolocation", $geolocation)
#else
    #set($geolocation = $session.getAttribute("geolocation"))
#end

Usage

Once you have created the $geolocation object, all of the following properties are available by accesing the $geolocation object in your Velocity code, as in the following example:

$geolocation.geoplugin_latitude

Note:

  • All values are determined based on the geolocated latitude and longitude of the current visitor viewing the page.
    • Any inaccuracies in determining the visitor's latitude and longitude will cause inaccuracies in the values of all other properties.
  • The Example Value column provides example values for a user located in Miami, Florida, USA.
PropertyData
Type
DescriptionExample Value
(Miami, FL, USA)
geoplugin_requestStringThe IP address used to determine the geolocated coordinates."97.93.92.19"
geoplugin_statusIntegerThe status of the geolocation information request.200
geoplugin_latitudeFloatThe latitude associated with the visitor's IP address.25.7617
geoplugin_longitudeFloatThe longitude associated with the visitor's IP address.-80.1918
geoplugin_areaCodeStringThe telephone area code of the visitor's location."305"
geoplugin_cityStringThe full name of the visitor's city."Miami"
geoplugin_continentCodeStringThe code for the visitor's continent."NA"
geoplugin_countryCodeStringThe code of the visitor's country."US"
geoplugin_countryNameStringThe full name of the visitor's country."United States"
geoplugin_currencyCodeStringThe currency code of the visitor's country."USD"
geoplugin_currencyConverterFloatThe conversion factor to convert the visitor's country currency to USD.1
geoplugin_currencySymbolStringThe currency symbol of the visitor's country."$"
geoplugin_currencySymbol_UTF8StringThe currency symbol of the visitor's country (UTF8 encoding)."$"
geoplugin_dmaCodeStringThe Nielson Designated Market Area (DMA) id of the visitor's location."528"
geoplugin_regionStringThe visitor's state, province, or region (usually identical to geoplugin_regionCode)."FL"
geoplugin_regionCodeStringThe code for the visitor's state, province, or region."FL"
geoplugin_regionNameStringThe full name of the visitor's state, province, or region."Florida"
geoplugin_creditStringAttribution for the geolocation library and data.MaxMind GeoLite2 (please see above)

Example

The following code displays selected geolocation information for the current user:

<h3>Geolocation Info:</h3>

#if(!$UtilMethods.isSet($geolocation))
    <p><b>No geolocation data available</b> <i>(showing USA)</i>.</p>
    ## No geolocation data available; set lat & long to geographical center of USA
    #set($latitude    = 44.9672)
    #set($longitude   = -103.7716)
    #set($country     = "Unknown")
    #set($countryCode = "Unknown")
#else
    #set($latitude    = ${geolocation.geoplugin_latitude})
    #set($longitude   = ${geolocation.geoplugin_longitude})
    #set($country     = ${geolocation.geoplugin_countryName})
    #set($countryCode = ${geolocation.geoplugin_countryCode})
#end

<ul>
    <li>Visitor's Coordinates: ${latitude}, ${longitude}</li>
    <li>Visitor's Country: ${country} (${countryCode})</li>
</ul>

For an additional example demonstrating how to use the GeoLite2 library to perform an Elasticsearch geolocation query, please see the Elasticsearch Examples documentation.