Grid9 C# / .NET Implementation

The C# implementation of Grid9 provides a high-performance, production-ready coordinate compression library for .NET applications. With 227 comprehensive tests and optimized performance, it's ideal for enterprise applications, web services, and high-throughput systems.

                Key Features: Uniform 3-meter precision globally • 9-character codes • Human-readable formatting • Batch operations • Thread-safe • Zero-allocation hot paths
            

Installation

NuGet Package

# Install via Package Manager
Install-Package Grid9

# Install via .NET CLI
dotnet add package Grid9

# Install via PackageReference
<PackageReference Include="Grid9" Version="1.0.0" />

From Source

git clone https://github.com/pedrof69/Grid9.git
cd Grid9/csharp
dotnet build

Quick Start

Basic Usage

using OptimalCoordinateCompression;

// Encode coordinates to Grid9 code
string code = UniformPrecisionCoordinateCompressor.Encode(40.7128, -74.0060);
// Result: "Q7KH2BBYF"

// Decode Grid9 code to coordinates
var (latitude, longitude) = UniformPrecisionCoordinateCompressor.Decode("Q7KH2BBYF");
// Result: (40.712779, -74.005988)

// Human-readable format
string readable = UniformPrecisionCoordinateCompressor.Encode(40.7128, -74.0060, true);
// Result: "Q7K-H2B-BYF"

Distance Calculation

string nyc = UniformPrecisionCoordinateCompressor.Encode(40.7128, -74.0060);
string london = UniformPrecisionCoordinateCompressor.Encode(51.5074, -0.1278);

double distanceMeters = UniformPrecisionCoordinateCompressor.CalculateDistance(nyc, london);
// Result: 5,570,224 meters

Batch Operations

// High-performance batch encoding
var coordinates = new[] {
    (40.7128, -74.0060),  // NYC
    (51.5074, -0.1278),   // London
    (35.6762, 139.6503)   // Tokyo
};

string[] codes = CoordinateOperations.BatchEncode(coordinates);
// Results: ["Q7KH2BBYF", "S50MBZX2Y", "PAYMZ39T7"]

API Reference

UniformPrecisionCoordinateCompressor

Method	Description
`Encode(lat, lon)`	Encode coordinates to 9-character Grid9 code
`Encode(lat, lon, humanReadable)`	Encode with optional XXX-XXX-XXX formatting
`Decode(code)`	Decode Grid9 code to (latitude, longitude)
`CalculateDistance(code1, code2)`	Calculate distance between two codes in meters
`GetNeighbors(code)`	Get up to 8 neighboring Grid9 codes
`IsValidEncoding(code)`	Validate Grid9 code format
`GetActualPrecision(lat, lon)`	Get precision at specific coordinates

CoordinateOperations

Method	Description
`BatchEncode(coordinates)`	Encode multiple coordinates efficiently
`BatchDecode(codes)`	Decode multiple codes efficiently
`FindNearby(lat, lon, radius)`	Find codes within radius (meters)

Performance

Encoding Speed

6.4M+ operations/second

Decoding Speed

7.0M+ operations/second

Memory Usage

32 bytes per operation

Optimization Features

Aggressive inlining for hot paths
Zero-allocation encoding/decoding
Stack-allocated temporary arrays
Pre-computed lookup tables
Thread-safe operations

Advanced Features

Precision Information

var (xError, yError, totalError) = UniformPrecisionCoordinateCompressor
    .GetActualPrecision(40.7128, -74.0060);
// Result: (1.8m, 2.4m, 3.0m)

Neighboring Codes

string[] neighbors = UniformPrecisionCoordinateCompressor
    .GetNeighbors("Q7KH2BBYF");
// Returns up to 8 adjacent Grid9 codes

Validation

bool isValid = UniformPrecisionCoordinateCompressor
    .IsValidEncoding("Q7KH2BBYF");
// Result: true

bool isValidFormatted = UniformPrecisionCoordinateCompressor
    .IsValidEncoding("Q7K-H2B-BYF");
// Result: true

Requirements

.NET 8.0 or later
C# 12.0 language features
No external dependencies

Testing

# Run all tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

# Run specific test category
dotnet test --filter Category=Performance

Integration Examples

ASP.NET Core Web API

[ApiController]
[Route("api/[controller]")]
public class LocationController : ControllerBase
{
    [HttpPost("encode")]
    public IActionResult Encode([FromBody] CoordinateDto coords)
    {
        try
        {
            var code = UniformPrecisionCoordinateCompressor
                .Encode(coords.Latitude, coords.Longitude);
            return Ok(new { grid9Code = code });
        }
        catch (ArgumentOutOfRangeException ex)
        {
            return BadRequest(ex.Message);
        }
    }
}

Entity Framework Integration

public class Location
{
    public int Id { get; set; }
    public string Name { get; set; }
    public double Latitude { get; set; }
    public double Longitude { get; set; }
    
    // Computed property for Grid9 code
    public string Grid9Code => 
        UniformPrecisionCoordinateCompressor.Encode(Latitude, Longitude);
}

Need help? Check out the full source code and examples on GitHub or open an issue.

View on GitHub Back to Home