Honua Python SDK

August 21, 2026 · View on GitHub

Python client libraries for Honua, the cloud-native geospatial platform built around honua-server. One typed client covers feature queries, geocoding, map/image export, editing, and server administration across the server's protocol adapters — GeoServices REST (FeatureServer/MapServer/ImageServer/GeocodeServer/GeometryServer), OGC API Features, STAC, OData, WFS/WMS/WMTS, and gRPC streaming — with one-call GeoDataFrame interop for the pandas/GeoPandas stack.

Packages

Two independently installable, Apache-2.0 packages live under packages/:

Package	Import	Description
`packages/honua-sdk`	`honua_sdk`	Data-plane client — feature queries, geocoding, protocol clients, gRPC streaming, GeoPandas/raster interop, `honua` CLI
`packages/honua-admin`	`honua_admin`	Control-plane client — services, connections, layers, styles, metadata, manifests, compatibility checks (depends on `honua-sdk`)

Also in this repo: packages/honua-gp, a proprietary geoprocessing compatibility layer for teams migrating scripts from ArcGIS arcpy (separate license, not published), and packages/honua-arcpy, a deprecated shim that re-exports it.

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.

Releases are automated with release-please and PyPI Trusted Publishing and ship to PyPI as honua-sdk and honua-admin. After release-please creates a package tag and GitHub Release, the publication workflow reconciles that exact release commit, publishes the SDK before the dependent admin package, and attaches the wheel and source distribution to the GitHub Release.

Install

Requires Python 3.11+ (CI tests 3.11, 3.12, 3.13). From PyPI:

pip install honua-sdk                             # data-plane client
pip install "honua-sdk[grpc,geopandas,raster]"    # + optional extras
pip install honua-admin                           # control-plane (admin) client

From source (always works, and the path for development):

git clone https://github.com/honua-io/honua-sdk-python.git
cd honua-sdk-python

# Data-plane client
pip install ./packages/honua-sdk

# With optional extras: gRPC streaming, GeoPandas vector interop,
# raster interop (rasterio / rioxarray / xarray)
pip install "./packages/honua-sdk[grpc,geopandas,raster]"

# Control-plane (admin) client — installs honua-sdk alongside it
pip install ./packages/honua-sdk ./packages/honua-admin

Or straight from GitHub without cloning, pinned to a release tag (replace with the newest python-sdk-v* tag):

pip install "honua-sdk[geopandas] @ git+https://github.com/honua-io/honua-sdk-python.git@python-sdk-v0.1.11#subdirectory=packages/honua-sdk"

The repo-root pyproject.toml is intentionally not installable (it holds shared tool config only) — install the per-package directories, not .. INSTALL.md has extras details and install-time troubleshooting.

I want to...

Goal	Start here
Query features in 5 minutes	docs/quickstart.md
Stream features over gRPC	INSTALL.md#with-grpc
Build an ETL pipeline	examples/geospatial_etl/
Wire a FastAPI service	examples/fastapi_spatial_service.py
Run spatial queries from Jupyter / pandas	docs/quickstart.md + examples/data_quality_report.py
Manage services & connections	packages/honua-admin/
Understand the protocol matrix	docs/protocol-parity.md
Diagnose an error	docs/quickstart.md#common-errors

Quick start

Query features through the canonical Source / Query / Result API and convert to a GeoDataFrame in one call:

from honua_sdk import HonuaClient, Query, SourceDescriptor, SourceLocator

with HonuaClient("https://your-honua-server.com") as client:
    source = client.source(
        SourceDescriptor(
            id="parcels",
            protocol="geoservices-feature-service",
            locator=SourceLocator(service_id="parcels", layer_id=0),
        )
    )
    result = source.query(Query(where="status = 'active'", 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
    print(gdf.head(), gdf.crs)

client.source(...) returns a source-bound facade with query(), query_all(), stream()/iter_features(), apply_edits(), and protocol(...). source.query() returns a canonical Result of normalized QueryFeature entries (id, properties, geometry, protocol, source, raw) — the same shape across FeatureServer, OGC API Features, STAC, and OData. The reverse helper honua_sdk.geopandas.geodataframe_to_features turns an edited GeoDataFrame back into apply_edits payloads.

OGC API Features

from honua_sdk import HonuaClient

with HonuaClient("https://your-honua-server.com") as client:
    ogc = client.ogc_features()
    collections = ogc.collections()

    parcels = ogc.collection("parcels")
    items = parcels.items(limit=100, filter="status = 'active'")
    feature = parcels.item("123")

Geocoding

from honua_sdk import HonuaGeocodingClient

with HonuaGeocodingClient("https://your-honua-server.com") as geocoder:
    results = geocoder.forward_geocode("1600 Pennsylvania Ave NW, Washington, DC")
    for r in results:
        print(f"{r.address}  ({r.latitude}, {r.longitude})  score={r.score}")

Async

Every HTTP workflow has an async counterpart with the same factory and method names — works with FastAPI, asyncio pipelines, and Jupyter:

from honua_sdk import AsyncHonuaClient, Query, SourceDescriptor, SourceLocator

async with AsyncHonuaClient("https://your-honua-server.com") as client:
    source = client.source(
        SourceDescriptor(
            id="parcels",
            protocol="geoservices-feature-service",
            locator=SourceLocator(service_id="parcels", layer_id=0),
        )
    )
    result = await source.query(Query(where="1=1"))

Admin client

from honua_admin import HonuaAdminClient

with HonuaAdminClient("https://your-honua-server.com", api_key="honua-api-key") as admin:
    compatibility = admin.check_compatibility()
    if not compatibility.supported:
        raise RuntimeError("; ".join(compatibility.reasons))

    features = admin.get_capability_flags()
    if features.manifest_apply:
        manifest = admin.get_manifest()
        print(f"Manifest resources: {len(manifest.resources)}")

Protocol IDs. Docs and examples use the canonical cross-SDK protocol ids (geoservices-feature-service, ogc-features, stac, odata, ...). Common aliases (feature-server, ogc-api-features, ...) are accepted at runtime and normalized by honua_sdk.normalize_protocol(...); the full table lives in honua_sdk.PROTOCOL_ALIASES. Compact helpers (client.query(...), client.query_features(...)) remain for one-liners — see Protocol Examples for every wrapper and Protocol Parity for the Python/JS coverage map.

Key features


Typed, canonical query surface	`Source` / `Query` / `Result` with normalized `QueryFeature` across FeatureServer, OGC Features, STAC, OData
Protocol clients	GeoServices (Feature/Map/Image/Geocode/Geometry/Scene/Elevation servers), OGC API Features/Maps/Tiles/Coverages/Processes/Records, STAC, OData, WFS, WMS, WMTS, geoprocessing + workflow wrappers — see protocol parity
GIS interop	`Result.to_geodataframe()`, `features_to_geodataframe` (Esri JSON aware), raster results via `rasterio`/`rioxarray` (`[raster]` extra)
gRPC streaming	`honua_sdk.grpc.HonuaGrpcClient` / `HonuaGrpcAsyncClient` for unary + streaming feature queries (`[grpc]` extra)
Sync + async	`HonuaClient` / `AsyncHonuaClient` in lockstep (sync clients generated from the async source of truth)
Automatic retry	429/502/503 with exponential backoff and `Retry-After` support; configurable via `max_retries`, `retry_methods`
Typed errors	`HonuaAuthError`, `HonuaRateLimitError`, `HonuaHttpError`, `HonuaTimeoutError`, `HonuaTransportError` — see common errors
CLI	`honua` (services / layers / style apply / sanitized `doctor` diagnostics) and `honua-migrate` (offline ArcPy script scan / translate / run, plus `.pyt` / `.atbx` toolbox and GP-service classification, with optional server-attested toolbox translation verdicts via `--server`)
Quality gates	mypy `strict` workspace-wide, 94% coverage gate, public-API compatibility snapshot, per-capability SDK coverage snapshot, live-server conformance lane against shared geospatial-grpc fixtures

Documentation

The rendered docs site lives at honua-io.github.io/honua-sdk-python (versioned MkDocs build of docs/). Platform-level docs are at honua.io and honua.gitbook.io/honuaio.

5-Minute Quickstart — query, GeoDataFrame, plot, common errors
Core Client — typed service, FeatureServer, applyEdits, pagination, error handling
Protocol Examples — OGC, STAC, WFS, WMS, WMTS, OData, geocoding, gRPC with response shapes
Authentication — refreshable bearer tokens, storage, rotation, failure modes
Pagination and retries & timeouts
Sanitized diagnostic bundles — the honua doctor bundle format
Geospatial ETL demo — script-first ETL flow with notebook companion
Compatibility — supported server matrix and public-API snapshot gate
SDK coverage — per-capability coverage snapshot gate
Troubleshooting — base URL, auth, staging smoke env vars, cleanup

Repo	What it is
honua-server	Flagship multi-protocol geospatial server this SDK talks to
honua-sdk-js	JavaScript/TypeScript SDKs + MCP server
honua-sdk-dotnet	.NET SDKs
honua-console	Unified web console (Studio, Catalog, Operate, Share)
honua-qgis-plugin	QGIS plugin (private preview; repo not yet public)
geospatial-grpc	Vendor-neutral gRPC protocol standard; source of this repo's conformance fixtures

Development

# Editable install of both packages with extras
pip install -e "packages/honua-sdk[grpc,geopandas]"
pip install -e "packages/honua-admin"
pip install pytest pytest-cov ruff mypy

# Lint + type-check (mypy runs in strict mode)
ruff check .
python -m mypy packages/honua-sdk/honua_sdk packages/honua-admin/honua_admin

# Deterministic local test suite
python3 -m pytest tests/ -q

# Public-API compatibility gate
python3 scripts/compatibility_gate.py

Sync clients (client.py, _client.py) are generated from their async counterparts — edit the async module and run python scripts/gen_sync.py; never hand-edit the generated files.

Opt-in integration lanes (staging smoke, live-server conformance, release smoke) need HONUA_BASE_URL and the --run-integration flag; see docs/troubleshooting.md and docs/compatibility.md for env vars, markers, and result artifacts.

Bugs and feature requests: GitHub issues. Pull requests are welcome — CI enforces lint, strict typing, the coverage gate, and the compatibility snapshot.

Security

Report vulnerabilities to security@honua.io — see the org security policy. Do not open public issues for security reports.

License

honua-sdk and honua-admin are licensed under Apache-2.0. packages/honua-gp and packages/honua-arcpy are proprietary (see their respective LICENSE files) and are not published.