Mathias Beaulieu-Duncan
57c9aa6e00
Some checks failed
Publish NuGet Packages / build-and-publish (push) Failing after 41s
124 lines
3.2 KiB
Markdown
124 lines
3.2 KiB
Markdown
# 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)
|