Skip to main content

Create Your First Geofence

Learn how to create geofences using both the SpatialFlow Dashboard and the API. For a deeper look at geofence types, geometry formats, and advanced options, see Geofences In Depth.

Prerequisites​

Option A — Create a Polygon via the Dashboard​

  1. Log in to the SpatialFlow Dashboard
  2. Click Locations in the top navigation bar, then select Geofences
  3. On the Geofence Management page, click the + Create Geofence button in the top-right corner
  4. The editor opens with a two-column layout: a map with a drawing toolbar on the left, and a Geofence Details form on the right

Draw the Boundary​

The drawing toolbar provides four tools:

ToolIconDescription
SelectPointerDrag vertices to reshape your geofence
PolygonPentagon (active by default)Draw a custom polygon boundary
CircleCirclePlace a circle geofence on the map
ClearTrashRemove the current drawing and start over

With the Polygon tool selected:

  1. Click on the map to place each vertex of your boundary
  2. Continue clicking to add more vertices
  3. Double-click to complete the polygon
Editing Your Polygon

Switch to the Select tool (pointer icon) to drag vertices and reshape your polygon. Click the trash icon to clear and start over.

Fill In the Details​

In the Geofence Details panel on the right, fill in:

  • Name (required) — e.g., SF Office Building
  • Description (optional) — e.g., Main office perimeter
  • Group (optional) — e.g., Office Locations

Click Create Geofence to save. The button is disabled until both a name and geometry are provided.

After creation you'll see a success notification and be redirected to the geofences list.

Creating a Circle via the Dashboard

Select the Circle tool from the toolbar, then click on the map to place the center. A Radius input (default: 1000 meters) appears in the toolbar — adjust it to set the size of your circle geofence.

Option B — Create a Circle via the API​

Send the Create Request​

curl -X POST https://api.spatialflow.io/api/v1/geofences/ \
  -H "Authorization: Bearer $SPATIALFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "NYC Warehouse Zone",
    "description": "500m radius around the warehouse entrance",
    "geometry": {
      "type": "Circle",
      "center": [-74.006, 40.714],
      "radius_meters": 500
    },
    "metadata": {
      "location": "New York Warehouse"
    }
  }'
Coordinate Order

SpatialFlow follows the GeoJSON standard: coordinates are [longitude, latitude], not [latitude, longitude]. Swapping them will place your geofence on the wrong side of the world.

Review the Response​

A successful 201 Created response returns the full geofence object:

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "NYC Warehouse Zone",
  "description": "500m radius around the warehouse entrance",
  "geometry": {
    "type": "Circle",
    "center": [-74.006, 40.714],
    "radius_meters": 500.0
  },
  "geometry_type": "Circle",
  "radius_meters": 500.0,
  "webhook_url": null,
  "webhook_events": [],
  "metadata": {
    "location": "New York Warehouse"
  },
  "is_active": true,
  "group_id": null,
  "group_name": null,
  "created_at": "2025-11-09T10:00:00Z",
  "updated_at": "2025-11-09T10:00:00Z"
}

Save the id — you'll need it when setting up workflows and testing.

Creating a Polygon via the API

To create a polygon instead, replace the geometry field with a standard GeoJSON Polygon. See the example in the Quick Start overview.

Verify Your Geofence​

Test a Point Against Your Geofences​

Use the test-point endpoint to check whether a coordinate falls inside any of your active geofences:

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

Response:

{
  "point": {
    "type": "Point",
    "coordinates": [-74.006, 40.714]
  },
  "inside_geofences": 1,
  "total_geofences": 3,
  "results": [
    {
      "geofence_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "geofence_name": "NYC Warehouse Zone",
      "is_inside": true,
      "distance_meters": 0
    },
    {
      "geofence_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "geofence_name": "Downtown Delivery Zone",
      "is_inside": false,
      "distance_meters": 1250.5
    }
  ],
  "matched_geofences": [
    {
      "geofence_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "geofence_name": "NYC Warehouse Zone",
      "group_id": null,
      "group_name": null,
      "distance_meters": 0
    }
  ]
}
  • results lists every active geofence with its is_inside status and distance from the point
  • matched_geofences lists only the geofences that contain the point, with group information included
warning

The test-point endpoint checks the point against all of your active geofences. To test against specific geofences only, include a geofence_ids array in your request body.

You've successfully created and verified a geofence:

  • ✅ Created a geofence via the Dashboard or API
  • ✅ Tested a point against your geofences
  • ✅ Confirmed your geofence is working

Next Steps​

Ready to put your geofences to work? Continue with these guides: