Retrieve geolocation data

Abstract

How to use the GeoIP API to retrieve geolocation data from interactions and IP addresses.

Sitecore provides API services for working with geolocation data. It is possible to get, for example, the city, country, or region from the IP address of the request.

The Tracker API provides access to the GeoIP data for the current interaction with the help of the Sitecore.Analytics.Tracker.Current.Interaction.GeoData property. For example, you can use the following code to retrieve the country for the current interaction:

var country = Sitecore.Analytics.Tracker.Current.Interaction.GeoData.Country;

You can also retrieve geolocation data for a specific IP address. There are two methods you can use for this purpose:

  • Sitecore.Analytics.Lookups.GeoIPManager

  • Sitecore.CES.GeoIp.Core.Lookups.LookupManager.GetWhoIsInformationByIp(...)

Use the GeoIPManager service

In order to retrieve geolocation data for an IP address, the Sitecore.Analytics.Lookups.GeoIPManager service performs a lookup in the local memory cache and the ReferenceData service . If it does not find the data there, it creates a separate thread and calls Sitecore.CES.GeoIp.Core.Lookups.LookupManager to get the data from the geolocation service.

This example shows how you can use Sitecore.Analytics.Lookups.GeoIpManager to resolve the country from the IP address:

using System; 
using System.Net; 
using Sitecore.Analytics.Lookups; 
using Sitecore.Analytics.Model;
…
public string GetCountryByIp(IPAddress ipAddress)
{
    var millisecondsTimeout = 2000;
    var options = new GeoIpOptions(ipAddress, millisecondsTimeout);
    // For Sitecore version prior to 9.1.1
    //var addressBytes = ipAddress.GetAddressBytes();
    //var options = new GeoIpOptions();
    //options.Ip = GeoIpManager.IpHashProvider.ResolveIpAddress(addressBytes);
    //options.Id = GeoIpManager.IpHashProvider.ComputeGuid(addressBytes);
    //options.MillisecondsTimeout = millisecondsTimeout;
    string country = DefaultCountry; //will be used if we are not be able to resolve the country using service.

    try
    {
        var result = GeoIpManager.GetGeoIpData(options);
        if (result.ResolveState == GeoIpResolveState.Resolved &&
            result.WhoIsInformation != null)
        {
            country = result.WhoIsInformation.Country;
        }    
    }
    catch (Exception)
    {
        // Handle the exceptions
    }
    return country;
}

When you create the GeoIpOptions variable, you must set the millisecondsTimeout parameter. This parameter defines how long the method waits to resolve the data. If the method cannot retrieve the data within the defined time, the process returns an empty GeoIpResult, and continues in the background. This prevents the method from blocking the request if data resolving takes too long.

We recommend that you set millisecondsTimeout to no more than a few seconds, so it does not add extra run time to page loading in case of any data resolving delays.

Note

If you set millisecondsTimeout to -1, the method waits infinitely long for the response from the service.

Use the GetWhoIsInformationByIp API

To resolve geolocation data, you can also use the underlying API of Sitecore.CES.GeoIp.Core.Lookups.LookupManager.GetWhoIsInformationByIp(...), which goes directly to the geolocation service. However, this API does not have a wait timeout functionality, so we recommend that you use caution when calling it from the request thread.

By default, the service does not use a cache. To enable caching:

  1. On your Sitecore instance, browse the App_Config\Sitecore\DetectionServices.Location\Sitecore.CES.GeoIP.config configuration file to find the location of the CES.GeoIp.Caching.GeoIpCacheSize setting.

  2. Create a patch file to change the CES.GeoIp.Caching.GeoIpCacheSize setting to the size of the cache you want to use.

    Note

    For more details on how to use this setting, refer to the description in the config file.