Themia.Geo 0.63.2

There is a newer version of this package available.
See the version list below for details.
dotnet add package Themia.Geo --version 0.63.2
                    
NuGet\Install-Package Themia.Geo -Version 0.63.2
                    
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Themia.Geo" Version="0.63.2" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Themia.Geo" Version="0.63.2" />
                    
Directory.Packages.props
<PackageReference Include="Themia.Geo" />
                    
Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package.
paket add Themia.Geo --version 0.63.2
                    
#r "nuget: Themia.Geo, 0.63.2"
                    
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
#:package Themia.Geo@0.63.2
                    
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package.
#addin nuget:?package=Themia.Geo&version=0.63.2
                    
Install as a Cake Addin
#tool nuget:?package=Themia.Geo&version=0.63.2
                    
Install as a Cake Tool

Themia.Geo

Neutral coordinate primitives: a validated lat/lng point (GeoPoint), two great-circle distance formulas (GeoDistance), and a metres-radius bounding box for SQL prefiltering (GeoBounds), plus the IGeocodingProvider contract that a separate package (e.g. Themia.Geo.Google) implements.

Pure computation: no HTTP, no credentials, no I/O, no database, no framework dependency. Targets net8.0 and net10.0.

No AddThemiaGeo

There is nothing in this package to register. GeoPoint, GeoDistance and GeoBounds are a struct and two static classes — there is no service, no configurable constant, and no state. IGeocodingProvider has no implementation here; a provider package registers itself (Themia.Geo.Google's AddThemiaGeoGoogle also registers IGeocodingProvider, so nothing upstream needs to). Adding a DI extension and an options type with no field anything reads would be ceremony, not a seam — see Themia.Storage for the same call on a package that is contracts plus one in-package implementation. If a second neutral concern ever needs configuring here, add AddThemiaGeo then, for that reason.

Distance: which formula, and neither is ellipsoid-corrected

var metres = GeoDistance.HaversineMetres(a, b);
var approx = GeoDistance.EquirectangularMetres(a, b);

Both treat the Earth as a sphere (the IUGG mean radius, 6,371,008.8 m). Neither corrects for the Earth's actual ellipsoid shape (WGS-84's ~0.3% flattening) — that is a deliberate simplification, not an oversight. It matters at global scale (a handful of kilometres of error over an antipodal distance) and does not matter for a metro-area radius filter, which is the whole intended use here. If a consumer ever needs ellipsoid-corrected distance (surveying, aviation-grade positioning), that is Vincenty's formula or a geodesy library — out of scope for this package.

Between the two:

  • EquirectangularMetres — a flat-projection approximation. Cheap (one cos, one sqrt, no asin), and accurate only over short distances — a few kilometres, which covers a metro-area radius filter under roughly 100 km. Use it when you are filtering rows against a fixed radius and the number itself is never shown to anyone.
  • HaversineMetres — accurate at any distance. Use it whenever the separation is unbounded, or whenever the computed distance is a number a user will see (a "3.2 km away" label) rather than only a yes/no filter — the extra asin is not worth trading accuracy for cents at that point.

Bounding boxes: the SQL prefilter, not the answer

var box = GeoBounds.AroundMetres(centre, metres: 5_000);
// WHERE latitude BETWEEN @swLat AND @neLat AND longitude BETWEEN @swLng AND @neLng

GeoBounds.AroundMetres sizes a box that fully contains a circle of the given radius — it is deliberately wider than the circle at the corners. Use it as an indexed range scan to narrow candidate rows before applying an exact GeoDistance formula to the survivors; do not treat "inside the box" as "inside the radius" on its own.

Deliberately not in this package

Each of these was considered and rejected for a stated reason, so a later reader does not helpfully re-add one as an obvious omission.

  • POI storage, a gazetteer, or any IPoiLookup abstraction. Proposed and rejected in coord #0115: the two consumer apps' POI stores do not share a shape (one fans a category across four tables, the other filters a single column), so a common interface would map cleanly onto neither.
  • Name matching, fuzzy search, and transliteration. Both consumers explicitly asked us not to ship this (coord #0115). These are Thai-language problems, not geometry, and they are unsolved on both sides today: RTGS Lat Phrao against the commonly written Ladprao; the abbreviation mark in จรัญฯ 13 versus จรัญสนิทวงศ์ 13, which share only three characters; a NameEn column holding transliteration for one row and translation for the next with nothing distinguishing them. A neutral package would get this wrong for both consumers, and the data each of those problems needs to solve correctly lives beside that consumer's own data, not in shared infrastructure.
  • API quota tracking. A monthly-budget counter is ~40 lines against one table for the one consumer that needs it. GeocodeOutcome.ProviderLimit gives that caller what it needs to stop; owning the budget itself is the caller's job, not a neutral package's.
  • Batch backfill orchestration ("find rows with no coordinate, geocode, write back"). The abstraction over which rows and what a row is would be larger than the ~80 lines of domain SQL it would replace.
  • PostGIS or a spatial index. Neither consumer runs PostGIS, and both operate over one metro area; a GeoBounds prefilter plus a GeoDistance formula is proportionate. Reconsider only if polygons at scale or nearest-neighbour ordering are actually needed.
  • GeoPolygon, point-in-polygon, or distance-to-boundary. Pure geometry with nothing domain-specific about it, and still rejected: neither consumer asked for it, and the one that has an equivalent (AreaBoundary) has it working today. "This could be shared" is not "someone needs it shared" — additive later, if either side asks.
  • Reverse geocoding. Nobody asked. Additive later.

IGeocodingProvider

public interface IGeocodingProvider
{
    Task<GeocodeResult> GeocodeAsync(string query, GeocodeOptions? options = null, CancellationToken cancellationToken = default);
}

GeocodeResult.Outcome distinguishes ProviderLimit (quota/rate-limited — stop, do not retry the batch) from ProviderError (transport failure or unexpected response — a retry may work). Collapsing the two removes the caller's ability to tell "keep going" from "back off" apart. There is deliberately no failover between providers here, unlike Themia.AI: geocoding runs in a background backfill that a caller can simply stop and resume, and the quota ProviderLimit protects is a monthly budget the caller owns, not a per-minute limit that clears in seconds.

Only one provider ships today: Themia.Geo.Google, whose AddThemiaGeoGoogle (Themia.Geo.Google.DependencyInjection) registers IGeocodingProvider and its own GoogleGeocodingOptions (the API key).

Product Compatible and additional computed target framework versions.
.NET net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed.  net9.0 was computed.  net9.0-android was computed.  net9.0-browser was computed.  net9.0-ios was computed.  net9.0-maccatalyst was computed.  net9.0-macos was computed.  net9.0-tvos was computed.  net9.0-windows was computed.  net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.
  • net10.0

    • No dependencies.
  • net8.0

    • No dependencies.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Themia.Geo:

Package Downloads
Themia.Geo.Google

Google Geocoding API provider for Themia.Geo's IGeocodingProvider. Maps Google's status field to GeocodeOutcome and suppresses IHttpClientFactory's default request-URI logging, because the API key travels as a query parameter with no header form.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.70.0 46 11/21/2026
0.69.0 50 11/18/2026
0.68.0 51 11/18/2026
0.67.2 51 11/18/2026
0.67.1 50 11/18/2026
0.67.0 55 11/17/2026
0.66.0 50 11/17/2026
0.65.0 108 11/16/2026
0.64.0 161 11/15/2026
0.63.2 112 11/15/2026
0.63.1 106 11/14/2026
0.63.0 108 11/14/2026
0.62.1 106 11/14/2026
0.62.0 113 11/14/2026
0.61.1 119 11/14/2026
0.61.0 109 11/13/2026
0.60.0 108 11/10/2026
0.59.0 104 11/10/2026
0.58.0 107 11/9/2026
0.57.2 112 11/8/2026
Loading failed