# Svrnty.GeoManagement.Abstractions

Core abstractions and models for geocoding and address management services.

## Overview

This package provides the foundational interfaces and data structures for implementing geocoding providers. It defines the contract for geocoding operations without being tied to any specific provider implementation.

## Installation

```bash
dotnet add package Svrnty.GeoManagement.Abstractions
```

## Key Components

### IGeoManagementProvider Interface

The main interface for geocoding operations:

```csharp
public interface IGeoManagementProvider
{
    // Convert address to coordinates
    Task<GeoPoint?> GetGeoPointAsync(Address address, CancellationToken cancellationToken = default);

    // Convert coordinates to address
    Task<Address?> ReverseGeocodeAsync(GeoPoint geoPoint, CancellationToken cancellationToken = default);

    // Normalize and validate an address
    Task<Address?> NormalizeAddressAsync(Address address, CancellationToken cancellationToken = default);
    Task<Address?> NormalizeAddressAsync(string address, CancellationToken cancellationToken = default);
}
```

### Address Model

Represents a structured postal address:

```csharp
public record Address(
    string Line1,
    string? Line2,
    string City,
    string Subdivision,    // State/Province
    string PostalCode,
    string Country,
    GeoPoint? Location,
    string? Note,
    bool IsNormalized = false
);
```

Features:
- Formatted address output with `GetFormattedAddress()` method
- Support for multiple formats: Full, Compact, MultiLine
- Optional location coordinates
- Normalization tracking flag

### GeoPoint Model

Represents geographic coordinates:

```csharp
public record GeoPoint(double Latitude, double Longitude);
```

## Usage

This package is designed to be used with provider implementations. For example:

```csharp
using Svrnty.GeoManagement.Abstractions.Abstractions;
using Svrnty.GeoManagement.Abstractions.Models;

public class MyService
{
    private readonly IGeoManagementProvider _geoProvider;

    public MyService(IGeoManagementProvider geoProvider)
    {
        _geoProvider = geoProvider;
    }

    public async Task<GeoPoint?> GetCoordinates(Address address)
    {
        return await _geoProvider.GetGeoPointAsync(address);
    }
}
```

## Available Providers

- **[Svrnty.GeoManagement.Google](https://www.nuget.org/packages/Svrnty.GeoManagement.Google)** - Google Maps Geocoding API implementation

## Implementing a Provider

To create your own geocoding provider:

1. Reference this package
2. Implement `IGeoManagementProvider`
3. Map provider-specific responses to `Address` and `GeoPoint` models

```csharp
public class MyCustomProvider : IGeoManagementProvider
{
    public async Task<GeoPoint?> GetGeoPointAsync(Address address, CancellationToken cancellationToken = default)
    {
        // Your implementation
    }

    // ... implement other methods
}
```

## License

MIT License - see [LICENSE](https://git.openharbor.io/svrnty/dotnet-geo-management/blob/main/LICENSE) for details

## Links

- [Git Repository](https://git.openharbor.io/svrnty/dotnet-geo-management)
- [Google Provider Package](https://www.nuget.org/packages/Svrnty.GeoManagement.Google)