What does the circle returned with the geofence event represent?

[JoachimDahlgren]

Problem description
In the geofence event notification data a mandatory area object is to be returned. From the documentation it is described as

• areaType - Type of this area. CIRCLE - The area is defined as a circle.
• center - (Point)Coordinates (latitude, longitude) defining a location in a map.
• radius - number >= 1
  Expected accuracy for the subscription event of device location, in meters from center. Note: The area surface could be restricted locally depending on regulations. Implementations may enforce a larger minimum radius (e.g. 1000 meters).

This could be interpreted either as the geofence area used when creating the subscription or as the area in which the device is when the event is generated.

Expected action

• Discuss and decide if the area in the event is the geofence or the estimated location of the device.
• Adjust the description in such a way that it is clear what this area represents

Additional context
We also have an incorrect description of the purpose of the radius in the area object when creating a subscription. The radius is not really to set the "Expected accuracy for the subscription event of device location, in meters from center. " as written today but rather to set the border of the geofence.

As touched upon in the discussions on #133 Define Guidelines for geofencing implementation the API invoker today lacks a way to set and/or understand the accuracy of a triggered event. Including the device location as a point with an accuracy could a potential mitigation.

[maxl2287]

Hi @JoachimDahlgren,

thanks for raising this important clarification point.

In my understanding, the area included in a geofencing subscription event represents the geofence itself, not the current estimated device location.

This interpretation makes sense especially for events such as:

• subscription-started
• subscription-updated
• subscription-ended

Consider the following example:
An API consumer creates a subscription for this geofence area:

      "area": {
        "areaType": "CIRCLE",
        "center": {
          "latitude": 50.735851,
          "longitude": 7.10066
        },
        "radius": 2000
      }

When the subscription starts, the first emitted event might look like this:

{
  "id": "124003",
  "source": "https://dataUsageServer.supertelco.com",
  "type": "org.camaraproject.geofencing-subscriptions.v0.subscription-started",
  "specversion": "1.0",
  "datacontenttype": "application/json",
  "data": {
    "initiationReason": "SUBSCRIPTION_CREATED",
    "subscriptionId": "dv10-h556-rt89-1403",
    "device": {
      "phoneNumber": 123456789
    },
    "area": {
      "areaType": "CIRCLE",
      "center": {
        "latitude": 50.735851,
        "longitude": 7.10066
      },
      "radius": 2000
    }
  },
  "time": "2024-03-05T15:00:23.682Z"
}

At this point, the device has not yet entered or left the area — which indicates that the area here clearly describes the geofence configuration, not a dynamic device location.

Therefore, the documentation should clarify that:

In event notifications, the area object represents the geofence area associated with the subscription.

The device’s actual position (possibly with an accuracy value) could be provided separately if needed to indicate where the device was when the event was triggered.

[jlurien]

I agree with Max here. To me it should represent the geofence. One aspect that it is not explicitly specified in the API is whether the area in the response and events must be exactly the same filled by the client in the request, or implementation may make some adjustments to the geofence. I assume that it is expected to be the same but probably we should enhance the description of area in the spec.

[bigludo7]

We could probably propose a PR for this?
@maxl2287 are you able to do it or do you want me to submit it?