Why I Built a .NET Library for Sri Lanka’s Administrative Divisions

A few years ago, I was building an application that needed to work with Sri Lanka’s administrative structure — Provinces, Districts, Divisional Secretariats, and Grama Niladhari Divisions. What should have been a simple task turned into hours of digging through scattered government data. That experience never really left me. Recently, I turned it into an open-source .NET library: LankaLens.AdministrativeDivisions.

This article explains the problem, why I built this package, and how you can start using it in your own .NET projects.

Sri Lanka’s administrative hierarchy has five levels:

• Country (Sri Lanka)
  • Province
    • District
      • Divisional Secretariat (DS)
        • Grama Niladhari Division (GN)

If you’ve ever built an address form, a reporting tool, or any system that needs to reference Sri Lankan locations, you’ve probably run into the same issues I did:

• No single trusted source. Province and district names are easy to find, but Divisional Secretariat and Grama Niladhari data is scattered across government PDFs, old spreadsheets, and outdated websites.
• Inconsistent codes. Different sources label the same division with different codes, which makes joining data across systems painful.
• Sinhala and Tamil names are hard to verify. Many public datasets either skip local-language names entirely or auto-translate them, which is not reliable for official use.
• Everyone solves it alone. Every developer who needs this data ends up rebuilding the same lookup tables, from scratch, every time.

There simply wasn’t a reusable, well-structured .NET package for this. So I decided to build one.

Note: This isn’t a government-issued dataset. It’s an independent, open-source project built from publicly available official sources, and it’s not affiliated with or endorsed by the Government of Sri Lanka.

A few principles guided the design from day one:

• Offline-first. No database, no external API calls. The entire dataset is embedded in the package, so it works in any .NET application — web, desktop, or mobile — without extra infrastructure.
• Authoritative data, honestly labeled. Hierarchy and English names come from the Department of Census and Statistics, Sri Lanka. Sinhala and Tamil names come from the Ministry of Home Affairs, using verified LIFe Location Codes. Where a localized name isn’t verified yet, the library returns null instead of guessing — a null is never a translation failure, and it’s never a placeholder.
• Dependency-free at runtime. The package doesn’t pull in any third-party dependencies, keeping your project lightweight.
• Open-source, so it can be checked. Anyone can review the data sources, raise an issue, or contribute a correction. That kind of transparency matters a lot more for administrative data than for most other kinds of packages.

The goal is simple: if you’re building a .NET application that needs Sri Lankan location data, you shouldn’t have to solve this problem from scratch.

Here’s what the 1.0.0 stable release bundles:

• Licensed under MIT
• Targets .NET 8 (and works with .NET 9 and .NET 10 as well)
• Supports hierarchical navigation, code-based lookups, and multilingual search
• Thread-safe, read-only API — safe to use in concurrent applications
• 1.0.0 establishes the initial stable public API, so you can now depend on it without expecting breaking changes on every release

dotnet add package LankaLens.AdministrativeDivisions

dotnet add package LankaLens.AdministrativeDivisions

using LankaLens.AdministrativeDivisions;

var sriLanka = AdministrativeDivisions.Default;

foreach (var province in sriLanka.GetProvinces())
{
    Console.WriteLine(province.Name.English);
}

using LankaLens.AdministrativeDivisions;

var sriLanka = AdministrativeDivisions.Default;

foreach (var province in sriLanka.GetProvinces())
{
    Console.WriteLine(province.Name.English);
}

You can move down the hierarchy using a division’s code, or move back up to find a parent:

var districts = sriLanka.GetDistrictsByProvince("1"); // Western Province
var divisionalSecretariats = sriLanka.GetDivisionalSecretariatsByDistrict("11"); // Colombo
var gramaNiladhariDivisions = sriLanka.GetGramaNiladhariDivisionsByDivisionalSecretariat("1103");

// Navigate back up
var parentProvince = sriLanka.GetProvinceForDistrict("11");

var districts = sriLanka.GetDistrictsByProvince("1"); // Western Province
var divisionalSecretariats = sriLanka.GetDivisionalSecretariatsByDistrict("11"); // Colombo
var gramaNiladhariDivisions = sriLanka.GetGramaNiladhariDivisionsByDivisionalSecretariat("1103");

// Navigate back up
var parentProvince = sriLanka.GetProvinceForDistrict("11");

English names are always available. Sinhala and Tamil names may be null for a small number of Grama Niladhari records that haven’t been verified yet:

var province = sriLanka.GetProvinceByCode("1");

Console.WriteLine(province!.Name.English); // Western
Console.WriteLine(province.Name.Sinhala);  // බස්නාහිර
Console.WriteLine(province.Name.Tamil);    // மேற்கு

var province = sriLanka.GetProvinceByCode("1");

Console.WriteLine(province!.Name.English); // Western
Console.WriteLine(province.Name.Sinhala);  // බස්නාහිර
Console.WriteLine(province.Name.Tamil);    // மேற்கு

Search results are ranked by exact match, then prefix match, then contains match:

// Simple English search
var results = sriLanka.Search("Colombo");

// Language-specific search with options
var sinhalaResults = sriLanka.Search(
    "බස්නාහිර",
    new AdministrativeDivisionSearchOptions
    {
        Language = Language.Sinhala,
        Type = AdministrativeDivisionType.Province,
        MaxResults = 5
    });

// Simple English search
var results = sriLanka.Search("Colombo");

// Language-specific search with options
var sinhalaResults = sriLanka.Search(
    "බස්නාහිර",
    new AdministrativeDivisionSearchOptions
    {
        Language = Language.Sinhala,
        Type = AdministrativeDivisionType.Province,
        MaxResults = 5
    });

Note: English matching is case-insensitive. Sinhala and Tamil matching is ordinal, and language-specific searches don’t fall back to English — this keeps results predictable when you’re building multilingual UI.

LankaLens.AdministrativeDivisions 1.0.0 — the first stable release — is available now on NuGet:

dotnet add package LankaLens.AdministrativeDivisions

dotnet add package LankaLens.AdministrativeDivisions

• NuGet: LankaLens.AdministrativeDivisions
• GitHub: poorna-soysa/LankaLens

If you’re building a .NET application that needs Sri Lankan administrative division data, I hope this saves you the time it once cost me. Feedback, issues, and contributions are always welcome.

Working with Sri Lanka’s administrative hierarchy in .NET used to mean piecing together data from scattered government sources, dealing with inconsistent codes, and guessing at Sinhala and Tamil names. LankaLens.AdministrativeDivisions solves this by packaging the full Province → District → Divisional Secretariat → Grama Niladhari hierarchy into a single, offline, dependency-free .NET library — backed by authoritative sources and honest about what is and isn’t verified. With version 1.0.0, the library now has a stable, fixed public API, so it’s ready for production use in address forms, reporting dashboards, or any location-aware feature — without the need to solve the same problem from scratch.