honua-sdk

Python client for Honua Server, the multi-protocol geospatial server behind Honua -- query geospatial features, geocode addresses, stream data over gRPC, and convert results to GeoDataFrames. Sync and async clients included.

Status: Alpha (0.x). APIs may change before 1.0. Breaking changes to the public API are gated by a compatibility snapshot and a per-capability SDK coverage snapshot.

See the monorepo README for the full documentation index, install matrix, and release notes.

Highlights

• Sync and async clients (HonuaClient, AsyncHonuaClient) with shared retry, refreshable-auth, and error-handling behavior.
• Source-bound facade (client.source(...)) returns normalized features across GeoServices FeatureServer, OGC API Features, STAC, and OData.
• Protocol wrappers for FeatureServer/MapServer/ImageServer/GeometryServer, SceneServer, ElevationServer, OGC Features/Maps/Tiles/Coverages/Processes/Records, STAC, WFS, WMS, WMTS, OData, and geocoding.
• Optional geopandas extra converts query responses to GeoDataFrames in one call via honua_sdk.geopandas; the raster extra adds raster result interop (rasterio / rioxarray / xarray).
• Optional grpc extra unlocks streaming feature queries through honua_sdk.grpc.HonuaGrpcClient / HonuaGrpcAsyncClient.
• Two CLIs ship with the package: honua (services / layers / style apply / sanitized doctor diagnostic bundles) and honua-migrate (offline ArcPy migration tooling: scan and translate ArcPy scripts, classify .pyt and .atbx toolboxes and geoprocessing services -- no arcpy install needed).

Install

pip install honua-sdk                   # core data-plane client
pip install "honua-sdk[geopandas]"      # + GeoDataFrame helpers
pip install "honua-sdk[grpc]"           # + streaming gRPC client
pip install "honua-sdk[raster]"         # + raster interop (rasterio/rioxarray/xarray)
pip install "honua-sdk[grpc,geopandas,raster]"  # everything

Requires Python 3.11+.

Install extras from the same package index and with the same version constraints as the core SDK. For a reproducible release, pin the same SDK version in each command; an older Git tag would replace the installed package with that version.

Minimal Example

The examples read the public, anonymous demo server at https://demo.honua.io and its maui-zoning FeatureServer (layer 2: zoning polygons with zone_code, zone_dist, cp_area and island). To use your own server, change the base URL, service and layer.

from honua_sdk import HonuaClient, Query, SourceDescriptor, SourceLocator

with HonuaClient("https://demo.honua.io") as client:
    source = client.source(
        SourceDescriptor(
            id="maui-zoning",
            protocol="geoservices-feature-service",
            locator=SourceLocator(service_id="maui-zoning", layer_id=2),
        )
    )
    result = source.query(Query(where="island = 'Maui'", out_fields=["*"]))
    print(f"Found {len(result.features)} features")
    for feature in result.features[:3]:
        print(feature.id, feature.properties)

    # Requires the [geopandas] extra
    gdf = result.to_geodataframe()  # GeoDataFrame with geometry column + CRS set

The same SourceDescriptor with a different protocol (ogc-features, stac, odata, ...) returns the same normalized Result shape.

Always use the with HonuaClient(...) as client: form -- it guarantees the underlying httpx connections are returned to the pool on exit, even when a request raises.

Async

import asyncio

from honua_sdk import AsyncHonuaClient, Query, SourceDescriptor, SourceLocator

async def main() -> None:
    async with AsyncHonuaClient("https://demo.honua.io") as client:
        source = client.source(
            SourceDescriptor(
                id="maui-zoning",
                protocol="geoservices-feature-service",
                locator=SourceLocator(service_id="maui-zoning", layer_id=2),
            )
        )
        result = await source.query(Query(where="island = 'Maui'", out_fields=["*"]))
        print(f"Found {len(result.features)} features")
        async for feature in source.stream(Query(where="zone_code = '929'")):  # parks
            print(feature.id, feature.properties)


asyncio.run(main())

Works with FastAPI, asyncio pipelines, Jupyter, and any other async framework. asyncio.run(main()) is for scripts; Jupyter and IPython already run an event loop, where asyncio.run raises RuntimeError, so call await main() in a notebook cell instead. Sync and async clients share identical method names, retry, and error-handling behavior.

Protocol IDs follow the canonical cross-SDK names (geoservices-feature-service, ogc-features, stac, odata, ...). Common aliases (feature-server, featureserver, ogc-api-features, ...) are accepted and normalized through honua_sdk.normalize_protocol(...).

Server capability baseline

This SDK requires a Honua Server that advertises these capabilities in its capability manifest:

• discovery.capability-manifest
• serve.geoservices-featureserver
• serve.ogc-api-features

All three ship in Honua Server's first published release, so that release is the minimum supported server (minimumServerVersion: first-release). The machine-readable declaration is release/sdk-capability-baseline.json; the Honua platform release reads it at the source revision this package was built from to decide which server versions this SDK is certified against.

Documentation

Rendered docs site: honua-io.github.io/honua-sdk-python. Platform docs: honua.io and honua.gitbook.io/honuaio.

• 5-Minute Quickstart
• Core Client
• Protocol Examples
• Authentication
• Geospatial ETL demo
• Troubleshooting
• Sanitized diagnostic bundles
• Monorepo README -- install matrix, package overview, and release notes

Related: honua-admin (control-plane client), honua-sdk-js (JS/TS SDKs + MCP server), honua-sdk-dotnet (.NET SDKs).

License

Apache-2.0