Visitor Geolocation

Last Updated: Aug 19, 2023
documentation for the dotCMS Content Management System

You can retrieve geolocation information for the current visitor using the $visitor.geo object. The Visitor Geolocation information 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 city, country, and time zone.


  • $visitor.geo will give you geolocation information for the requesting IP and cache that for the remainder of the visitor's session.
  • $visitor.getGeo("IP_ADDRESS") will give you geolocation information for the IP_ADDRESS passed in.

All of the following information can be accessed via the properties of the $visitor.geo object in your Velocity code:

DescriptionExample Values
(for Miami, FL, USA)
cityStringThe full name of the visitor's city."Miami"
companyStringThe name of the company the visitor's IP address is registered to.null
continentStringThe full name of the visitor's continent."North America"
continentCodeStringThe code for the visitor's continent."NA"
countryStringThe full name of the visitor's country."United States"
countryCodeStringThe code of the visitor's country."US"
ipAddressStringThe visitor's IP address.""
latitudeFloatThe latitude associated with the visitor's IP address.25.7617
longitudeFloatThe longitude associated with the visitor's IP address.-80.1918
subdivisionStringThe full name of the visitor's state, province, or region."Florida"
subdivisionCodeStringThe code for the visitor's state, province, or region."FL"
timezoneStringThe location-based name of the visitor's time zone."America/Miami"


  • To access an individual property, append the property name to the $visitor.geo object, as in the following example:
  • You may display all the properties of the $visitor.geo object at once, by displaying the entire object to the screen.
    • However the geolocation information is not displayed if you display the entire $visitor object to the screen; you must explicitly reference the $visitor.geo object for the geolocation information to be displayed.
  • The visitor's latitude and longitude are determined from the IP address of the current visitor viewing the Page.
  • All other values are determined based on this geolocated latitude and longitude.
    • 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.

Updating the Geo IP database

Because dotCMS is open source, dotCMS ships with the last opensource compatible version of MaxMind's GEO_IP database, which is now more than 4 years old. It is possible to update the GEO_IP database with modern data by purchasing a new version of the database from MaxMind.

dotCMS provides a plugin that can be used to update the geoip database in your dotCMS and dotCMS Cloud instances. Please see the instructions for using this plugin to upload and update GEO_IP in your dotCMS instances.

On this page


We Dig Feedback

Selected excerpt: