Skip to main content

Get told when a vehicle reaches a site

Scopes: geofences:write, geofences:read, webhooks:write.

1. Draw the site​

A circle of 300 m round a depot:

GEOFENCE_ID=$(curl -s -X POST "https://api.zaitrack.app/v1/geofences" \
  -H "Authorization: Bearer $KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Riyadh depot", "category": "depot", "kind": "circle",
       "center": {"lat": 24.7136, "lng": 46.6753}, "radiusM": 300}' | jq -r '.id')

kind is circle (with center and radiusM), polygon (with vertices) or route-corridor (with polyline and bufferM). category is one of depot, customer-site, prohibited, restricted-hours, toll-zone, hazmat-route, service-area or driver-home.

2. Subscribe to entries and exits​

curl -s -X POST "https://api.zaitrack.app/v1/webhooks" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://hooks.example.com/zaitrack", "description": "Depot arrivals",
       "events": ["zaitrack.geofence.entered.v1", "zaitrack.geofence.exited.v1"]}' | jq '{id, secret}'

Store the secret: it is shown once. Your endpoint now receives a signed POST each time a vehicle enters or leaves any of your geofences; check data for the geofence and verify the signature.

3. Read the visits​

The visits list gives each entry with its exit, for a geofence, a device or a vehicle:

curl -s "https://api.zaitrack.app/v1/geofences/visits?geofenceId=$GEOFENCE_ID&from=2026-10-01T00:00:00Z" \
  -H "Authorization: Bearer $KEY" | jq '.items'

open=true lists only the vehicles still inside. To test a point without waiting for a vehicle:

curl -s "https://api.zaitrack.app/v1/geofences/containing?lat=24.7140&lng=46.6750" \
  -H "Authorization: Bearer $KEY" | jq