Honua.Sdk.GeoServices 1.12.0

Honua.Sdk.GeoServices

REST clients for the Honua FeatureServer (ArcGIS GeoServices-compatible) read, query, statistics, and apply-edits API, plus the GeoServices NAServer routing, service-area, and closest-facility client.

Part of the Honua .NET SDK — see the repo README for the full package catalog, browser/WASM support, authentication, and release policy.

Install

Stable releases are on nuget.org and install anonymously. An unversioned add resolves to the newest stable release (the current SDK version is in the repo README). Prereleases stay on the authenticated GitHub Packages feed; see INSTALL.md.

dotnet add package Honua.Sdk.GeoServices

Quick usage

using Honua.Sdk.GeoServices.Extensions;
using Honua.Sdk.GeoServices.FeatureServer;
using Honua.Sdk.GeoServices.FeatureServer.Models;
using Microsoft.Extensions.DependencyInjection;

var services = new ServiceCollection();
services.AddHonuaFeatureServer(o => o.BaseAddress = new Uri("https://your-honua-server"));
var provider = services.BuildServiceProvider();

var client = provider.GetRequiredService<IHonuaFeatureServerClient>();

await foreach (var page in client.QueryPagesAsync(
    "parcels",
    layerId: 0,
    new FeatureServerQueryParams
    {
        Where = "state = 'CO'",
        OutFields = "objectid,parcel_no,acres",
        ResultRecordCount = 1000,
        OutSR = 4326,
    },
    cancellationToken))
{
    Console.WriteLine($"Page with {page.Features?.Count ?? 0} features");
}

ArcGIS sources (import)

HonuaFeatureServerClient can also read an external ArcGIS service. Parse the service root URL: it may carry a path prefix (ArcGIS Online /<org>/arcgis/, a web adaptor's /arcgis/), folders (Utilities/Water), and FeatureServer or MapServer. Discovery, query, queryAttachments and attachment requests all resolve under that root.

using Honua.Sdk.GeoServices.FeatureServer;

var root = ArcGisServiceRoot.Parse(
    new Uri("https://gis.example.com/arcgis/rest/services/Utilities/Water/MapServer"));
var source = new HonuaFeatureServerClient(httpClient, root.ToClientOptions());

var layer = await source.GetLayerInfoAsync(root.ServiceId, 0, cancellationToken);
var attachments = await source.QueryAttachmentsAsync(root.ServiceId, 0, [1, 2, 3], cancellationToken);

The client reads JSON and error bodies up to HonuaFeatureServerClientOptions.MaxResponseBytes. The default is 64 MiB, the same limit honua-server's importer uses. A larger body throws HonuaFeatureServerResponseTooLargeException. When Content-Length declares a larger body, the client throws before reading any of it. Otherwise it stops reading at the limit.

For source inventories that must distinguish an omitted member from an explicit false or null, the concrete client also exposes GetServiceMetadataAsync and GetLayerMetadataAsync. These return unprojected JsonDocument instances through the same bounded, error-aware transport. The caller owns and must dispose each document; the HTTP response is disposed before the method returns. Typed metadata methods remain available for ordinary reads.

using var metadata = await source.GetLayerMetadataAsync(root.ServiceId, 0, cancellationToken);
var advertisedAttachments = metadata.RootElement.TryGetProperty("hasAttachments", out var value)
    ? value.Clone()
    : (System.Text.Json.JsonElement?)null;

Count-only queries require an explicit numeric count in the source response. QueryCountAsync throws HonuaFeatureServerException when the count is omitted or null, so an unavailable count is never reported as an empty source. An explicit zero remains zero.

Routing

using Honua.Sdk.Abstractions.Routing;
using Honua.Sdk.GeoServices.Routing;

services.AddHonuaRouting(o => o.BaseAddress = new Uri("https://your-honua-server"));

var router = provider.GetRequiredService<IHonuaRoutingClient>();
var route = await router.GetDirectionsAsync(
    new RouteDirectionsRequest
    {
        Origin = RoutingLocation.FromLatitudeLongitude(40.0150, -105.2705, "Boulder"),
        Destination = RoutingLocation.FromLatitudeLongitude(39.7392, -104.9903, "Denver"),
    },
    cancellationToken);

Raster (ImageServer)

AddHonuaImageServer registers the read-only ImageServer client plus the provider-neutral IHonuaRasterDataClient (raster metadata, coverage statistics, and a windowed/subset read). A raster geoprocessing tool can resolve IHonuaRasterDataClient from DI and read a clipped window of a large raster rather than transferring the whole dataset:

using Honua.Sdk.Abstractions.Data;
using Honua.Sdk.Abstractions.Features;
using Honua.Sdk.GeoServices.Extensions;

services.AddHonuaImageServer(o => o.BaseAddress = new Uri("https://your-honua-server"));

var raster = provider.GetRequiredService<IHonuaRasterDataClient>();

var metadata = await raster.GetRasterMetadataAsync(
    new RasterMetadataRequest { Source = new SpatialDataSource { ServiceId = "Elevation" } },
    cancellationToken);

// Read a clipped window (bbox extent sampled to a target pixel size) as GeoTIFF.
await using var window = await raster.ReadWindowAsync(
    new RasterWindowReadRequest
    {
        Source = new SpatialDataSource { ServiceId = "Elevation" },
        Extent = new FeatureBoundingBox { MinX = -158, MinY = 21, MaxX = -157, MaxY = 22, Crs = "4326" },
        Width = 512,
        Height = 512,
        Format = RasterWindowFormat.GeoTiff,
    },
    cancellationToken);

await using var file = File.Create("window.tif");
await window.Content.CopyToAsync(file, cancellationToken);

The umbrella Honua.Sdk package exposes this via the UseImageServer flag on AddHonua(...).

Raster output (write) stance

IHonuaRasterDataClient is read-only by design: it covers raster metadata, coverage statistics, and windowed reads. The Honua server does expose a raster write path — the admin multipart raster import endpoint (POST /api/v1/admin/import/raster, GeoTIFF / world-file upload into PostGIS) — but it lives on the privileged Admin surface and is not part of the raster-data read contract. A geoprocessing tool that produces a raster should write a GeoTIFF locally (for example from a ReadWindowAsync window or a computed result) and register it through that admin raster import endpoint.

The write half is exposed by Honua.Sdk.Admin via IHonuaAdminRasterImportClient (included in IHonuaAdminClient), completing the raster geoprocessing round-trip:

// Read half  (Honua.Sdk.GeoServices): IHonuaRasterDataClient.ReadWindowAsync(...)
// Write half (Honua.Sdk.Admin):
await using var tiff = File.OpenRead("output.tif");
var result = await adminClient.ImportRasterAsync(new RasterImportRequest
{
    Content = tiff,
    FileName = "output.tif",
    LayerId = 7,
    Name = "GP result",
    Srid = 4326,
});

var formats = await adminClient.GetSupportedRasterFormatsAsync();

Documentation

• Quickstart
• Authentication
• Troubleshooting
• Feature edits

License

Apache 2.0