👁 Image
mostlylucid.geodetection 7.5.5

Mostlylucid.GeoDetection

Geographic location detection and routing middleware for ASP.NET Core applications with multiple provider support.

Features

• Multiple Providers: ip-api.com (free, no account), MaxMind GeoLite2 (local database), or simple mock
• Country-Based Routing: Allow/block by country code with middleware and attributes
• Memory Caching: Fast in-memory caching enabled by default
• Optional Database Caching: SQLite/EF Core persistent cache (opt-in)
• Auto-Updates: Automatic MaxMind database downloads and updates

Installation

dotnet add package Mostlylucid.GeoDetection

Quick Start

Option 1: ip-api.com (Easiest - No Setup Required)

// Uses free ip-api.com API, no account needed
builder.Services.AddGeoRoutingWithIpApi();

app.UseGeoRouting();

Option 2: MaxMind GeoLite2 (Best for Production)

builder.Services.AddGeoRouting(
 configureProvider: options =>
 {
 options.Provider = GeoProvider.MaxMindLocal;
 options.AccountId = 123456; // Free account from maxmind.com
 options.LicenseKey = "your-license-key";
 }
);

app.UseGeoRouting();

Option 3: Simple Mock (Development/Testing)

builder.Services.AddGeoRoutingSimple();

Providers

Getting a MaxMind Account (Free)

1. Sign up at maxmind.com/en/geolite2/signup
2. Generate a license key in your account
3. Configure AccountId and LicenseKey
4. Database auto-downloads on startup

Configuration

appsettings.json

{
 "GeoLite2": {
 "Provider": "IpApi",
 "AccountId": null,
 "LicenseKey": null,
 "DatabasePath": "data/GeoLite2-City.mmdb",
 "EnableAutoUpdate": true,
 "CacheDuration": "01:00:00",
 "FallbackToSimple": true
 }
}

Provider Options

builder.Services.AddGeoRouting(
 configureRouting: options =>
 {
 options.Enabled = true;
 options.AllowedCountries = new[] { "US", "CA", "GB" };
 options.BlockedCountries = new[] { "XX" };
 options.AddCountryHeader = true; // Adds X-Country header
 options.StoreInContext = true; // Store in HttpContext.Items
 options.EnableTestMode = true; // Allow header override
 },
 configureProvider: options =>
 {
 options.Provider = GeoProvider.IpApi;
 options.CacheDuration = TimeSpan.FromHours(1);
 }
);

Database Caching (Optional)

By default, only memory caching is used. To persist lookups to a database:

// Add SQLite database cache (call BEFORE AddGeoRouting)
builder.Services.AddGeoCacheDatabase("Data Source=data/geocache.db");

builder.Services.AddGeoRouting(
 configureCache: options =>
 {
 options.Enabled = true;
 options.CacheExpiration = TimeSpan.FromDays(30);
 }
);

Use any EF Core provider by configuring DbContext yourself:

builder.Services.AddDbContext<GeoDbContext>(options =>
 options.UseSqlServer(connectionString));

Country-Based Routing

Endpoint Extensions

app.MapGet("/us-only", () => "US Only Content")
 .RequireCountry("US");

app.MapGet("/eu-content", () => "EU Content")
 .RequireCountry("DE", "FR", "IT", "ES", "NL", "BE");

app.MapGet("/blocked", () => "Not for XX")
 .BlockCountries("XX");

MVC Attributes

[GeoRoute(AllowedCountries = new[] { "US", "CA" })]
public class NorthAmericaController : Controller
{
 public IActionResult Index() => View();
}

[GeoRoute(BlockedCountries = new[] { "XX" })]
public IActionResult Restricted() => View();

Access Location Data

public class MyController : Controller
{
 private readonly IGeoLocationService _geoService;

 public MyController(IGeoLocationService geoService)
 {
 _geoService = geoService;
 }

 public async Task<IActionResult> Index()
 {
 var clientIp = HttpContext.Connection.RemoteIpAddress?.ToString();
 var location = await _geoService.GetLocationAsync(clientIp!);

 return Ok(new
 {
 location?.CountryCode,
 location?.CountryName,
 location?.City,
 location?.Latitude,
 location?.Longitude,
 location?.TimeZone,
 location?.IsVpn,
 location?.IsHosting
 });
 }
}

GeoLocation Model

public class GeoLocation
{
 public string CountryCode { get; set; } // "US", "GB", etc.
 public string CountryName { get; set; } // "United States"
 public string? ContinentCode { get; set; } // "NA", "EU", "AS"
 public string? RegionCode { get; set; } // State/region
 public string? City { get; set; }
 public double? Latitude { get; set; }
 public double? Longitude { get; set; }
 public string? TimeZone { get; set; } // "America/New_York"
 public bool IsVpn { get; set; } // Known VPN/proxy
 public bool IsHosting { get; set; } // Datacenter IP
}

Statistics

var stats = geoService.GetStatistics();
// stats.TotalLookups, stats.CacheHits, stats.DatabaseLoaded, etc.

Notes

• Supports reverse proxies (X-Forwarded-For, CF-Connecting-IP)
• Country codes follow ISO 3166-1 alpha-2 standard
• ip-api.com is rate limited to 45 requests/minute (free tier)
• MaxMind databases update weekly (auto-update enabled by default)
• Private/reserved IPs return "XX" country code

License

GNU AGPLv3

Links

• GitHub Repository
• MaxMind GeoLite2
• ip-api.com