Geofencing

The geofencing functionality allows applications to track when a given device enters or leaves a location based on the coordinates and radius or a named point of interest that have been provided.

Geofencing works off the same location information as location retrieval and verification. This means that in some cases where the area is defined as a circle, accuracy is on cell tower level, so specifying too small of an area may result in incomplete or inaccurate results and in some countries or on some networks the minimum radius may be regulated. Therefore, this functionality is best applied to situations where a course-grained location notification is desired.

Subscribing to geofencing notificationsheader link

Creating basic geofencing subscriptionsheader link

The snippet below allows you to subscribe a specific device to geofencing. It creates a geofenced circle of 2000 meters centered on latitude 47.48627616952785 and longitude 19.07915612501993 and will send a notification to https://example.com/notify if the device enters this region.

import network_as_code as nac
from network_as_code.models.geofencing import EventType, Circle, Center

client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)

device = client.devices.get(phone_number="+3637123456")

subscription = client.geofencing.subscribe(
    device=device,
    sink="https://example.com/notify",
    types=[EventType.AREA_LEFT],
    area=Circle(center=Center(latitude=47.48627616952785, longitude=19.07915612501993), radius=2000)
)

You can alternatively subscribe a specific device to geofencing using an area defined by a point of interest. This can be for example an industrial zone or shopping district provided by its name as a simple string.

import network_as_code as nac
from network_as_code.models.geofencing import EventType, POI

client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)

device = client.devices.get(phone_number="+3637123456")

subscription = client.geofencing.subscribe(
    device=device,
    sink="https://example.com/notify",
    types=[EventType.AREA_LEFT],
    area=POI(poi_name="StatueOfLiberty")
)

Creating geofencing subscriptions with optional parametersheader link

It's also possible to pass in optional parameters to the subscription:

import network_as_code as nac
from datetime import datetime, timedelta, timezone
from network_as_code.models.geofencing import PlainCredential, EventType, Circle, Center

client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)

device = client.devices.get(phone_number="+3637123456")

subscription = client.geofencing.subscribe(
    device=device,
    sink="https://example.com/notify",
    types=[EventType.AREA_LEFT],
    area=Circle(center=Center(latitude=47.48627616952785, longitude=19.07915612501993), radius=2000),
    sink_credential=PlainCredential(identifier="client-id",secret="client-secret"),
    subscription_expire_time=datetime.now(timezone.utc) + timedelta(days=1),
    subscription_max_events=1,
    initial_event=True
)

Geofencing parametersheader link

Geofencing event typesheader link

Credential typesheader link

Receiving geofencing notificationsheader link

Geofencing notifications are delivered using CloudEvents to the event sink specified in the subscription. Network as Code currently only supports delivery via HTTP, which means that notifications will be sent as POST requests to the sink URL and will contain the event information as a JSON payload.

The notifications will also come with identifying information specified by the sink credentials.

There are three types of geofencing notifications that you may receive:

Area entry notification will have a request body of the following schema:

{
  "id": "event-id-random-123",
  "source": "/whatever-api/v1/subscriptions/123",
  "time": "2025-07-01T14:15:16.789Z",
  "specversion" : "1.0",
  "type": "org.camaraproject.geofencing-subscriptions.v0.area-entered",
  "datacontenttype" : "application/json",
  "data": {
    "subscriptionId": "subscriptionId-123",
    "device": {...},
    "area": {...}
  }
}

Area left notification schema is:

{
  "id": "event-id-random-123",
  "source": "/whatever-api/v1/subscriptions/123",
  "time": "2025-07-01T14:15:16.789Z",
  "specversion" : "1.0",
  "type": "org.camaraproject.geofencing-subscriptions.v0.area-left",
  "datacontenttype" : "application/json",
  "data": {
    "subscriptionId": "subscriptionId-123",
    "device": {...},
    "area": {...}
  }
}

And subscription termination will result in:

{
  "id": "event-id-random-123",
  "source": "/whatever-api/v1/subscriptions/123",
  "time": "2025-07-01T14:15:16.789Z",
  "specversion" : "1.0",
  "type": "org.camaraproject.geofencing-subscriptions.v0.subscription-ends",
  "datacontenttype" : "application/json",
  "data": {
    "subscriptionId": "subscriptionId-123",
    "device": {...},
    "area": {...}
    "terminationReason": "..."
  }
}

The termination reason may be one of the following:

Notification-keyword valuesheader link

Managing geofencing subscriptionsheader link

Get all active subscriptionsheader link

All of the currently active Geofencing subscriptions can be fetched using the get-all functionality. This will return a list containing the details of each subscription that hasn't yet been terminated.

import network_as_code as nac

client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)

subscriptions = client.geofencing.get_all()

Get subscription by IDheader link

Geofencing subscriptions can also be fetched by subscription ID, if you already know it. This will just return the single subscription with that ID, assuming that it has not been terminated.

import network_as_code as nac
from network_as_code.models.geofencing import EventType, POI

client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)

device = client.devices.get(phone_number="+3637123456")

subscription = client.geofencing.subscribe(
    device=device,
    sink="https://example.com/notify",
    types=[EventType.AREA_ENTERED],
    area=POI(poi_name="StatueOfLiberty")
)

subscription_id = subscription.event_subscription_id

same_subscription = client.geofencing.get(subscription_id)

Delete subscriptionheader link

Subscriptions can be manually terminated by deleting them. This is done by calling the delete method or endpoint.

import network_as_code as nac
from network_as_code.models.geofencing import EventType, Circle, Center

client = nac.NetworkAsCodeClient(
    token="<your-application-key-here>"
)

device = client.devices.get(phone_number="+3637123456")

subscription = client.geofencing.subscribe(
    device=device,
    sink="https://example.com/notify",
    types=[EventType.AREA_ENTERED],
    area=Circle(center=Center(latitude=47.48627616952785, longitude=19.07915612501993), radius=2000)
)

subscription.delete()

Last updated January 22, 2026