GeoIP .NET API

Starting in v5.4.0, MaxMind introduced the Anonymizer object to provide detailed insights into network anonymity.

Important Migration: The following properties on MaxMind.GeoIP2.Model.Traits are marked Obsolete and should be replaced by the Anonymizer object:

• IsAnonymous
• IsAnonymousVpn
• IsHostingProvider
• IsPublicProxy
• IsResidentialProxy
• IsTorExitNode

New Anonymizer Properties:

• Confidence: Score (1-99) representing percent confidence the network is an active VPN.
• IsAnonymous: Indicates if the IP belongs to an anonymous network.
• IsAnonymousVpn: True if registered to an anonymous VPN provider.
• IsHostingProvider: True if the IP belongs to a hosting or VPN provider.
• IsPublicProxy: True if the IP is a public proxy.
• IsResidentialProxy: True if the IP is on a suspected anonymizing network belonging to a residential ISP.
• IsTorExitNode: True if the IP is a Tor exit node.
• NetworkLastSeen: Last day the network was sighted (available on .NET 6.0+ as DateOnly).
• ProviderName: The name of the associated VPN provider.

The WebServiceClient is used to access MaxMind's web services.

Key usage patterns:

• Thread Safety: The object is safe to share across threads.
• Connection Reuse: You should reuse a single WebServiceClient instance for multiple requests to avoid creating new connections for every request.
• Lifecycle: You must dispose of the object when finished to ensure connections are closed and resources are returned to the system.
• Initialization: Create it with your Account ID and License Key. You can optionally specify a host, fall-back locales, or timeout.

Host Options:

• Default: Production GeoIP web service.
• geolite.info: Queries the GeoLite web service.
• sandbox.maxmind.com: Queries the Sandbox GeoIP web service.

// Standard usage
var client = new WebServiceClient(42, "license_key1");

// GeoLite usage
var client = new WebServiceClient(42, "license_key1", host: "geolite.info");

// Sandbox usage
var client = new WebServiceClient(42, "license_key1", host: "sandbox.maxmind.com");

To use the WebServiceClient with the HttpClient factory pattern as a Typed client in ASP.NET Core, follow these steps:

1. Update Program.cs to configure options from your configuration section and register the client for dependency injection:

builder.Services.Configure<WebServiceClientOptions>(builder.Configuration.GetSection("MaxMind"));
builder.Services.AddHttpClient<WebServiceClient>();

2. Update appsettings.json with your credentials and optional settings:

"MaxMind": {
  "AccountId": 123456,
  "LicenseKey": "1234567890",
  // "Timeout": 3000,
  // "Host": "geolite.info"
}

3. Inject and use the WebServiceClient in your controllers or services.

[ApiController]
[Route("[controller]")]
public class MaxMindController : ControllerBase
{
    private readonly WebServiceClient _maxMindClient;

    public MaxMindController(WebServiceClient maxMindClient)
    {
        _maxMindClient = maxMindClient;
    }

    [HttpGet]
    public async Task<string> Get()
    {
        var location = await _maxMindClient.CountryAsync();
        return location.Country.Name;
    }
}

Version 6.0 introduced significant breaking changes due to a shift in the underlying data model and deserialization logic. If you are upgrading from v5.x or earlier, you must address the following:

• Model Types: All model and response classes are now C# records instead of classes.
• Initialization: Constructor-based initialization is no longer supported. You must use object initializer syntax.
  • Old: new Traits(domain: "example.com")
  • New: new Traits { Domain = "example.com" }
• Immutability: Properties now use init setters. To modify a model, use the with expression pattern via the WithLocales() method instead of in-place mutation.
• ToString Behavior: The custom ToString() on NamedEntity subclasses (City, Country, etc.) has been removed. Use the .Name property directly to get the entity name.
• Memory Mapping: FileAccessMode.Memory and the DatabaseReader(Stream) constructor now use anonymous memory-mapped files. This removes the ~2.1 GiB size limit but may not work in environments like WASM, mobile/sandboxed runtimes, or hardened containers with restricted shared-memory syscalls.
• Nullability: TryXxx methods now use the [MaybeNullWhen(false)] attribute, allowing the compiler to understand that out parameters are non-null when the method returns true.

// Old syntax (v5.x and below)
var traits = new Traits("example.com");

// New syntax (v6.0+)
var traits = new Traits { Domain = "example.com" };