Using geolocation for contacts

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 GeoIP Databases.

The default database is GeoLite City (Legacy). You can extend the accuracy of the feature by downloading additional databases.

Using GeoIP2 Databases

The GeoLite and GeoIP Legacy Databases will be discontinued. We recommend transitioning to the newer GeoLite2 or GeoIP2 Databases – see the Managing your MaxMind databases section.

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.

On this page

Kentico EMS required

Features described on this page require the Kentico EMS license.

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 Kentico contact fields.

    Note

    By default, Kentico contacts do not have an equivalent of the following fields:

    • Area code
    • Metro code
    • DMA code
    • Latitude
    • Longitude

    To learn how to create custom fields for holding the data, see Adding custom fields to contacts.

    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.

    Area code

    Integer‑based and text‑based fields.

    Note: The area code data is not available when using GeoIP2 Databases.

    Metro code

    Integer‑based and text‑based fields.

    DMA code

    Integer‑based and text‑based fields.

    Note: The DMA code data is not available when using GeoIP2 Databases.

    Latitude

    Floating-point number and text‑based fields.

    Longitude

    Floating-point number and text‑based fields.

    Organization/ISP

    Text-based fields.

    Note: Organization data is only available if you have the GeoIP Organization Database (Legacy) or GeoLite2 ASN Database added to your project.

  6. Click Save.

Managing your MaxMind databases

You can improve the functionality of geolocation by using more detailed and accurate databases and by keeping your current databases up to date.

Adding GeoIP2 databases

The initially used GeoLite or GeoIP Legacy databases will be discontinued. If you wish to integrate MaxMind's newer GeoIP2 Databases, use the following manual process:

  1. Apply hotfix 11.0.27 or newer to your Kentico instance.
  2. Open your web project in Visual Studio. For sites created using the MVC development model, perform all of the following steps in the MVC project that provides the live site.
  3. Right-click the project in the Solution Explorer and select Manage NuGet Packages.
  4. Install the Kentico.Geolocation.Update-v11 package.

    Note: The package also installs several required dependencies, such as the MaxMind.GeoIP2 package and version 11.0.2 of the Newtonsoft.Json package. You need to accept all license agreements and ensure that these packages work correctly with any customizations you may have in your project. If you have any custom projects within the solution that use the same packages, you need to consolidate the package versions.

  5. Download the free GeoLite2 City database or purchase the GeoIP2 City database (provides more accuracy and details).
  6. Place the database file into your project's ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder.
  7. Open your project's web.config file, and make sure the CMSGeoIPLocationFileName key (in the appSettings section) is set according to the name of your geolocation database file (GeoLite2-City.mmdb or GeoIP2-City.mmdb).

    Example
    <add key="CMSGeoIPLocationFileName" value="GeoIP2-City.mmdb" />
  8. (Optional) If you also wish to use the GeoLite2 ASN database to determine the organization name of visiting contacts, download the GeoLite2 ASN database file (GeoLite2-ASN.mmdb) and place it into your web project's ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder.

The geolocation feature now uses the added GeoLite2 or GeoIP2 databases. You can no longer use the GeoIP Legacy databases.

Adding GeoIP City (Legacy)

The GeoIP City Legacy database provides more accurate results than the default GeoLite City Legacy database.

  1. Obtain the GeoIP City Legacy database.
  2. Place the database file into the ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder of your web project.
  3. Configure the system to use the new geolocation database by adding the following key to the appSettings section of your web.config file. Specify the name of the database file as the key's value.

    <add key="CMSGeoIPLocationFileName" value="GeoIPCity.dat" />

Geolocation now uses the GeoIPCity.dat database instead of the default GeoLiteCity.dat database.

Adding GeoIP Organization (Legacy)

The GeoIP Organization Legacy database allows the system to determine the organization name of visiting contacts. 

Note that the database only contains data for large corporations and organizations, and does not have guaranteed accuracy. We recommend contacting MaxMind support for more information about the accuracy of the organization data.

  1. Obtain the GeoIP Organization Legacy database.
  2. Place the database file into the ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder of your web project.

    Note: The name of the database file must be GeoIPOrg.dat.

Geolocation now supports organization detection.

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 web project's ~/App_Data/CMSModules/WebAnalytics/MaxMind/ folder.


Was this page helpful?