Themia.Geo
0.63.0
See the version list below for details.
dotnet add package Themia.Geo --version 0.63.0
NuGet\Install-Package Themia.Geo -Version 0.63.0
<PackageReference Include="Themia.Geo" Version="0.63.0" />
<PackageVersion Include="Themia.Geo" Version="0.63.0" />
<PackageReference Include="Themia.Geo" />
paket add Themia.Geo --version 0.63.0
#r "nuget: Themia.Geo, 0.63.0"
#:package Themia.Geo@0.63.0
#addin nuget:?package=Themia.Geo&version=0.63.0
#tool nuget:?package=Themia.Geo&version=0.63.0
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 (onecos, onesqrt, noasin), 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 extraasinis 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
IPoiLookupabstraction. 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 Phraoagainst the commonly writtenLadprao; the abbreviation mark inจรัญฯ 13versusจรัญสนิทวงศ์ 13, which share only three characters; aNameEncolumn 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.ProviderLimitgives 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
GeoBoundsprefilter plus aGeoDistanceformula 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 | Versions 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. |
-
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 |