Python Client Library

The official GeoServer Python SDK provides a high-level, idiomatic interface for interacting with GeoServer instances. It supports synchronous and asynchronous operations, automatic pagination, real-time spatial streaming, and full OGC standards compliance (WMS, WFS, WCS, GeoJSON).

🐍 Version 2.4 Release

Includes native async/await support, improved GeoJSON parsing, built-in retry logic for transient network failures, and zero-dependency CLI tools.

Installation

Install the latest stable release via pip:

pip install geoserver-sdk

For development or nightly builds:

pip install git+https://github.com/geoserver/py-sdk.git@main

Quick Start

Initialize a client and fetch your first spatial dataset in three lines:

import geoserver

async def main():
    # Connect to your instance
    client = geoserver.Client(
        host="https://api.geoserver.example.com",
        token="YOUR_API_KEY",
        region="us-east-1"
    )

    # Query features within a bounding box
    features = await client.query(
        dataset="global_coastlines_v3",
        bbox=[-180, -90, 180, 90],
        crs="EPSG:4326",
        limit=100
    )
    
    print(f"Fetched {features.count} geometries")

if __name__ == "__main__":
    import asyncio
    asyncio.run(main())

API Reference

The core Client class exposes the following methods:

Method	Description	Returns
connect(config)	Establishes a persistent connection with optional TLS verification and proxy routing.	`ClientSession`
query(dataset, bbox, crs, limit)	Executes a spatial query against a registered layer. Supports WKT, GeoJSON, and Shapefile outputs.	`FeatureCollection`
render_map(layers, format, width, height)	Generates a static map image using server-side styling. Returns a binary stream.	`bytes`
stream_dataset(name, callback)	Opens a WebSocket-like spatial event stream. Triggers `callback(feature)` on updates.	`StreamHandle`
upload_vector(data, format, destination)	Authored data ingestion. Automatically projects and indexes geometries.	`UploadResult`

Authentication

GeoServer supports multiple authentication strategies. The SDK automatically handles token rotation and refresh:

# API Key (Recommended for production)
client = geoserver.Client(token="gs_live_abc123")

# OAuth2 / OpenID Connect
client = geoserver.Client(
    auth=geoserver.oauth.OAuth2Provider(
        client_id="your_app",
        client_secret="secret",
        redirect_uri="https://your-app.com/callback"
    )
)

Usage Examples

Export to GeoJSON

collection = await client.query("us_census_tracts", limit=500)
with open("tracts.geojson", "w") as f:
    f.write(collection.to_geojson(pretty=True))

Real-Time Sensor Streaming

def on_update(feature):
    print(f"New reading: {feature.properties['value']} at {feature.geometry}")

stream = client.stream_dataset("iot_temperature_sensors", on_update)
# Stream runs indefinitely until cancelled

FAQ & Troubleshooting

Q: Why am I getting a 429 Too Many Requests error?
A: The SDK includes automatic exponential backoff. If you see this, consider increasing your rate limit tier or implementing client-side caching for static datasets.

Q: Does the SDK support offline caching?
A: Yes. Use client.cache.enable(path="/tmp/gs-cache") to persist queries locally. Cache TTL is configurable via environment variables or the config object.

Q: How do I handle large geometries without memory spikes?
A: Use the chunk_size parameter in query() or switch to the generator-based query_iter() method for lazy evaluation.