Define guidelines for geofencing implementation

[jlurien]

Problem description
As we saw with location-verification, the area where the network locates a device is not, or close to, a single point. It is an area that can be quite large compared with the geofence area. In order to decide when the device enters or leaves the geofence we have to agree on some rules based on the intersection of both areas.

Expected action
As we did with location-verification, we should discuss and agree on some guidelines for a common implementation.

Proposal (to start with):

In this case if we consider D (= area where network locates the device) and G (= geofence area), we may consider that:

• area-entered event is to be triggered when more than N% of D is within G, for the first time, or after area-left has been triggered.
• area-left event is to be triggered when, after area-entered event has been already triggered, then more than N% of D is outside G.

"N%" thresholds are to be decided. Instead of 50%, we may choose a higher % to leave some safe gap between both, for example 60% .

[jlurien]

For your consideration @bigludo7, @akoshunyadi, @alpaycetin74 , @javier-carrocalabor (and others of course :)

[alpaycetin74]

hello,
I am not sure why we refer to area-left in the definition of area-entered, and vice versa.
Maybe we could say:

1. area-entered event is to be triggered if the network establishes that more than N% of D is within G.
   Network shall also consider the value of the initialTriggerAreaEntered property in the API request:

• If initialTriggerAreaEntered is true, the time information D was established is irrelevant.
• If initialTriggerAreaEntered is false, the time information D was established must be later than event subscription time.

(On a side note, this also makes me think if initialTriggerAreaEntered is true, i.e.the client wants to know if the device was already in G, maybe we should define an upperbound for the age of location information. The network may have a location information saying the device is already inside G, but the information may be too old and stale.)

2. area-left event is to be triggered if the network establishes that more than N% of D is outside G and this information has been established after the event subscription time.

Thank you.

[jlurien]

The reference to the other event is to make clear that area-entered is only expected if the device enters the geofence for the first time, or if the device has left the geofence within the subscription lifetime and enters the geofence again. That is, 2 or more area-entered events should not be triggered if the device remains in the geofence. But I'm thinking now that a developer may subscribe to just one of the events, so it may not have received the other event, so we should not mention it.

So, properly it should say:

• A device is considered within the geofence when more than N% of D is within G. area-entered event is expected when the device enters G for the first time, or after the device has left the geofence within the subscription lifetime and enters again.

[bigludo7]

Another point that we should also probably discuss here is at subscription time.

Suppose we get a subscription for an area not covered or below a given percentage, or, for an area too small to be valid (N% will never be above x with current network ).
In these case the consumer will never be able to receive notification.

I tend to think that we must be pro-active on this and refuse the subscription with a explicit message. So we must add this capability in our API.

Probably this extra layer of checking could challenge our capability to answer synchronously to the call so also I'm wondering if we should not add capability to answer asynchronously to geofencing request.

[jlurien]

Interesting point. Adding such a capability, to create subscriptions asynchronously, would require adapting the model in Commonalities. But another option is to rely on the current notification system, accepting always the subscription request, synchronously, but defining new TerminationReason for subscription-ends, e.g. AREA_NOT_SUPPORTED

[bigludo7]

@jlurien we have a conversation yesterday in Population Density Data API for same purpose --> camaraproject/PopulationDensityData#20.

@jlurien Adding such a capability, to create subscriptions asynchronously, would require adapting the model in Commonalities.

I'm not sure for that as we have described[ implicit subscription].(https://github.com/camaraproject/Commonalities/blob/main/documentation/API-design-guidelines.md#instance-based-implicit-subscription)

It could be a good start point no?

[jlurien]

I think that implicit subscriptions are a different case, but for Resource-based (explicit) subscription, I see now we already have:

(*) As the subscription could be created synchronously or asynchronously both status codes 201 and 202 must be described in the OpenAPI specification.

But the 202 case is not detailed. In DeviceStatus they have specified both 201 and 202.

So, if we take the "MUST" in the guidelines above as a mandate, we should add it to Geofencing as well, but I have doubts about how this 202 scenario is expected to work. Looking into DeviceStatus I see that with 202 a subscriptionId is returned, but is not clear how a GET /subscriptions/{subscriptionId} would look like for a subscription that is not yet created. There is no "status" property for subscriptions. I guess that at most we could not return startedAt, indicating that subscription has not started, but this scenario probably needs a more detailed definition.

[jlurien]

@bigludo7 ,

I just saw your PR at camaraproject/Commonalities#189
where there is a status in the new Subscription model. That would solved the situation I mentioned above.

[ilya-smirnov-berlin]

We are planing to use the entrance/exiting intersection ratio (D/N) in our initial implementation as internal configuration value of API since the geofencing API doesn't include any concept how the user can define them yet.
Initially I would use ratios of 0,5 (0...1.0) for default logic for triggering of geofence events. Using internally configurable values we can have following scenarios

Enter/exit intersection ratio	Event	Behaviour
~0	Enter	As soon the location area intersects with the geofence area an entrance event is triggered
~0	Exit	As soon the location area has no more intersection with the geofence area an exit event is triggered
0.5	Enter	As soon the location area intersects with the geofence area for 50 or more percent an entrance event is triggered
0.5	Exit	As soon the location area intersects with the geofence area for 50 or less percent an exit event is triggered
1	Enter	As soon the location area is a subset of the geofence area an entrance event is triggered
1	Exit	As soon the location area comlpletley disjoint to the geofence area an exit event is triggered

All cases has some potential flaws. Knowing the principle the consumer of the geofencing API can "customise" the fence area (assuming they are not consumed from some third party geo systems/maps). Akos proposed to use predefined presets (as a list of enums) for "overlapping" parameters.

[akoshunyadi]

I think we could add such intersection ratio as a new parameter to the subscription creation. This would give the API consumer the possibility to adapt the API for his need. Otherwise I think the events won't fulfill the expectations.

[bigludo7]

@ilya-smirnov-berlin @akoshunyadi To be sure I got your proposal, we offer the API consumer to pick an option during subscription (between 3) that I can reformulate this way (for device entered):

• loose check -The intersection ratio moves from 0 to >0 (and >0.50) - meaning: The device is probably not in the zone but it is close to be
• medium check - The intersection ratio moves from <0.50 to ratio >=0.50 (but not equal to 1) - meaning: The device is most probably in the zone that out of it
• strict check - The intersection ratio moves to <1 to 1 - meaning: the device is for sure in the zone

[akoshunyadi]

@bigludo7 exactly, using such categories makes the complexity for the user manageable.

[jlurien]

The ratios make sense to the implementation but we have to design the best approach for the customer to use it, as choosing a numeric ratio may not be understandable. My feeling is that for customers, the device location is seen mostly as a point, so the concept of intersection is not that evident. We know that for networks this is not the case. Qualitative options, as @bigludo7 proposes, may be more friendly. cc @javier-carrocalabor

On the other hand, in location-verification we already have the concept of matchRate which is basically the ratio, but in this case. it is calculated by the network, so customer does not need to decide on it.

[ilya-smirnov-berlin]

Based on latest comments I suggest an enum attribute with three values for ratios ~0, 0.5, 1.0

      enum:
        - LOOSE
        - MEDIUM
        - STRICT

The attribute for the triggering can be optional with default value MEDIUM_CHECK (ratio 0.5)

{
  "webhook": {
    "notificationUrl": "https://application-server.com",
    "notificationAuthToken": "c8974e592c2fa383d4a3960714"
  },
  "subscriptionDetail": {
    "device": {
      "phoneNumber": "+12345678912"
    },
    "area": {
      "areaType": "CIRCLE",
      "center": {
        "latitude": 50.735851,
        "longitude": 7.10066
      },
      "radius": 2000
    },
    "triggerSensibility": "STRICT",
    "type": "org.camaraproject.geofencing.v0.area-entered"
  },
  "subscriptionExpireTime": "2024-03-22T05:40:58.469Z"
}

Enum value names / attribute name (triggerSensibility) can be refined. Since we have currently only one type of event (exit/enter) the value can relate to the selected event.