Retrieve geolocation data
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.
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:
-
On your Sitecore instance, browse the
App_Config\Sitecore\DetectionServices.Location\Sitecore.CES.GeoIP.config
configuration file to find the location of theCES.GeoIp.Caching.GeoIpCacheSize
setting. -
Create a patch file to change the
CES.GeoIp.Caching.GeoIpCacheSize
setting to the size of the cache you want to use.NoteFor more details on how to use this setting, refer to the description in the config file.