Python SDK

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

Alpha Release

The Python SDK is currently in alpha (v0.2.0). APIs may change before the stable release.

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