Getting Started

Install the SDK and make your first API request.

Installation

pip install spatialflow

Quick Start

import asyncio
from spatialflow import SpatialFlow, models

async def main():
    async with SpatialFlow(api_key="sf_xxx") as client:
        # List geofences
        response = await client.geofences.list()
        for geofence in response.geofences:
            print(f"{geofence.name}: {geofence.id}")

asyncio.run(main())

Create Your First Geofence

import asyncio
from spatialflow import SpatialFlow, models

async def main():
    async with SpatialFlow(api_key="sf_xxx") as client:
        # Create a geofence
        geofence = await client.geofences.create(
            models.CreateGeofenceRequest(
                name="My Region",
                geometry={
                    "type": "Polygon",
                    "coordinates": [[
                        [-122.4, 37.8],
                        [-122.4, 37.7],
                        [-122.3, 37.7],
                        [-122.3, 37.8],
                        [-122.4, 37.8],
                    ]]
                }
            )
        )
        print(f"Created: {geofence.name} ({geofence.id})")

asyncio.run(main())

Error Handling

The SDK provides typed exceptions for common error cases:

from spatialflow import (
    SpatialFlow,
    AuthenticationError,
    NotFoundError,
    ValidationError,
    RateLimitError,
)

async def main():
    async with SpatialFlow(api_key="sf_xxx") as client:
        try:
            geofence = await client.geofences.get(geofence_id="invalid-id")
        except NotFoundError:
            print("Geofence not found")
        except AuthenticationError:
            print("Invalid API key")
        except ValidationError as e:
            print(f"Validation error: {e}")
        except RateLimitError:
            print("Rate limited, try again later")

asyncio.run(main())

Available Exceptions

Exception	HTTP Status	Description
AuthenticationError	401	Invalid or missing credentials
PermissionError	403	Insufficient permissions
NotFoundError	404	Resource not found
ValidationError	400, 422	Invalid request data
RateLimitError	429	Too many requests
ConflictError	409	Resource conflict
ServerError	5xx	Server-side error
TimeoutError	-	Request timed out
ConnectionError	-	Network connection failed

Next Steps

• Resources - Full CRUD reference
• Workflow Builders - Create workflows programmatically
• Webhook Verification - Verify incoming webhooks