Retrieve geolocation data

Current version: 10.1

Sitecore provides API services for working with geolocation (GeoIP) 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:

RequestResponseshell

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.DependencyInjection.ServiceLocator.ServiceProvider.GetRequiredService<Sitecore.CES.GeoIp.Core.IGeoIpManager>().GetGeoIpData(...)
Sitecore.CES.GeoIp.Core.Lookups.LookupManager.GetWhoIsInformationByIp(...)

The GeoIPManager service

You use the public API the GeoIPManager service to retrieve GeoIP data for a given IP address:

RequestResponseshell

Sitecore.CES.GeoIp.Core.IGeoIpManager.GetGeoIpData(string ipAddress,TimeSpan? timeout = null)

Note

All configuration settings mentioned in this topic are in the <wwwroot>\App_Config\Sitecore\ DetectionServices.Location\ Sitecore.CES.GeoIp.config configuration file.

When you call the API for a given IP address, it checks for the existence of GeoIP data in this order:

The memory cache
The database
The geolocation service

When it finds a result, it does not check any further. The following sections explain in detail how it checks the various locations.

The memory cache

This is the first place the API searches for GeoIP data for the given IP address. Two configuration settings specify the size of this cache and how long the data for each IP address remains in the cache:

RequestResponseshell

<setting name="CES.GeoIp.Caching.GeoIpCacheExpiryTime" value="1:00:00:00"/>
<setting name="CES.GeoIp.Caching.GeoIpCacheSize" value="5MB"/>

The database

The VisitGeoIpData table stores the encrypted IP addresses and the associated GeoIP data. You can specify the following in the configuration:

GeoIP data lifetime: the default expiry date for records in the table is one year after insertion. You can specify another time in the <setting name="CES.GeoIp.Database.MaxEntryLifetime" value="365:00:00:00"> setting.
Database used: the default database used is Web, but you can can specify another in the <setting name="CES.GeoIp.ConnectionName" value="web"> setting. You can specify any database defined in the connectionstring.config file. The database must support read/write operations, and it must contain the VisitGeoIp table.
Clean up agent: the agent purges expired records when it is run. By default, it runs once a day. You can specify another frequency in the <agent type="Sitecore.CES.GeoIp.Core.Database.CleanupAgent, Sitecore.CES.GeoIp.Core" method="Run" interval="24:00:00" async="true" resolve="true"> configuration setting.

You can also configure active geo replication, where you use read-only replicated databases:

Specify the read-only database in the <setting name="CES.GeoIp.ConnectionName" value="read-only database name"> configuration setting.
Specify the writable database in the <setting name="CES.GeoIp.ConnectionName.Writable" value="writable database name "> configuration setting.

Both databases must contain the VisitGeoIpData table.

Note

Only specify CES.GeoIp.ConnectionName.Writable when you actually use active geo replication. If you do not, leave this value blank.

The geolocation service

The API uses the geolocation service as the last step if neither the memory cache nor the database has the data you ask for. When it receives a result for a given IP address, it stores this result in the database, and also adds it to the memory cache.

Using the GeoIPManagerService

The following example shows how you can use the Sitecore.CES.GeoIp.Core.IGeoIpManager API to resolve the country for a given IP address:

RequestResponsec#

using Microsoft.Extensions.DependencyInjection;
using Sitecore.CES.GeoIp.Core;
using Sitecore.CES.GeoIp.Core.Model;
using Sitecore.DependencyInjection;
public string GetCountryByIp(string ipAddress)
{
    try
    {
        var country = string.Empty;

            var geoIpManager = ServiceLocator.ServiceProvider.GetRequiredService<IGeoIpManager>();

            var geoIpFetchedData = geoIpManager.GetGeoIpData(ipAddress);

            if (geoIpFetchedData.Status == GeoIpFetchDataStatus.Fetched && geoIpFetchedData.WhoIsInformation != null)
            {
                country = geoIpFetchedData.WhoIsInformation.Country;
            }    
    }
    catch (Exception)
    {
        // Handle the exceptions
    }
    return country;
}

The GetGeoIpData method has an optional parameter called TimeSpan timeout. It specifies for how long the method waits to resolve data. If the method cannot retrieve the data within the specified time, the process returns an Unknown Ip Address with Timeout status, and continues in the background. This prevents the method from blocking the request if data resolving takes too long. If you do not pass this parameter to the method, it uses the value that is specified in the CES.GeoIp.LookupRequestTimeout. We recommend that you set timeout to no more than a few seconds, so that it does not add extra run time to page loading in case of any data resolving delays.

If you set the timeout to TimeSpan.Max, the method waits forever for the reponse from the service.

The API returns an object with Sitecore.CES.GeoIp.Core.Model.GeoIpFetchedData as the type. This object contains the status of the result of Sitecore.CES.GeoIp.Core.Model.GeoIpFetchDataStatus as well as the geo data result. The status value is one of the following:

Fetched: Successfully completed
Timeout: has not completed yet and returned due to timeout
Unknown: The IP address is unknown
Disabled: The API is disabled
Invalid: The IP address provided is invalid
Failed: The API has encounter error and failed

The GetWhoIsInformationByIp API

This API will be removed in a later version, but it is present for backwards compatibility for now. Internally, it calls the GeoIpManager service.