Try our conversational search powered by Generative AI!

Jun 18, 2018
(11 votes)

Geolocation provider changes

For quite some time Episerver CMS has come with built-in Geolocation support for MaxMind’s GeoLite database. When creating a site using the Episerver CMS Visual Studio Extension or the EPiServer.CMS NuGet package it would come with a recent version of this database included.

But as of late, MaxMind has announced that they are discontinuing the GeoLite database format effective January 2, 2019 and that the database will no longer be updated as of April 1, 2018.

As a replacement, MaxMind is instead offering the free GeoLite2 or the commercial GeoIP2 database which both comes with IPv6 support. These databases do however use a different format than the legacy GeoLite database that’s not compatible with the Geolocation provider included in the current version of Episerver CMS.

For a while, it has been possible to add support for GeoLite2 databases by replacing the built-in Geolocation provider with an excellent third-party provider available from the Episerver NuGet server, written by Khurram Khan, one of our brilliant MVPs.

With the GeoLite support officially coming to an end it no longer makes sense to continue providing the same default Geolocation support. We have therefore decided to make the following changes.

A new provider for GeoLite2 databases

A new separate NuGet package called EPiServer.Personalization.MaxMindGeolocation has been released. This package includes a Geolocation provider with support for MaxMind’s GeoLite2 database and it effectively works as a direct replacement for the provider from the PixieEPiServerExtensionMaxMindGeoIP2 package but with the added support from Episerver. This support is currently limited to usage with MaxMind’s free GeoLite2 City or Country databases, but the commercial GeoIP2 databases should also work although this has not been verified.

This provider needs to be installed separately as the EPiServer CMS package does not have a dependency to it. The Geolocation database can be downloaded from MaxMind’s website directly. To ensure that an updated list of locations is used, the provider also requires the matching CSV file which includes a list of all locations contained in the database. Make sure you specify the path of both the database and the locations file in your configuration such as:

<geolocation defaultProvider="maxmind2">
        <add name="maxmind2" 
             type="EPiServer.Personalization.MaxMindGeolocationProvider, EPiServer.Personalization.MaxMindGeolocation" 
             locationsFileName="path\to\GeoLite2-City-Locations-en.csv" />

The paths can be either relative to the website root or absolute.

You can alternatively configure the provider in the ConfigureContainer method of an initialization module that implements IConfigurableModule.

public void ConfigureContainer(ServiceConfigurationContext context)
    context.Services.AddMaxMindGeolocationProvider("path\to\geolite2-country.mmdb", "path\to\geolite2-country-locations-en.csv");

Note that the names of some regions have changed compared to the old GeoLite database, so if you are using the Geographic Location Visitor Group Criterion down to this level, you may have to update these with the new names.

Use geolocation provided by the CDN

We have also added support for retrieving Geolocation from the current request when provided from the CDN in the form of a header with a country code. Due to its nature, it's limited to Continent and Country location and will only be used for sites that don't have a Geolocation provider configured. This support will be turned on by default for all DXC customers. See Content Delivery Network (CDN) Configuration for additional information on how to enable this option.

Phasing out the old GeoLite provider

The old Geolocation provider currently included in the EPiServer.ApplicationModules assembly inside the EPiServer.Framework package will be obsoleted immediately and removed in a future major release. The EPiServer.CMS package will still contain the legacy GeoLite database for a while longer as removing it would remove it from existing solutions when updating the NuGet package. Once the provider has been fully deprecated, we will remove the database as well.

New sites created using the Episerver CMS Visual Studio Extension will be configured without a Geolocation provider going forward.

If you have any questions in relation to these changes, please comment below or send your question to our support team.

Jun 18, 2018


Stephan Lonntorp
Stephan Lonntorp Jun 19, 2018 11:10 AM

This is great!

But since Find isn't using JSON.NET > 11, and MaxMind.GeoIP2 3.0.0 requires >= 11.0.2, I can't use it. I'm guessing I'm not alone in this.

Ram Kumar K
Ram Kumar K Jun 19, 2018 10:53 PM

I've same issue with Find using older version of

henriknystrom Jun 19, 2018 11:56 PM

Thanks for the comments and sorry about your issues. An update to the Find packages with Json.NET 11 support is in the pipeline, so it should hopefully not be too long for you. I've reached out to the Find team to get a more presice timeline and will post it in another comment if I can.

Thanks for your patience!

Jun 20, 2018 08:11 AM

Have you tried using the ignore-dependency flag when installing Find ( We will update Find to support Json.Net 11 soon, but our tests shows that Find works with Json.Net 11.

Gautam Budidha
Gautam Budidha Aug 31, 2018 04:24 PM

I've run into the same issue. Find 13.0.1 can't use Json.Net 11, so I updated Json.Net while ignoring dependencies. However, when I try to install CsvHelper or Episerver.Personalization.MaxMindGeolocation, I still get a conflict:

Unable to find a version of 'WindowsAzure.Storage' that is compatible with 'EPiServer.Azure 9.4.4 constraint: WindowsAzure.Storage (>= 8.5.0 && < 9.0.0)'

I need Episerver.Azure for DXC, so simply removing it is not an option. Any ideas on where this dependency might be coming from? Ignoring dependencies at this rate is going to create an unstable app.

David McDonald
David McDonald Mar 18, 2019 07:36 PM

This new version says it requires license or attribution of the MaxMind, was that the case with the previous version of the Geolocation on Visitor Groups?


The GeoLite2 databases are distributed under the Creative Commons Attribution-ShareAlike 4.0 International License. The attribution requirement may be met by including the following in all advertising and documentation mentioning features of or use of this database:

This product includes GeoLite2 data created by MaxMind, available from
<a href=""></a>.

henriknystrom Mar 28, 2019 09:54 PM

Good question! Episerver had purchased a redistribution license for the Geolite (v1) database from MaxMind which was why we were able to include it with our package/installer. With GeoLite2 database however, this type of license was to my understanding not available. So we're therefore letting site owners make their own decision on which type of licensing they want to use.

Hope that answers your question.

Cuong Phan
Cuong Phan Aug 4, 2021 07:29 AM

The <geolocation> should be placed under <episerver.framework> tag for the new commers. 

Please login to comment.
Latest blogs
Join the Content Recommendations Work Smarter webinar May 8th 16.00-16.45 CET with expert Aidan Swain

Learn more about Content Recommendations, with Optimizely’s very own Senior Solutions consultant, Aidan Swain . He will discuss best practices and...

Karen McDougall | Apr 12, 2024

Plugin for Identifying and Bulk Deleting Orphaned Missing Properties in Optimizely

I am aware that the Optimizely World community has extensively discussed this topic, with numerous solutions and code snippets available to help...

Adnan Zameer | Apr 11, 2024 | Syndicated blog

Enhancing the Authoring Experience: Extending the LinkItem

The LinkItem field is one of the most demanded properties by the community, allowing editors to effortlessly create and manage links across pages a...

Santiago Morla | Apr 10, 2024 | Syndicated blog

The distinctions between Optimizely Web Experimentation and Optimizely Feature Experimentation

This blog is part of the series - Unlocking the Power of Experimentation: A Marketer's Insight. Let’s dive into Optimizely's powerful experimentati...

Holly Quilter | Apr 9, 2024

Optimizely SaaS CMS: Balancing TCO and ROI in Your CMS Hosting Decision

With Optimizely SaaS CMS coming soon, I’ve been talking with companies about the tricky business of picking the right core system software for thei...

Johnny Mullaney | Apr 8, 2024 | Syndicated blog

What version of Optimizely CMS am I running?

Optimizely continually rolls out new features for CMS customers and these features are normally for the latest major version of Optimizely CMS (CMS...

David Knipe | Apr 8, 2024 | Syndicated blog