Python SDK

The official Python SDK for SpatialFlow provides a clean, async-first interface for the SpatialFlow API.

SDK Version 1.1.0

The published Python SDK is v1.1.0. The webhook signature and payload fixes are in the source and will ship in the next release (1.1.1), so the PyPI package does not have them yet.

Requirements

• Python >= 3.9
• asyncio support

What's in the SDK

The SDK provides two API surfaces:

Clean API (Recommended)

Intuitive, resource-based methods:

await client.geofences.list()
await client.geofences.create(request)
await client.workflows.toggle(workflow_id="...")
await client.locations.ingest(device_id="...", lat=37.7, lon=-122.4)
await client.integrations.create_webhook(name="...", url="...")

Raw API

Direct access to generated OpenAPI methods:

await client.raw.geofences.apps_geofences_api_list_geofences()
await client.raw.workflows.apps_workflows_api_toggle_workflow(workflow_id="...")

Features

• Async/await - Built on aiohttp for non-blocking I/O
• Full CRUD - Geofences, workflows, webhooks, devices, integrations
• Workflow builders - Programmatically create workflow configurations
• Location ingestion - Public API for device location updates
• Pagination - Async iterators for large result sets
• Webhook verification - HMAC-SHA256 signature validation
• File uploads - GeoJSON, KML, GPX import with job polling
• Typed errors - AuthenticationError, NotFoundError, ValidationError, etc.

Authentication

API Key (Recommended for server-side)

from spatialflow import SpatialFlow

client = SpatialFlow(api_key="sf_xxx")

JWT Token (For client-side apps)

client = SpatialFlow(access_token="eyJ...")

Async Context Manager

The client should be used as an async context manager to ensure proper cleanup:

async with SpatialFlow(api_key="sf_xxx") as client:
    response = await client.geofences.list()
    # ...
# Connection is automatically closed

Or manually close when done:

client = SpatialFlow(api_key="sf_xxx")
try:
    response = await client.geofences.list()
finally:
    await client.close()

Configuration

Parameter	Default	Description
api_key	-	API key (starts with sf_)
access_token	-	JWT token (alternative to api_key)
base_url	https://api.spatialflow.io	API base URL
timeout	30	Request timeout in seconds
max_retries	3	Maximum retry attempts

Next Steps

• Getting Started - Installation and first request
• Resources - Full CRUD reference for all resources
• Workflow Builders - Programmatic workflow creation