Skip to main content

Geofences

Geofences are virtual boundaries defined on a map that trigger events when devices enter or exit them. They're the foundation of location-based automation in SpatialFlow.

What is a Geofence?​

A geofence is a virtual perimeter around a real-world geographic area. When a device's location crosses this boundary, SpatialFlow detects the transition and can trigger automated actions through workflows.

Real-world examples:

  • A delivery zone around a restaurant that notifies when drivers enter
  • A restricted area that sends alerts when unauthorized devices cross the boundary
  • A retail store location that triggers marketing actions when customers arrive
  • A job site perimeter that logs worker entry and exit times

Geofence Types​

SpatialFlow supports polygon and circle geofences to match a variety of real-world boundaries.

Polygon Geofences​

Polygon geofences allow you to define custom-shaped boundaries using multiple vertices (points).

Use cases:

  • Irregularly shaped properties or facilities
  • Delivery zones that follow street patterns
  • Campus or industrial complex boundaries
  • Service areas that match neighborhood boundaries

Key characteristics:

  • Defined by 3 to 500 vertices
  • More vertices = more precise boundaries
  • GeoJSON Polygon format with coordinate arrays
  • Automatically closed (first and last points connect)

Example polygon structure:

{
  "type": "Polygon",
  "coordinates": [
    [
      [-122.4194, 37.7749],  // First vertex (lng, lat)
      [-122.4184, 37.7749],
      [-122.4184, 37.7739],
      [-122.4194, 37.7739],
      [-122.4194, 37.7749]   // Last vertex (must match first)
    ]
  ]
}
Drawing Polygons

Use the SpatialFlow Dashboard's map interface to draw polygons visually. Click to place vertices, double-click to complete. The UI handles closing the polygon automatically.

Circle Geofences​

Circle geofences define a boundary using a center point and a radius in meters. They're ideal for simple, symmetrical zones.

Use cases:

  • Point-of-interest proximity alerts (e.g., within 500m of a store)
  • Simple job site perimeters
  • Delivery drop-off radius zones
  • Asset proximity monitoring

Key characteristics:

  • Defined by a center point (longitude, latitude) and radius in meters
  • Uses a custom Circle geometry type (not a standard GeoJSON type)
  • Rendered as a circle on the Dashboard map

Example circle structure:

{
  "name": "Store Proximity Zone",
  "geometry": {
    "type": "Circle",
    "center": [-74.006, 40.714],
    "radius_meters": 500
  }
}
Drawing Circles

Use the Dashboard's Draw circle tool to create circle geofences visually. Click a center point and drag to set the radius.

Key Properties​

Every geofence in SpatialFlow has these core properties:

Name (Required)​

  • Human-readable identifier
  • 1-100 characters
  • Example: "Downtown Delivery Zone"

Geometry (Required)​

  • GeoJSON Polygon, MultiPolygon, or Circle (custom type) defining the boundary
  • Coordinates in [longitude, latitude] format
  • SRID 4326 (WGS84) coordinate system
  • Validated on creation

Description (Optional)​

  • Detailed notes about the geofence
  • Up to 500 characters
  • Example: "Primary delivery area covering downtown district"

Metadata (Optional)​

  • Custom JSON object for storing additional data
  • Use for tagging, categorization, or application-specific data
  • Example:
{
  "region": "north",
  "priority": "high",
  "cost_center": "12345"
}

Active Status​

  • Boolean flag to enable/disable the geofence
  • Inactive geofences don't trigger events
  • Useful for temporary disabling without deletion

Group (Optional)​

  • Organize related geofences into named groups
  • Group ID and group name for logical workspace
  • Query all geofences in a group via API

Creating Geofences​

Via API​

Create a polygon geofence using the REST API:

curl -X POST https://api.spatialflow.io/api/v1/geofences \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Downtown Office",
    "description": "Main office building geofence",
    "geometry": {
      "type": "Polygon",
      "coordinates": [
        [
          [-122.4194, 37.7749],
          [-122.4184, 37.7749],
          [-122.4184, 37.7739],
          [-122.4194, 37.7739],
          [-122.4194, 37.7749]
        ]
      ]
    },
    "metadata": {
      "building": "headquarters",
      "floor_count": 5
    }
  }'

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Downtown Office",
  "description": "Main office building geofence",
  "geometry": {
    "type": "Polygon",
    "coordinates": [...]
  },
  "metadata": {
    "building": "headquarters",
    "floor_count": 5
  },
  "is_active": true,
  "created_at": "2025-11-10T10:00:00Z",
  "updated_at": "2025-11-10T10:00:00Z"
}

Via Dashboard​

The SpatialFlow Dashboard provides a visual interface for geofence creation:

  1. Click Locations in the top navigation bar, then select Geofences
  2. Click + Create Geofence in the top-right corner
  3. Choose the map tool:
    • Polygon Tool: Click to place vertices, double-click to finish
    • Circle Tool: Click to set center, then adjust the Radius input in the toolbar
  4. Fill in the geofence details (name, description, metadata)
  5. Click Create Geofence

For detailed UI guidance, see Create Your First Geofence.

Geofence Groups​

Groups help organize related geofences for easier management and querying.

Common grouping strategies:

  • By region: "West Coast Stores", "East Coast Warehouses"
  • By type: "Delivery Zones", "Restricted Areas", "Parking Lots"
  • By customer: "Client A Locations", "Client B Sites"
  • By project: "Q4 Campaign", "Winter Operations"

Creating grouped geofences:

{
  "name": "Store #101",
  "group_name": "Retail Locations",
  "geometry": { ... }
}

Listing all groups:

curl https://api.spatialflow.io/api/v1/geofences/groups \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "groups": [
    {
      "group_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "group_name": "Retail Locations",
      "geofence_count": 47
    }
  ],
  "count": 1
}

Best Practices​

Vertex Limits​

  • Minimum: 3 vertices (triangle)
  • Maximum: 500 vertices
  • Recommended: 4-50 vertices for most use cases
  • Performance tip: More vertices = longer processing time. Simplify complex boundaries when possible.

Coordinate Precision​

  • Use 6-8 decimal places for coordinates
  • Example: -122.419416, 37.774929
  • More precision doesn't improve accuracy beyond device GPS capabilities

Naming Conventions​

Use clear, descriptive names that include:

  • Location identifier: "Downtown SF Office"
  • Purpose: "Delivery Zone - Restaurant A"
  • Unique identifiers: "Store #101"

Good examples:

  • "SF HQ - Main Building"
  • "NYC Warehouse - Zone A"
  • "Customer Site - Acme Corp"

Avoid:

  • "Geofence 1"
  • "Test"
  • "asdf"

Metadata Usage​

Store application-specific data in metadata for:

  • Filtering: Query geofences by custom attributes
  • Display: Show additional info in your application
  • Integration: Pass context to downstream systems

Example metadata structure:

{
  "metadata": {
    "region": "west",
    "type": "delivery_zone",
    "contact_email": "ops@example.com",
    "business_hours": "9am-5pm PST",
    "priority": "high"
  }
}

Performance Considerations​

  • Keep total geofence count reasonable (< 10,000 per workspace)
  • Use active/inactive status instead of deleting temporarily unused geofences
  • Group related geofences for easier bulk operations
  • Test complex polygons with the test point endpoint before production use

Testing Geofences​

Always test your geofences before connecting them to workflows:

curl -X POST https://api.spatialflow.io/api/v1/geofences/test-point \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "geometry": {
      "type": "Point",
      "coordinates": [-122.4194, 37.7749]
    }
  }'

Response shows which geofences contain the point:

{
  "point": {
    "latitude": 37.7749,
    "longitude": -122.4194
  },
  "results": [
    {
      "geofence_id": "123e4567-e89b-12d3-a456-426614174000",
      "geofence_name": "Downtown Office",
      "contains": true,
      "distance_meters": 0
    }
  ],
  "inside_count": 1,
  "total_tested": 47
}

Common Use Cases​

1. Delivery Zone Management​

Define service areas for delivery operations. Trigger notifications when drivers enter/exit zones, calculate dwell time, and optimize routing.

{
  "name": "Pizza Delivery - Downtown",
  "description": "30-minute delivery zone",
  "metadata": {
    "service_type": "delivery",
    "max_delivery_time_minutes": 30,
    "store_id": "store_123"
  }
}

2. Restricted Area Monitoring​

Create security perimeters that alert when unauthorized devices enter. Useful for construction sites, private property, or secure facilities.

{
  "name": "Construction Site - No Entry",
  "description": "Active construction zone - authorized personnel only",
  "metadata": {
    "security_level": "restricted",
    "contact": "security@example.com"
  }
}

3. Store Locations​

Define retail locations for customer engagement campaigns. Trigger welcome messages, collect visit analytics, or activate location-based offers.

{
  "name": "Retail Store #42 - Seattle",
  "description": "Flagship store in downtown Seattle",
  "metadata": {
    "store_number": "042",
    "manager": "Jane Smith",
    "offers_enabled": true
  }
}

4. Fleet Management​

Track vehicles entering depots, customer sites, or service areas. Automate check-in/check-out processes and monitor route adherence.

{
  "name": "Depot - North Bay",
  "description": "Primary vehicle depot",
  "metadata": {
    "depot_code": "NB001",
    "capacity": 50,
    "overnight_parking": true
  }
}

Signals and Anomaly Detection​

Geofences are not just for entry/exit detection — they also power SpatialFlow's anomaly detection signals:

  • Dwell Detection: When a device stays inside a geofence beyond a configured time threshold, a dwell signal fires. Thresholds are set per-workflow, allowing different alert levels for the same geofence.
  • Policy Violations: Policies bind a geofence to time windows and device/role filters. When a device is inside a geofence during a restricted time window, a policy violation signal fires.

These signals feed into workflows just like geofence entry/exit events, enabling sophisticated automation like after-hours access alerts or extended-stay notifications.

See Signals for the full list of signal types and how they work.

Coordinate System​

SpatialFlow uses EPSG:4326 (WGS84), the same coordinate system used by GPS devices and most mapping APIs.

Format: [longitude, latitude]

  • Longitude: -180 to 180 (east-west)
  • Latitude: -90 to 90 (north-south)
Common Mistake

Note the order: longitude first, then latitude. This is the GeoJSON standard but opposite of how coordinates are often spoken (lat, lng).

Correct: [-122.4194, 37.7749] (lng, lat) Incorrect: [37.7749, -122.4194] (lat, lng)

Validation​

SpatialFlow validates all geofences on creation and update:

Validation rules:

  • Geometry must be valid GeoJSON
  • Polygons must be closed (first and last points match)
  • Coordinates must be within valid ranges
  • Vertex count between 3 and 500
  • No self-intersecting polygons
  • Minimum 3 vertices for exterior ring

Common validation errors:

  • Polygon must be closed: First and last coordinates don't match
  • Invalid coordinates: Longitude or latitude out of range
  • Too many vertices: Exceeded 500 vertex limit
  • Self-intersecting polygon: Polygon edges cross each other

Next Steps​

Now that you understand geofences, explore related features:

API Endpoints​

Key geofence endpoints:

  • POST /api/v1/geofences - Create a geofence
  • GET /api/v1/geofences - List all geofences
  • GET /api/v1/geofences/{id} - Get a specific geofence
  • PATCH /api/v1/geofences/{id} - Update a geofence
  • DELETE /api/v1/geofences/{id} - Delete a geofence
  • POST /api/v1/geofences/test-point - Test a point against all geofences
  • GET /api/v1/geofences/groups - List all geofence groups
  • GET /api/v1/geofences/groups/{id}/geofences - Get geofences in a group

See the API Reference for complete details and examples.