Using geolocation for contacts

Enterprise license required

Features described on this page require the Kentico Xperience Enterprise license.

You can use geolocation to determine the origin (real world geographic location) of your website visitors based on their IP address. The system obtains the geographic data using MaxMind’s GeoIP2 Databases.

By default, the system does not contain a geolocation database – you need to add at least one manually. You can either use the free GeoLite2 City database, or purchase the GeoIP2 City database for increased accuracy. Optionally, you can also use the GeoLite2 ASN database to get additional organization (ASN) data.

To obtain the free databases, you need to sign up for a GeoLite2 account, create a license key, and set up a download mechanism. Visit the GeoLite2 Free Downloadable Databases page for more information.

Note

The system only determines the geographic location of contacts during their first visit on a website. The information is not updated when the same contact accesses your websites again from a different location.

Configuring geolocation

To set up geolocation for your websites:

  1. Open the Settings application.

  2. Navigate to the On-line marketing -> Contact management -> Geolocation category.

  3. Select the Enable contact geolocation by IP checkbox.

  4. (Optional) Enter a Suffix for mapped data.

    • The system adds the suffix to the values of all text-based contact fields that are obtained using geolocation.
  5. Configure the mappings of geolocation data to Xperience contact fields.

    Note

    By default, Xperience contacts do not have fields for storing the following types of geolocation data:

    Field data type restrictions

    Mind the following type restrictions when assigning target fields for the geolocation data:

    Field

    Only accepts

    Country

    Integer-based and text-based fields.

    • When mapping to integer fields, the Country ID value is used
    • Text-based fields use the Country display name value

    State

    Integer-based and text-based fields.

    • When mapping to integer fields, the State ID value is used
    • Text-based fields use the State display name value

    City

    Text‑based fields.

    Postal code

    Integer‑based and text‑based fields.

    Metro code

    Integer‑based and text‑based fields.

    Latitude

    Floating-point number and text‑based fields.

    Longitude

    Floating-point number and text‑based fields.

    Organization/ASN

    Text-based fields.

    Note: Organization data is only available if you add the GeoLite2 ASN database to your project.

  6. Click Save.

Managing your MaxMind databases

By default, the system does not contain a geolocation database. To use geolocation for contacts:

Download the database files in binary format.

Database file location

Always place the database files into the ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder of the MVC project that provides your live site. You may need to manually create the required folder structure.

Adding the geolocation database

You can either download the free GeoLite2 City database or purchase the GeoIP2 City database (provides more accuracy and details).

  1. Obtain the geolocation database file (GeoLite2-City.mmdb or GeoIP2-City.mmdb).
  2. Place the database file into your MVC project’s ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder.

By default, the system is configured to use the GeoLite2 City database. If you wish to use the more extensive GeoIP2 City database, you need to add the CMSGeoIPLocationFileName key to the appSettings section of your project’s web.config file. Specify the name of the database file as the key’s value.




<add key="CMSGeoIPLocationFileName" value="GeoIP2-City.mmdb" />


Adding the ASN database

The GeoLite2 ASN database allows the system to determine the organization name of visiting contacts (based on ASN data).

  1. Download the GeoLite2 ASN database file (GeoLite2-ASN.mmdb).
  2. Place the database file into your MVC project’s ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder.

Geolocation now supports organization detection, and you can map the data to a contact field in the Xperience geolocation settings. For example, you can use the default Company field of contacts.

Updating existing databases

To ensure that the geolocation data is accurate, you need to regularly update your MaxMind databases.

To update your databases, download the newest version and upload the database file to your MVC project’s ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder.