honua-sdk › Clients

Two top-level clients share the same surface area and configuration model. Use HonuaClient for synchronous scripts, notebooks, and tools backed by httpx — and reach for AsyncHonuaClient in async services (FastAPI, asyncio workers) where you need concurrent I/O. Both clients expose the same canonical query/iter_query dispatcher and the same protocol-specific escape hatches; see Core client model for the conceptual map of options, retries, and with_options(...) semantics that apply to both.

The geocoding clients (HonuaGeocodingClient and AsyncHonuaGeocodingClient) are dedicated thin wrappers for the geocoding endpoint and keep the same configuration knobs.

from honua_sdk import HonuaClient

with HonuaClient("https://your-honua-server.com", timeout=30.0) as client:
    services = client.list_services()

See also: Source facade for the canonical query path, Core client model for with_options(...) semantics, and Retries and timeouts for the retry policy, Retry-After handling, and per-call / with_options(...) timeout behaviour.

honua_sdk.HonuaClient

Task-oriented synchronous client for common Honua data-plane workflows.

Wraps the Honua REST/HTTP surface (catalog, FeatureServer, OGC API Features, STAC, OData, WFS, WMS, WMTS, geocoding) and the canonical Source / Query / Result facade behind a single typed entrypoint.

Authentication is configured at construction with at most one of api_key, bearer_token, or auth_provider (mutually exclusive). bearer_token= is deprecated (removal in 0.2.x); prefer auth_provider=StaticAuthProvider({"Authorization": f"Bearer {token}"}). When client is supplied as a pre-built :class:httpx.Client, no auth kwargs may be passed — configure them on the client instead.

Retries: only idempotent methods (GET/HEAD/PUT/DELETE/OPTIONS) on transient statuses (429/502/503/504) are retried by default. Opt POST in by configuring retry_methods on the underlying retry transport; mutating helpers such as :meth:apply_edits then auto-generate Idempotency-Key headers.

Use as a context manager so the underlying transport closes deterministically::

with HonuaClient("https://example.com", api_key="...") as client:
    result = client.source(descriptor).query(Query(where="1=1"))

Per-call overrides (timeout, extra_headers, idempotency_key) are exposed on every method; use :meth:with_options for sticky per-clone overrides (shared transport unless base_url is supplied).

See also: :class:honua_sdk.source.Source and the Core Client guide at docs/core-client.md.

close()

Release underlying HTTP resources if this instance owns the client.

When the client was constructed with an externally supplied :class:httpx.Client, ownership stays with the caller and this method is a no-op.

with_options(*, timeout=None, max_retries=None, base_url=None)

Return a clone with overridden options.

When only timeout and/or max_retries are supplied, the returned client reuses the original's :class:httpx.Client and its connection pool — only the per-request timeout and (optionally) the per-request retry budget are overridden. In this transport-sharing mode the clone does not own the underlying client; calling :meth:close on the clone is a no-op. Only the original is responsible for closing the transport.

Passing base_url creates an independent client; the transport is NOT shared. Because the underlying :class:httpx.Client binds its base_url (and authority-bound timeouts, event hooks, and connection-pool keys) at construction time, swapping the base URL on a shared client would silently target the wrong host for any code path that relies on those bindings. To avoid that footgun, supplying base_url builds a fresh :class:httpx.Client for the clone and the clone owns it — you must clone.close() (or use with) independently of the original.

Parameters:

Name	Type	Description	Default
timeout	float | None	When set, overrides the per-request timeout. Smaller timeout values automatically build an independent client (with the smaller transport timeout); larger values reuse the parent's transport with a per-request httpx.Timeout(...) override.	None
max_retries	int | None	When set, overrides the retry budget. 0 disables retries on the clone via a per-request extension read by the retry transport.	None
base_url	str | None	When set, the returned clone is fully independent (owns its own :class:httpx.Client and connection pool) and must be closed separately. The transport is NOT shared with the original.	None

Returns:

Name	Type	Description
An	'HonuaClient'	class:HonuaClient — transport-sharing when the
	'HonuaClient'	override timeout is greater than or equal to the parent's
	'HonuaClient'	configured timeout, independently-owned when base_url is
	'HonuaClient'	supplied or when timeout is smaller than the parent's
	'HonuaClient'	configured timeout.

copy(*, timeout=None, max_retries=None, base_url=None)

Alias for :meth:with_options.

Provided for parity with the stripe-python convention, where both client.copy(...) and client.with_options(...) return a reconfigured clone. The semantics are identical to :meth:with_options; see that method for the full contract.

readiness(*, timeout=None, extra_headers=None)

Fetch the readiness payload from /healthz/ready.

Returns:

Type	Description
dict[str, Any]	The raw readiness JSON payload as a dict.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed before any response was received.

capabilities(*, timeout=None, extra_headers=None)

Discover server-advertised data-plane protocols and feature flags.

When the server does not expose /api/v1/capabilities (older deployments answer 404), this falls back to deriving a :class:DataPlaneCapabilities from readiness and the service catalog.

Returns:

Name	Type	Description
A	DataPlaneCapabilities	class:DataPlaneCapabilities describing protocol/feature
	DataPlaneCapabilities	availability.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request (and to the readiness/list_services fallback).

Raises:

Type	Description
HonuaHttpError	The server returned a non-404 error status.
HonuaTransportError	The request failed at the transport layer.

supports(capability, *, timeout=None, extra_headers=None)

Return whether the server advertises a given data-plane capability.

Parameters:

Name	Type	Description	Default
capability	str	Capability identifier (protocol slug such as "feature-server" or a feature flag name).	required

Returns:

Type	Description
bool	True when the server advertises the capability,
bool	False otherwise.

Raises:

Type	Description
HonuaHttpError	The underlying capability lookup failed server-side with a non-404 status.
HonuaTransportError	The capability lookup failed at the transport layer.

Per-request options (timeout / extra_headers) are forwarded to :meth:capabilities.

source(descriptor)

Return a source-bound facade for Source/Query/Result workflows.

Parameters:

Name	Type	Description	Default
descriptor	'SourceDescriptor | Mapping[str, Any]'	A :class:SourceDescriptor (or mapping convertible to one) identifying the dataset and protocol the facade should target.	required

Returns:

Name	Type	Description
An	'Source'	class:Source bound to this client's transport.

list_services(*, response_format='json', timeout=None, extra_headers=None)

List services from the GeoServices catalog endpoint.

Parameters:

Name	Type	Description	Default
response_format	str	Value passed as the f query parameter on /rest/services (defaults to "json").	'json'

Returns:

Type	Description
dict[str, Any]	The raw catalog payload as a dict.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

list_service_summaries(*, response_format='json', timeout=None, extra_headers=None)

List services as typed catalog summaries.

Parameters:

Name	Type	Description	Default
response_format	str	Value passed as the f query parameter on /rest/services (defaults to "json").	'json'

Returns:

Type	Description
list[ServiceSummary]	A list of :class:ServiceSummary objects; empty when the
list[ServiceSummary]	catalog payload does not contain a services list.

Per-request options (timeout / extra_headers) are forwarded to :meth:list_services.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

ogc_features()

Return an OGC API Features wrapper bound to this client.

Returns:

Name	Type	Description
An	'HonuaOgcFeatures'	class:HonuaOgcFeatures facade that reuses this
	'HonuaOgcFeatures'	client's HTTP session.

geocoder(locator='World')

Return a GeocodeServer wrapper that reuses this client's session.

Parameters:

Name	Type	Description	Default
locator	str	GeocodeServer locator name (defaults to "World").	'World'

Returns:

Name	Type	Description
An	'HonuaGeocodingClient'	class:HonuaGeocodingClient bound to locator.

feature_server(service_id)

Return a GeoServices FeatureServer wrapper for a service.

Parameters:

Name	Type	Description	Default
service_id	str	Service identifier as advertised by the catalog.	required

Returns:

Name	Type	Description
An	'GeoServicesFeatureServerClient'	class:GeoServicesFeatureServerClient bound to this
	'GeoServicesFeatureServerClient'	client's transport.

Raises:

Type	Description
HonuaHttpError	A subsequent request issued through the returned wrapper fails server-side (the factory itself does not perform I/O).

map_server(service_id)

Return a GeoServices MapServer wrapper for a service.

Parameters:

Name	Type	Description	Default
service_id	str	Service identifier as advertised by the catalog.	required

Returns:

Name	Type	Description
An	'GeoServicesMapServerClient'	class:GeoServicesMapServerClient bound to this
	'GeoServicesMapServerClient'	client's transport.

image_server(service_id=None)

Return a GeoServices ImageServer wrapper.

Parameters:

Name	Type	Description	Default
service_id	str | None	Optional service identifier; when None the wrapper targets the deployment-level ImageServer surface.	None

Returns:

Name	Type	Description
An	'GeoServicesImageServerClient'	class:GeoServicesImageServerClient bound to this
	'GeoServicesImageServerClient'	client.

geometry_server()

Return the GeoServices GeometryServer wrapper.

Returns:

Name	Type	Description
An	'GeoServicesGeometryServerClient'	class:GeoServicesGeometryServerClient bound to
	'GeoServicesGeometryServerClient'	this client's transport.

ogc_maps()

Return an OGC API Maps wrapper.

Returns:

Name	Type	Description
An	'OgcMapsClient'	class:OgcMapsClient bound to this client's
	'OgcMapsClient'	transport.

ogc_tiles()

Return an OGC API Tiles wrapper.

Returns:

Name	Type	Description
An	'OgcTilesClient'	class:OgcTilesClient bound to this client's
	'OgcTilesClient'	transport.

ogc_coverages()

Return an OGC API Coverages wrapper.

Returns:

Name	Type	Description
An	'OgcCoveragesClient'	class:OgcCoveragesClient bound to this client's
	'OgcCoveragesClient'	transport.

ogc_processes()

Return an OGC API Processes wrapper.

Returns:

Name	Type	Description
An	'OgcProcessesClient'	class:OgcProcessesClient bound to this client's
	'OgcProcessesClient'	transport.

ogc_records()

Return an OGC API Records wrapper.

geoprocessing()

Return a geoprocessing (OGC API Processes) client.

Returns:

Name	Type	Description
An	'HonuaGeoprocessing'	class:~honua_sdk.geoprocessing.HonuaGeoprocessing bound
	'HonuaGeoprocessing'	to this client's transport for listing/describing processes and
	'HonuaGeoprocessing'	submitting + polling + fetching the results of process executions.

workflow()

Return a workflow package authoring + publication client.

Returns:

Name	Type	Description
An	'HonuaWorkflow'	class:~honua_sdk.workflow.HonuaWorkflow bound to this
	'HonuaWorkflow'	client's transport for authoring workflow package drafts,
	'HonuaWorkflow'	snapshotting immutable versions, validating / dry-running /
	'HonuaWorkflow'	publishing them, and running publications over the server's
	'HonuaWorkflow'	/api/v1/console workflow package surface (the durable
	'HonuaWorkflow'	replacement for the dropped GeoETL pipeline endpoints; admin
	'HonuaWorkflow'	authorization required server-side).

stac()

Return a STAC API wrapper.

Returns:

Name	Type	Description
An	'StacClient'	class:StacClient bound to this client's transport.

scenes()

Return a 3D scene metadata + resolution wrapper.

Returns:

Name	Type	Description
An	'SceneClient'	class:SceneClient bound to this client's transport.

elevation()

Return an elevation HTTP API wrapper.

Returns:

Name	Type	Description
An	'ElevationClient'	class:ElevationClient bound to this client's transport.

wfs()

Return a WFS 2.0 wrapper.

Returns:

Name	Type	Description
An	'WfsClient'	class:WfsClient bound to this client's transport.

wms(service_id)

Return a service-scoped WMS wrapper.

Parameters:

Name	Type	Description	Default
service_id	str	Service identifier as advertised by the catalog.	required

Returns:

Name	Type	Description
An	'WmsClient'	class:WmsClient bound to this client's transport.

wmts(service_id)

Return a service-scoped WMTS wrapper.

Parameters:

Name	Type	Description	Default
service_id	str	Service identifier as advertised by the catalog.	required

Returns:

Name	Type	Description
An	'WmtsClient'	class:WmtsClient bound to this client's transport.

odata()

Return an OData v4 wrapper.

Returns:

Name	Type	Description
An	'ODataClient'	class:ODataClient bound to this client's transport.

grpc(*, target=None, insecure=None, credentials=None, timeout=30.0, extra_metadata=None)

Return a gRPC FeatureService client bound to this client's config.

Builds an :class:HonuaGrpcClient (the analytic gRPC surface: unary + streaming QueryFeatures with server-side spatial filters, statistics, and aggregation) from the same base URL and authentication this client was constructed with — so the gRPC surface is reachable in the same token-scoped harness without re-plumbing a channel.

The dial target defaults to the REST base_url's host:port (the Honua gRPC service shares the REST authority). Authentication is carried as gRPC call metadata derived from the client's api_key / bearer_token / auth_provider via :func:honua_sdk.grpc.build_grpc_metadata. Transport security defaults to TLS for an https base URL and plaintext otherwise; override with credentials= (a :class:grpc.ChannelCredentials) or insecure=True.

Parameters:

Name	Type	Description	Default
target	str | None	Explicit host:port gRPC dial target. Defaults to the REST base URL's authority.	None
insecure	bool | None	Force a plaintext channel. Defaults to True for a non-https base URL, False otherwise.	None
credentials	Any	Explicit channel credentials. Defaults to :func:grpc.ssl_channel_credentials for a secure channel.	None
timeout	float | None	Per-call gRPC timeout in seconds.	30.0
extra_metadata	Mapping[str, str] | None	Additional metadata entries merged onto the auth-derived metadata.	None

Returns:

Name	Type	Description
An	'HonuaGrpcClient'	class:HonuaGrpcClient ready to issue feature queries.

Raises:

Type	Description
ValueError	The client base_url has no host to derive a target from.

query(source, *, protocol=None, layer_id=None, where=None, filter=None, bbox=None, spatial_filter=None, fields=None, return_geometry=None, out_statistics=None, group_by=None, return_distinct_values=None, return_count_only=None, page_size=None, limit=None, max_pages=100, extra_params=None, timeout=None, extra_headers=None, idempotency_key=None)

Run a protocol-neutral feature query and collect normalized features.

Parameters:

Name	Type	Description	Default
source	str | FeatureQuery	Either a source identifier (service name, OGC collection id, STAC collection id, OData entity set) or a pre-built :class:FeatureQuery. When a query object is provided the remaining keyword arguments are ignored.	required
protocol	QueryProtocol | None	Override the protocol resolved from source.	None
layer_id	int | None	FeatureServer layer index or OData layer id when the protocol requires one.	None
where	str | None	GeoServices-style WHERE clause (FeatureServer only).	None
filter	str | None	CQL2/OData filter expression (OGC Features / STAC / OData).	None
bbox	str | Sequence[int | float] | None	Spatial filter as a list/tuple of coordinates or comma string. Not supported when protocol is OData.	None
spatial_filter	Mapping[str, Any] | None	Arbitrary-geometry spatial filter (FeatureServer only): a mapping of geometry (Esri JSON / GeoJSON / __geo_interface__), relationship (intersects, within, contains, crosses, touches, overlaps, within-distance), optional in_sr and distance/units. Translated to the GeoServices geometry/geometryType/spatialRel/inSR params.	None
fields	str | Sequence[str] | None	Attribute selection; comma-string or sequence of names.	None
return_geometry	bool | None	Whether to include geometry (FeatureServer).	None
out_statistics	Sequence[Mapping[str, Any]] | None	Server-side statistic definitions (FeatureServer): a sequence of mappings with statistic_type (count, sum, min, max, avg, stddev, var), on_statistic_field, and optional out_statistic_field_name.	None
group_by	str | Sequence[str] | None	Group-by fields paired with out_statistics.	None
return_distinct_values	bool | None	Request distinct rows (FeatureServer).	None
return_count_only	bool | None	Request only the matching count (FeatureServer).	None
page_size	int | None	Page size hint for paginated protocols.	None
limit	int | None	Maximum number of features to collect across all pages.	None
max_pages	int | None	Safety cap on pages walked; defaults to 100. Pass None for an unbounded walk (FeatureServer) — a ResourceWarning is emitted if a bounded walk stops with more features still available on the server.	100
extra_params	Mapping[str, Any] | None	Additional protocol-specific query parameters merged into each request.	None
timeout	float | Timeout | None	Per-call timeout override forwarded to every page request across all protocols (FeatureServer, OGC Features, STAC, OData). Accepts a float seconds value or an :class:httpx.Timeout.	None
idempotency_key	str | None	Stripe-style Idempotency-Key header value attached to every page request. Merged into extra_headers before forwarding.	None
extra_headers	Mapping[str, str] | None	Additional HTTP headers merged into every page request across all protocols.	None

Returns:

Name	Type	Description
A	FeatureQueryResult	class:FeatureQueryResult containing the normalized
	FeatureQueryResult	features, resolved protocol, source, and the effective query.

Raises:

Type	Description
ValueError	bbox is supplied for the OData protocol.
HonuaHttpError	A page request returned a non-success status.
HonuaTransportError	A page request failed at the transport layer.

iter_query(source, *, protocol=None, layer_id=None, where=None, filter=None, bbox=None, spatial_filter=None, fields=None, return_geometry=None, page_size=None, limit=None, max_pages=100, extra_params=None, timeout=None, extra_headers=None, idempotency_key=None)

Stream normalized features from FeatureServer, OGC Features, STAC, or OData.

This is the streaming counterpart to :meth:query — features are yielded one at a time so callers can short-circuit large result sets.

Parameters:

Name	Type	Description	Default
source	str | FeatureQuery	Source identifier or pre-built :class:FeatureQuery. When a query object is provided the remaining keyword arguments are ignored.	required
protocol	QueryProtocol | None	Override the protocol resolved from source.	None
layer_id	int | None	FeatureServer layer index or OData layer id when the protocol requires one.	None
where	str | None	GeoServices-style WHERE clause (FeatureServer only).	None
filter	str | None	CQL2/OData filter expression for OGC/STAC/OData.	None
bbox	str | Sequence[int | float] | None	Spatial filter; not supported for OData.	None
spatial_filter	Mapping[str, Any] | None	Arbitrary-geometry spatial filter (FeatureServer); see :meth:query for the mapping shape.	None
fields	str | Sequence[str] | None	Attribute selection.	None
return_geometry	bool | None	Whether to include geometry (FeatureServer).	None
page_size	int | None	Page size hint for paginated protocols.	None
limit	int | None	Maximum number of features to yield across all pages.	None
max_pages	int | None	Safety cap on pages walked; defaults to 100. Pass None for an unbounded walk (FeatureServer).	100
extra_params	Mapping[str, Any] | None	Protocol-specific query parameters merged into each request.	None

Per-call timeout / extra_headers are forwarded to every protocol's pagination wrapper (FeatureServer, OGC Features, STAC, OData). idempotency_key is merged into extra_headers before forwarding.

Yields:

Name	Type	Description
Normalized	QueryFeature	class:QueryFeature objects.

Raises:

Type	Description
ValueError	bbox is supplied for the OData protocol.
HonuaHttpError	A page request returned a non-success status.
HonuaTransportError	A page request failed at the transport layer.

query_features(service_id, layer_id, *, where='1=1', out_fields='*', return_geometry=True, extra_params=None, timeout=None, extra_headers=None)

Query features from a FeatureServer layer and return raw JSON.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
where	str	GeoServices WHERE clause; defaults to "1=1".	'1=1'
out_fields	str | Sequence[str]	Field selection; either a comma-string or sequence of names. Defaults to "*".	'*'
return_geometry	bool	Whether the server should include geometry.	True
extra_params	Mapping[str, Any] | None	Additional query-string parameters merged into the request (e.g. resultOffset, resultRecordCount).	None

Returns:

Type	Description
dict[str, Any]	The raw FeatureServer query response as a dict.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

query_feature_set(service_id, layer_id, *, where='1=1', out_fields='*', return_geometry=True, extra_params=None, timeout=None, extra_headers=None)

Query a FeatureServer layer and return a typed :class:FeatureSet.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
where	str	GeoServices WHERE clause; defaults to "1=1".	'1=1'
out_fields	str | Sequence[str]	Field selection; either a comma-string or sequence of names. Defaults to "*".	'*'
return_geometry	bool	Whether the server should include geometry.	True
extra_params	Mapping[str, Any] | None	Additional query-string parameters merged into the request (e.g. resultOffset, resultRecordCount).	None

Returns:

Name	Type	Description
A	FeatureSet	class:FeatureSet parsed from the raw query response.

Per-request options (timeout / extra_headers) are forwarded to :meth:query_features.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

query_features_all(service_id, layer_id, *, where='1=1', out_fields='*', return_geometry=True, page_size=1000, limit=None, max_pages=100, extra_params=None, timeout=None, extra_headers=None)

Page through FeatureServer query results and return typed features.

Walks the FeatureServer query endpoint with resultOffset / resultRecordCount until either limit is reached, the server stops indicating that the transfer limit was exceeded, or max_pages is hit.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
where	str	GeoServices WHERE clause; defaults to "1=1".	'1=1'
out_fields	str | Sequence[str]	Field selection; comma-string or sequence of names.	'*'
return_geometry	bool	Whether the server should include geometry.	True
page_size	int	Page size hint forwarded as resultRecordCount. Must be greater than zero.	1000
limit	int | None	Optional cap on the total number of features returned.	None
max_pages	int	Safety cap on the number of pages walked. Must be greater than zero.	100
extra_params	Mapping[str, Any] | None	Additional query parameters. Any resultOffset value is honored as the starting offset.	None

Returns:

Type	Description
list[Feature]	A list of typed :class:Feature objects up to limit.

Per-request options (timeout / extra_headers) are forwarded to every page-level :meth:query_feature_set call.

Raises:

Type	Description
ValueError	page_size or max_pages is not positive.
HonuaHttpError	A page request returned a non-success status.
HonuaTransportError	A page request failed at the transport layer.

apply_edits(service_id, layer_id, *, adds=None, updates=None, deletes=None, rollback_on_failure=True, idempotency_key=None, timeout=None, extra_headers=None)

Submit a layer-level GeoServices applyEdits request.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
adds	Sequence[Mapping[str, Any]] | None	Sequence of feature mappings to insert.	None
updates	Sequence[Mapping[str, Any]] | None	Sequence of feature mappings to update by OBJECTID.	None
deletes	Sequence[int] | str | None	Either a sequence of object ids or a comma-string of ids to delete.	None
rollback_on_failure	bool	Whether the server should roll the entire batch back if any individual edit fails.	True
idempotency_key	str | None	Stripe-style Idempotency-Key header value. When None and the underlying retry transport is configured to retry POST (i.e. the caller opted in via retry_methods), a fresh uuid4 hex is generated so that retries are de-duplicated server-side. Pass an explicit value to make the request idempotent across application retries as well.	None

Returns:

Type	Description
dict[str, Any]	The raw applyEdits response payload as a dict.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

apply_edits_result(service_id, layer_id, *, adds=None, updates=None, deletes=None, rollback_on_failure=True, idempotency_key=None, timeout=None, extra_headers=None)

Submit applyEdits and return typed per-operation results.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
adds	Sequence[Mapping[str, Any]] | None	Sequence of feature mappings to insert.	None
updates	Sequence[Mapping[str, Any]] | None	Sequence of feature mappings to update by OBJECTID.	None
deletes	Sequence[int] | str | None	Either a sequence of object ids or a comma-string of ids to delete.	None
rollback_on_failure	bool	Whether the server should roll the entire batch back if any individual edit fails.	True
idempotency_key	str | None	Stripe-style Idempotency-Key header value; forwarded to :meth:apply_edits. See that method for auto-generation semantics.	None

Returns:

Name	Type	Description
An	ApplyEditsResult	class:ApplyEditsResult parsed from the response.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:apply_edits.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

export_map(service_id, bbox, *, size=(400, 400), image_format='png', transparent=True, dpi=96, extra_params=None, timeout=None, extra_headers=None)

Request rendered map bytes from the MapServer export endpoint.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
bbox	Sequence[float] | str	Bounding box as a sequence of floats (xmin, ymin, xmax, ymax) or pre-formatted comma string.	required
size	tuple[int, int]	(width, height) in pixels; defaults to (400, 400).	(400, 400)
image_format	str	Output image format ("png", "jpg", ...).	'png'
transparent	bool	Whether the rendered image should be transparent where there is no data.	True
dpi	int	Output DPI value forwarded to the server.	96
extra_params	Mapping[str, Any] | None	Additional query parameters merged into the request (e.g. layers, layerDefs).	None

Returns:

Type	Description
bytes	The raw image bytes returned by the server.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

honua_sdk.AsyncHonuaClient

Task-oriented asynchronous client for common Honua data-plane workflows.

Async counterpart to :class:honua_sdk.HonuaClient: wraps the Honua REST/HTTP surface (catalog, FeatureServer, OGC API Features, STAC, OData, WFS, WMS, WMTS, geocoding) and the canonical Source / Query / Result facade behind a single typed entrypoint.

Authentication is configured at construction with at most one of api_key, bearer_token, or auth_provider (mutually exclusive). bearer_token= is deprecated (removal in 0.2.x); prefer auth_provider=StaticAuthProvider({"Authorization": f"Bearer {token}"}). When client is supplied as a pre-built :class:httpx.AsyncClient, no auth kwargs may be passed — configure them on the client instead.

Retries: only idempotent methods (GET/HEAD/PUT/DELETE/OPTIONS) on transient statuses (429/502/503/504) are retried by default. Opt POST in by configuring retry_methods on the underlying retry transport; mutating helpers such as :meth:apply_edits then auto-generate Idempotency-Key headers.

Use as an async context manager so the underlying transport closes deterministically::

async with AsyncHonuaClient("https://example.com", api_key="...") as client:
    result = await client.source(descriptor).query(Query(where="1=1"))

Per-call overrides (timeout, extra_headers, idempotency_key) are exposed on every method; use :meth:with_options for sticky per-clone overrides (shared transport unless base_url is supplied).

See also: :class:honua_sdk.source.Source and the Core Client guide at docs/core-client.md.

close() async

Release underlying HTTP resources if this instance owns the client.

When the client was constructed with an externally supplied :class:httpx.AsyncClient, ownership stays with the caller and this coroutine is a no-op.

with_options(*, timeout=None, max_retries=None, base_url=None)

Return a clone with overridden options.

When only timeout and/or max_retries are supplied, the returned client reuses the original's :class:httpx.AsyncClient and its connection pool — only the per-request timeout and (optionally) the per-request retry budget are overridden. In this transport-sharing mode the clone does not own the underlying client; awaiting :meth:close on the clone is a no-op. Only the original is responsible for closing the transport.

Passing base_url creates an independent client; the transport is NOT shared. Because the underlying :class:httpx.AsyncClient binds its base_url (and authority-bound timeouts, event hooks, and connection-pool keys) at construction time, swapping the base URL on a shared client would silently target the wrong host for any code path that relies on those bindings. To avoid that footgun, supplying base_url builds a fresh :class:httpx.AsyncClient for the clone and the clone owns it — you must await clone.close() (or use async with) independently of the original.

Parameters:

Name	Type	Description	Default
timeout	float | None	When set, overrides the per-request timeout. Smaller timeout values automatically build an independent client (with the smaller transport timeout); larger values reuse the parent's transport with a per-request httpx.Timeout(...) override.	None
max_retries	int | None	When set, overrides the retry budget. 0 disables retries on the clone via a per-request extension read by the retry transport.	None
base_url	str | None	When set, the returned clone is fully independent (owns its own :class:httpx.AsyncClient and connection pool) and must be closed separately. The transport is NOT shared with the original.	None

Returns:

Name	Type	Description
An	'AsyncHonuaClient'	class:AsyncHonuaClient — transport-sharing when the
	'AsyncHonuaClient'	override timeout is greater than or equal to the parent's
	'AsyncHonuaClient'	configured timeout, independently-owned when base_url is
	'AsyncHonuaClient'	supplied or when timeout is smaller than the parent's
	'AsyncHonuaClient'	configured timeout.

copy(*, timeout=None, max_retries=None, base_url=None)

Alias for :meth:with_options.

Provided for parity with the stripe-python convention, where both client.copy(...) and client.with_options(...) return a reconfigured clone. The semantics are identical to :meth:with_options; see that method for the full contract.

readiness(*, timeout=None, extra_headers=None) async

Fetch the readiness payload from /healthz/ready.

Returns:

Type	Description
dict[str, Any]	The raw readiness JSON payload as a dict.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed before any response was received.

capabilities(*, timeout=None, extra_headers=None) async

Discover server-advertised data-plane protocols and feature flags.

When the server does not expose /api/v1/capabilities (older deployments answer 404), this falls back to deriving a :class:DataPlaneCapabilities from readiness and the service catalog.

Returns:

Name	Type	Description
A	DataPlaneCapabilities	class:DataPlaneCapabilities describing protocol/feature
	DataPlaneCapabilities	availability.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request (and to the readiness/list_services fallback).

Raises:

Type	Description
HonuaHttpError	The server returned a non-404 error status.
HonuaTransportError	The request failed at the transport layer.

supports(capability, *, timeout=None, extra_headers=None) async

Return whether the server advertises a given data-plane capability.

Parameters:

Name	Type	Description	Default
capability	str	Capability identifier (protocol slug such as "feature-server" or a feature flag name).	required

Returns:

Type	Description
bool	True when the server advertises the capability,
bool	False otherwise.

Raises:

Type	Description
HonuaHttpError	The underlying capability lookup failed server-side with a non-404 status.
HonuaTransportError	The capability lookup failed at the transport layer.

Per-request options (timeout / extra_headers) are forwarded to :meth:capabilities.

source(descriptor)

Return an async source-bound facade for Source/Query/Result workflows.

Parameters:

Name	Type	Description	Default
descriptor	'SourceDescriptor | Mapping[str, Any]'	A :class:SourceDescriptor (or mapping convertible to one) identifying the dataset and protocol the facade should target.	required

Returns:

Name	Type	Description
An	'AsyncSource'	class:AsyncSource bound to this client's transport.

list_services(*, response_format='json', timeout=None, extra_headers=None) async

List services from the GeoServices catalog endpoint.

Parameters:

Name	Type	Description	Default
response_format	str	Value passed as the f query parameter on /rest/services (defaults to "json").	'json'

Returns:

Type	Description
dict[str, Any]	The raw catalog payload as a dict.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

list_service_summaries(*, response_format='json', timeout=None, extra_headers=None) async

List services as typed catalog summaries.

Parameters:

Name	Type	Description	Default
response_format	str	Value passed as the f query parameter on /rest/services (defaults to "json").	'json'

Returns:

Type	Description
list[ServiceSummary]	A list of :class:ServiceSummary objects; empty when the
list[ServiceSummary]	catalog payload does not contain a services list.

Per-request options (timeout / extra_headers) are forwarded to :meth:list_services.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

ogc_features()

Return an async OGC API Features wrapper bound to this client.

Returns:

Name	Type	Description
An	'AsyncHonuaOgcFeatures'	class:AsyncHonuaOgcFeatures facade that reuses this
	'AsyncHonuaOgcFeatures'	client's HTTP session.

geocoder(locator='World')

Return an async GeocodeServer wrapper that reuses this client's session.

Parameters:

Name	Type	Description	Default
locator	str	GeocodeServer locator name (defaults to "World").	'World'

Returns:

Name	Type	Description
An	'AsyncHonuaGeocodingClient'	class:AsyncHonuaGeocodingClient bound to locator.

feature_server(service_id)

Return an async GeoServices FeatureServer wrapper for a service.

Parameters:

Name	Type	Description	Default
service_id	str	Service identifier as advertised by the catalog.	required

Returns:

Name	Type	Description
An	'AsyncGeoServicesFeatureServerClient'	class:AsyncGeoServicesFeatureServerClient bound to this
	'AsyncGeoServicesFeatureServerClient'	client's transport.

Raises:

Type	Description
HonuaHttpError	A subsequent request issued through the returned wrapper fails server-side (the factory itself does not perform I/O).

map_server(service_id)

Return an async GeoServices MapServer wrapper for a service.

Parameters:

Name	Type	Description	Default
service_id	str	Service identifier as advertised by the catalog.	required

Returns:

Name	Type	Description
An	'AsyncGeoServicesMapServerClient'	class:AsyncGeoServicesMapServerClient bound to this
	'AsyncGeoServicesMapServerClient'	client's transport.

image_server(service_id=None)

Return an async GeoServices ImageServer wrapper.

Parameters:

Name	Type	Description	Default
service_id	str | None	Optional service identifier; when None the wrapper targets the deployment-level ImageServer surface.	None

Returns:

Name	Type	Description
An	'AsyncGeoServicesImageServerClient'	class:AsyncGeoServicesImageServerClient bound to this
	'AsyncGeoServicesImageServerClient'	client.

geometry_server()

Return the async GeoServices GeometryServer wrapper.

Returns:

Name	Type	Description
An	'AsyncGeoServicesGeometryServerClient'	class:AsyncGeoServicesGeometryServerClient bound to
	'AsyncGeoServicesGeometryServerClient'	this client's transport.

ogc_maps()

Return an async OGC API Maps wrapper.

Returns:

Name	Type	Description
An	'AsyncOgcMapsClient'	class:AsyncOgcMapsClient bound to this client's
	'AsyncOgcMapsClient'	transport.

ogc_tiles()

Return an async OGC API Tiles wrapper.

Returns:

Name	Type	Description
An	'AsyncOgcTilesClient'	class:AsyncOgcTilesClient bound to this client's
	'AsyncOgcTilesClient'	transport.

ogc_coverages()

Return an async OGC API Coverages wrapper.

Returns:

Name	Type	Description
An	'AsyncOgcCoveragesClient'	class:AsyncOgcCoveragesClient bound to this client's
	'AsyncOgcCoveragesClient'	transport.

ogc_processes()

Return an async OGC API Processes wrapper.

Returns:

Name	Type	Description
An	'AsyncOgcProcessesClient'	class:AsyncOgcProcessesClient bound to this client's
	'AsyncOgcProcessesClient'	transport.

ogc_records()

Return an async OGC API Records wrapper.

geoprocessing()

Return an async geoprocessing (OGC API Processes) client.

Returns:

Name	Type	Description
An	'AsyncHonuaGeoprocessing'	class:~honua_sdk.geoprocessing.AsyncHonuaGeoprocessing bound
	'AsyncHonuaGeoprocessing'	to this client's transport for listing/describing processes and
	'AsyncHonuaGeoprocessing'	submitting + polling + fetching the results of process executions.

workflow()

Return an async workflow package authoring + publication client.

Returns:

Name	Type	Description
An	'AsyncHonuaWorkflow'	class:~honua_sdk.workflow.AsyncHonuaWorkflow bound to this
	'AsyncHonuaWorkflow'	client's transport for authoring workflow package drafts,
	'AsyncHonuaWorkflow'	snapshotting immutable versions, validating / dry-running /
	'AsyncHonuaWorkflow'	publishing them, and running publications over the server's
	'AsyncHonuaWorkflow'	/api/v1/console workflow package surface (the durable
	'AsyncHonuaWorkflow'	replacement for the dropped GeoETL pipeline endpoints; admin
	'AsyncHonuaWorkflow'	authorization required server-side).

stac()

Return an async STAC API wrapper.

Returns:

Name	Type	Description
An	'AsyncStacClient'	class:AsyncStacClient bound to this client's transport.

scenes()

Return an async 3D scene metadata + resolution wrapper.

Returns:

Name	Type	Description
An	'AsyncSceneClient'	class:AsyncSceneClient bound to this client's transport.

elevation()

Return an async elevation HTTP API wrapper.

Returns:

Name	Type	Description
An	'AsyncElevationClient'	class:AsyncElevationClient bound to this client's transport.

wfs()

Return an async WFS 2.0 wrapper.

Returns:

Name	Type	Description
An	'AsyncWfsClient'	class:AsyncWfsClient bound to this client's transport.

wms(service_id)

Return an async service-scoped WMS wrapper.

Parameters:

Name	Type	Description	Default
service_id	str	Service identifier as advertised by the catalog.	required

Returns:

Name	Type	Description
An	'AsyncWmsClient'	class:AsyncWmsClient bound to this client's transport.

wmts(service_id)

Return an async service-scoped WMTS wrapper.

Parameters:

Name	Type	Description	Default
service_id	str	Service identifier as advertised by the catalog.	required

Returns:

Name	Type	Description
An	'AsyncWmtsClient'	class:AsyncWmtsClient bound to this client's transport.

odata()

Return an async OData v4 wrapper.

Returns:

Name	Type	Description
An	'AsyncODataClient'	class:AsyncODataClient bound to this client's transport.

grpc(*, target=None, insecure=None, credentials=None, timeout=30.0, extra_metadata=None)

Return a gRPC FeatureService client bound to this client's config.

Builds an :class:AsyncHonuaGrpcClient (the analytic gRPC surface: unary + streaming QueryFeatures with server-side spatial filters, statistics, and aggregation) from the same base URL and authentication this client was constructed with — so the gRPC surface is reachable in the same token-scoped harness without re-plumbing a channel.

The dial target defaults to the REST base_url's host:port (the Honua gRPC service shares the REST authority). Authentication is carried as gRPC call metadata derived from the client's api_key / bearer_token / auth_provider via :func:honua_sdk.grpc.build_grpc_metadata. Transport security defaults to TLS for an https base URL and plaintext otherwise; override with credentials= (a :class:grpc.ChannelCredentials) or insecure=True.

Parameters:

Name	Type	Description	Default
target	str | None	Explicit host:port gRPC dial target. Defaults to the REST base URL's authority.	None
insecure	bool | None	Force a plaintext channel. Defaults to True for a non-https base URL, False otherwise.	None
credentials	Any	Explicit channel credentials. Defaults to :func:grpc.ssl_channel_credentials for a secure channel.	None
timeout	float | None	Per-call gRPC timeout in seconds.	30.0
extra_metadata	Mapping[str, str] | None	Additional metadata entries merged onto the auth-derived metadata.	None

Returns:

Name	Type	Description
An	'HonuaGrpcAsyncClient'	class:AsyncHonuaGrpcClient ready to issue feature queries.

Raises:

Type	Description
ValueError	The client base_url has no host to derive a target from.

query(source, *, protocol=None, layer_id=None, where=None, filter=None, bbox=None, spatial_filter=None, fields=None, return_geometry=None, out_statistics=None, group_by=None, return_distinct_values=None, return_count_only=None, page_size=None, limit=None, max_pages=100, extra_params=None, timeout=None, extra_headers=None, idempotency_key=None) async

Run a protocol-neutral feature query and collect normalized features.

Parameters:

Name	Type	Description	Default
source	str | FeatureQuery	Either a source identifier (service name, OGC collection id, STAC collection id, OData entity set) or a pre-built :class:FeatureQuery. When a query object is provided the remaining keyword arguments are ignored.	required
protocol	QueryProtocol | None	Override the protocol resolved from source.	None
layer_id	int | None	FeatureServer layer index or OData layer id when the protocol requires one.	None
where	str | None	GeoServices-style WHERE clause (FeatureServer only).	None
filter	str | None	CQL2/OData filter expression (OGC Features / STAC / OData).	None
bbox	str | Sequence[int | float] | None	Spatial filter as a list/tuple of coordinates or comma string. Not supported when protocol is OData.	None
spatial_filter	Mapping[str, Any] | None	Arbitrary-geometry spatial filter (FeatureServer only): a mapping of geometry (Esri JSON / GeoJSON / __geo_interface__), relationship (intersects, within, contains, crosses, touches, overlaps, within-distance), optional in_sr and distance/units. Translated to the GeoServices geometry/geometryType/spatialRel/inSR params.	None
fields	str | Sequence[str] | None	Attribute selection; comma-string or sequence of names.	None
return_geometry	bool | None	Whether to include geometry (FeatureServer).	None
out_statistics	Sequence[Mapping[str, Any]] | None	Server-side statistic definitions (FeatureServer): a sequence of mappings with statistic_type (count, sum, min, max, avg, stddev, var), on_statistic_field, and optional out_statistic_field_name.	None
group_by	str | Sequence[str] | None	Group-by fields paired with out_statistics.	None
return_distinct_values	bool | None	Request distinct rows (FeatureServer).	None
return_count_only	bool | None	Request only the matching count (FeatureServer).	None
page_size	int | None	Page size hint for paginated protocols.	None
limit	int | None	Maximum number of features to collect across all pages.	None
max_pages	int | None	Safety cap on pages walked; defaults to 100. Pass None for an unbounded walk (FeatureServer) — a ResourceWarning is emitted if a bounded walk stops with more features still available on the server.	100
extra_params	Mapping[str, Any] | None	Additional protocol-specific query parameters merged into each request.	None
timeout	float | Timeout | None	Per-call timeout override forwarded to every page request across all protocols (FeatureServer, OGC Features, STAC, OData). Accepts a float seconds value or an :class:httpx.Timeout.	None
idempotency_key	str | None	Stripe-style Idempotency-Key header value attached to every page request. Merged into extra_headers before forwarding.	None
extra_headers	Mapping[str, str] | None	Additional HTTP headers merged into every page request across all protocols.	None

Returns:

Name	Type	Description
A	FeatureQueryResult	class:FeatureQueryResult containing the normalized
	FeatureQueryResult	features, resolved protocol, source, and the effective query.

Raises:

Type	Description
ValueError	bbox is supplied for the OData protocol.
HonuaHttpError	A page request returned a non-success status.
HonuaTransportError	A page request failed at the transport layer.

iter_query(source, *, protocol=None, layer_id=None, where=None, filter=None, bbox=None, spatial_filter=None, fields=None, return_geometry=None, page_size=None, limit=None, max_pages=100, extra_params=None, timeout=None, extra_headers=None, idempotency_key=None) async

Stream normalized features from FeatureServer, OGC Features, STAC, or OData.

This is the streaming counterpart to :meth:query — features are yielded one at a time so callers can short-circuit large result sets.

Parameters:

Name	Type	Description	Default
source	str | FeatureQuery	Source identifier or pre-built :class:FeatureQuery. When a query object is provided the remaining keyword arguments are ignored.	required
protocol	QueryProtocol | None	Override the protocol resolved from source.	None
layer_id	int | None	FeatureServer layer index or OData layer id when the protocol requires one.	None
where	str | None	GeoServices-style WHERE clause (FeatureServer only).	None
filter	str | None	CQL2/OData filter expression for OGC/STAC/OData.	None
bbox	str | Sequence[int | float] | None	Spatial filter; not supported for OData.	None
spatial_filter	Mapping[str, Any] | None	Arbitrary-geometry spatial filter (FeatureServer); see :meth:query for the mapping shape.	None
fields	str | Sequence[str] | None	Attribute selection.	None
return_geometry	bool | None	Whether to include geometry (FeatureServer).	None
page_size	int | None	Page size hint for paginated protocols.	None
limit	int | None	Maximum number of features to yield across all pages.	None
max_pages	int | None	Safety cap on pages walked; defaults to 100. Pass None for an unbounded walk (FeatureServer).	100
extra_params	Mapping[str, Any] | None	Protocol-specific query parameters merged into each request.	None

Per-call timeout / extra_headers are forwarded to every protocol's pagination wrapper (FeatureServer, OGC Features, STAC, OData). idempotency_key is merged into extra_headers before forwarding.

Yields:

Name	Type	Description
Normalized	AsyncIterator[QueryFeature]	class:QueryFeature objects.

Raises:

Type	Description
ValueError	bbox is supplied for the OData protocol.
HonuaHttpError	A page request returned a non-success status.
HonuaTransportError	A page request failed at the transport layer.

query_features(service_id, layer_id, *, where='1=1', out_fields='*', return_geometry=True, extra_params=None, timeout=None, extra_headers=None) async

Query features from a FeatureServer layer and return raw JSON.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
where	str	GeoServices WHERE clause; defaults to "1=1".	'1=1'
out_fields	str | Sequence[str]	Field selection; either a comma-string or sequence of names. Defaults to "*".	'*'
return_geometry	bool	Whether the server should include geometry.	True
extra_params	Mapping[str, Any] | None	Additional query-string parameters merged into the request (e.g. resultOffset, resultRecordCount).	None

Returns:

Type	Description
dict[str, Any]	The raw FeatureServer query response as a dict.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

query_feature_set(service_id, layer_id, *, where='1=1', out_fields='*', return_geometry=True, extra_params=None, timeout=None, extra_headers=None) async

Query a FeatureServer layer and return a typed :class:FeatureSet.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
where	str	GeoServices WHERE clause; defaults to "1=1".	'1=1'
out_fields	str | Sequence[str]	Field selection; either a comma-string or sequence of names. Defaults to "*".	'*'
return_geometry	bool	Whether the server should include geometry.	True
extra_params	Mapping[str, Any] | None	Additional query-string parameters merged into the request (e.g. resultOffset, resultRecordCount).	None

Returns:

Name	Type	Description
A	FeatureSet	class:FeatureSet parsed from the raw query response.

Per-request options (timeout / extra_headers) are forwarded to :meth:query_features.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

query_features_all(service_id, layer_id, *, where='1=1', out_fields='*', return_geometry=True, page_size=1000, limit=None, max_pages=100, extra_params=None, timeout=None, extra_headers=None) async

Page through FeatureServer query results and return typed features.

Walks the FeatureServer query endpoint with resultOffset / resultRecordCount until either limit is reached, the server stops indicating that the transfer limit was exceeded, or max_pages is hit.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
where	str	GeoServices WHERE clause; defaults to "1=1".	'1=1'
out_fields	str | Sequence[str]	Field selection; comma-string or sequence of names.	'*'
return_geometry	bool	Whether the server should include geometry.	True
page_size	int	Page size hint forwarded as resultRecordCount. Must be greater than zero.	1000
limit	int | None	Optional cap on the total number of features returned.	None
max_pages	int	Safety cap on the number of pages walked. Must be greater than zero.	100
extra_params	Mapping[str, Any] | None	Additional query parameters. Any resultOffset value is honored as the starting offset.	None

Returns:

Type	Description
list[Feature]	A list of typed :class:Feature objects up to limit.

Per-request options (timeout / extra_headers) are forwarded to every page-level :meth:query_feature_set call.

Raises:

Type	Description
ValueError	page_size or max_pages is not positive.
HonuaHttpError	A page request returned a non-success status.
HonuaTransportError	A page request failed at the transport layer.

apply_edits(service_id, layer_id, *, adds=None, updates=None, deletes=None, rollback_on_failure=True, idempotency_key=None, timeout=None, extra_headers=None) async

Submit a layer-level GeoServices applyEdits request.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
adds	Sequence[Mapping[str, Any]] | None	Sequence of feature mappings to insert.	None
updates	Sequence[Mapping[str, Any]] | None	Sequence of feature mappings to update by OBJECTID.	None
deletes	Sequence[int] | str | None	Either a sequence of object ids or a comma-string of ids to delete.	None
rollback_on_failure	bool	Whether the server should roll the entire batch back if any individual edit fails.	True
idempotency_key	str | None	Stripe-style Idempotency-Key header value. When None and the underlying retry transport is configured to retry POST (i.e. the caller opted in via retry_methods), a fresh uuid4 hex is generated so that retries are de-duplicated server-side. Pass an explicit value to make the request idempotent across application retries as well.	None

Returns:

Type	Description
dict[str, Any]	The raw applyEdits response payload as a dict.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

apply_edits_result(service_id, layer_id, *, adds=None, updates=None, deletes=None, rollback_on_failure=True, idempotency_key=None, timeout=None, extra_headers=None) async

Submit applyEdits and return typed per-operation results.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
layer_id	int	Numeric layer index within the FeatureServer.	required
adds	Sequence[Mapping[str, Any]] | None	Sequence of feature mappings to insert.	None
updates	Sequence[Mapping[str, Any]] | None	Sequence of feature mappings to update by OBJECTID.	None
deletes	Sequence[int] | str | None	Either a sequence of object ids or a comma-string of ids to delete.	None
rollback_on_failure	bool	Whether the server should roll the entire batch back if any individual edit fails.	True
idempotency_key	str | None	Stripe-style Idempotency-Key header value; forwarded to :meth:apply_edits. See that method for auto-generation semantics.	None

Returns:

Name	Type	Description
An	ApplyEditsResult	class:ApplyEditsResult parsed from the response.

Per-request options (timeout / extra_headers / idempotency_key) are forwarded to :meth:apply_edits.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

export_map(service_id, bbox, *, size=(400, 400), image_format='png', transparent=True, dpi=96, extra_params=None, timeout=None, extra_headers=None) async

Request rendered map bytes from the MapServer export endpoint.

Parameters:

Name	Type	Description	Default
service_id	str	GeoServices service identifier; URL-encoded.	required
bbox	Sequence[float] | str	Bounding box as a sequence of floats (xmin, ymin, xmax, ymax) or pre-formatted comma string.	required
size	tuple[int, int]	(width, height) in pixels; defaults to (400, 400).	(400, 400)
image_format	str	Output image format ("png", "jpg", ...).	'png'
transparent	bool	Whether the rendered image should be transparent where there is no data.	True
dpi	int	Output DPI value forwarded to the server.	96
extra_params	Mapping[str, Any] | None	Additional query parameters merged into the request (e.g. layers, layerDefs).	None

Returns:

Type	Description
bytes	The raw image bytes returned by the server.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

honua_sdk.HonuaGeocodingClient

Synchronous task-oriented client for Honua GeocodeServer workflows.

close()

Release underlying HTTP resources if this instance owns the client.

When constructed with an externally supplied :class:httpx.Client, ownership stays with the caller and this method is a no-op.

forward_geocode(address, *, max_results=10, country_codes=None, spatial_reference_wkid=4326, timeout=None, extra_headers=None)

Find address candidates for a single-line address string.

Parameters:

Name	Type	Description	Default
address	str	Free-form single-line address.	required
max_results	int	Maximum number of candidates the server may return (forwarded as maxLocations).	10
country_codes	str | None	Optional ISO country-code filter (forwarded as countryCode).	None
spatial_reference_wkid	int	WKID for returned coordinates (forwarded as outSR); defaults to 4326 (WGS84).	4326

Returns:

Type	Description
list[GeocodeResult]	A list of :class:GeocodeResult candidates, ordered by the
list[GeocodeResult]	server-reported match score.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

reverse_geocode(latitude, longitude, *, spatial_reference_wkid=4326, timeout=None, extra_headers=None)

Reverse-geocode a coordinate pair into a postal address.

Parameters:

Name	Type	Description	Default
latitude	float	Latitude of the input coordinate.	required
longitude	float	Longitude of the input coordinate.	required
spatial_reference_wkid	int	WKID for both the input coordinate interpretation and the response location; defaults to 4326 (WGS84).	4326

Returns:

Name	Type	Description
A	ReverseGeocodeResult | None	class:ReverseGeocodeResult when the server returned
	ReverseGeocodeResult | None	either an address or a location; None when neither field
	ReverseGeocodeResult | None	was present in the response.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

suggest(text, *, max_suggestions=5, country_codes=None, timeout=None, extra_headers=None)

Fetch typeahead suggestions for partial address text.

Parameters:

Name	Type	Description	Default
text	str	Partial address text the user has typed so far.	required
max_suggestions	int	Maximum number of suggestions to return (forwarded as maxSuggestions).	5
country_codes	str | None	Optional ISO country-code filter (forwarded as countryCode).	None

Returns:

Type	Description
list[GeocodeSuggestion]	A list of :class:GeocodeSuggestion objects. Pair the
list[GeocodeSuggestion]	magic_key field with a follow-up
list[GeocodeSuggestion]	meth:forward_geocode call to resolve a chosen suggestion.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

honua_sdk.AsyncHonuaGeocodingClient

Asynchronous task-oriented client for Honua GeocodeServer workflows.

close() async

Release underlying HTTP resources if this instance owns the client.

When constructed with an externally supplied :class:httpx.AsyncClient, ownership stays with the caller and this coroutine is a no-op.

forward_geocode(address, *, max_results=10, country_codes=None, spatial_reference_wkid=4326, timeout=None, extra_headers=None) async

Find address candidates for a single-line address string.

Parameters:

Name	Type	Description	Default
address	str	Free-form single-line address.	required
max_results	int	Maximum number of candidates the server may return (forwarded as maxLocations).	10
country_codes	str | None	Optional ISO country-code filter (forwarded as countryCode).	None
spatial_reference_wkid	int	WKID for returned coordinates (forwarded as outSR); defaults to 4326 (WGS84).	4326

Returns:

Type	Description
list[GeocodeResult]	A list of :class:GeocodeResult candidates, ordered by the
list[GeocodeResult]	server-reported match score.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

reverse_geocode(latitude, longitude, *, spatial_reference_wkid=4326, timeout=None, extra_headers=None) async

Reverse-geocode a coordinate pair into a postal address.

Parameters:

Name	Type	Description	Default
latitude	float	Latitude of the input coordinate.	required
longitude	float	Longitude of the input coordinate.	required
spatial_reference_wkid	int	WKID for both the input coordinate interpretation and the response location; defaults to 4326 (WGS84).	4326

Returns:

Name	Type	Description
A	ReverseGeocodeResult | None	class:ReverseGeocodeResult when the server returned
	ReverseGeocodeResult | None	either an address or a location; None when neither field
	ReverseGeocodeResult | None	was present in the response.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.

suggest(text, *, max_suggestions=5, country_codes=None, timeout=None, extra_headers=None) async

Fetch typeahead suggestions for partial address text.

Parameters:

Name	Type	Description	Default
text	str	Partial address text the user has typed so far.	required
max_suggestions	int	Maximum number of suggestions to return (forwarded as maxSuggestions).	5
country_codes	str | None	Optional ISO country-code filter (forwarded as countryCode).	None

Returns:

Type	Description
list[GeocodeSuggestion]	A list of :class:GeocodeSuggestion objects. Pair the
list[GeocodeSuggestion]	magic_key field with a follow-up
list[GeocodeSuggestion]	meth:forward_geocode call to resolve a chosen suggestion.

Per-request options (timeout / extra_headers) are forwarded to :meth:_request.

Raises:

Type	Description
HonuaHttpError	The server returned a non-success status.
HonuaTransportError	The request failed at the transport layer.