From 60e33d8a89dc9b6f56c3f3221826ed0b540e0fc3 Mon Sep 17 00:00:00 2001 From: Ilia Smirnov Date: Tue, 20 May 2025 09:27:28 +0200 Subject: [PATCH 1/4] feature: added polygon area type for location verification and geofencing --- .../geofencing-subscriptions.yaml | 102 +++++++++++++++++- .../location-verification.yaml | 65 ++++++++++- 2 files changed, 161 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml index d1ad1a58..92ded827 100644 --- a/code/API_definitions/geofencing-subscriptions.yaml +++ b/code/API_definitions/geofencing-subscriptions.yaml @@ -10,8 +10,9 @@ info: * If the provided area is out of the operator's coverage or it is not supported for any reason, an error `422 GEOFENCING_SUBSCRIPTIONS.AREA_NOT_COVERED` will be returned. * Legal restrictions regarding privacy, or other regulatory or implementation issues, may force the operator to set restrictions to the provided area, such as setting a minimum value to the accepted radius. In these cases, an error `422 GEOFENCING_SUBSCRIPTIONS.INVALID_AREA` will be returned and the error message will refer to the reason of the limitation. + * If the provided polygonal type of area is not supported by operator, an error `422 GEOFENCING_SUBSCRIPTIONS.NOT_MANAGED_AREA_TYPE` will be returned. - The area provided in the request is described by a circle determined by coordinates (latitude and longitude) and an accuracy defined by the radius. + The area provided in the request is described by a circle or a polygon. The circle area is determined by coordinates (latitude and longitude) and an accuracy defined by the radius. The polygon area is determined by an array of corner points in form of geo coordinates (latitude and longitude). Upon successfully creating a subscription, the API will provide an Event Subscription ID, and it will indicate the subscription's expiration date. @@ -145,6 +146,8 @@ paths: examples: CIRCLE_AREA_ENTERED: $ref: "#/components/examples/REQUEST_CIRCLE_AREA_ENTERED" + POLYGON_AREA_ENTERED: + $ref: "#/components/examples/REQUEST_POLYGON_AREA_ENTERED" required: true callbacks: notifications: @@ -169,6 +172,8 @@ paths: $ref: "#/components/examples/CIRCLE_AREA_ENTERED" CIRCLE_AREA_LEFT: $ref: "#/components/examples/CIRCLE_AREA_LEFT" + POLYGON_AREA_ENTERED: + $ref: "#/components/examples/POLYGON_AREA_ENTERED" SUBSCRIPTION_ENDS: $ref: "#/components/examples/SUBSCRIPTION_ENDS" SUBSCRIPTION_UNPROCESSABLE: @@ -745,14 +750,17 @@ components: propertyName: areaType mapping: CIRCLE: "#/components/schemas/Circle" + POLYGON: "#/components/schemas/Polygon" AreaType: type: string description: | Type of this area. CIRCLE - The area is defined as a circle. + POLYGON - The area is defined as a polygon. enum: - CIRCLE + - POLYGON Circle: description: Circular area @@ -779,6 +787,34 @@ components: longitude: 7.10066 radius: 50000 + Polygon: + description: Polygon based area defined by an ordered geo points array + allOf: + - $ref: "#/components/schemas/Area" + - type: object + properties: + coordinates: + type: array + items: + type: array + items: + $ref: "#/components/schemas/Point" + minItems: 3 + maxItems: 16 + required: + - coordinates + example: + areaType: POLYGON + coordinates: + - latitude: 52.516770 + longitude: 13.378156 + - latitude: 52.516841 + longitude: 13.379433 + - latitude: 52.515917 + longitude: 13.37959 + - latitude: 52.515849 + longitude: 13.378308 + Point: type: object description: Coordinates (latitude, longitude) defining a location in a map. @@ -1388,6 +1424,7 @@ components: - UNSUPPORTED_IDENTIFIER - GEOFENCING_SUBSCRIPTIONS.AREA_NOT_COVERED - GEOFENCING_SUBSCRIPTIONS.INVALID_AREA + - GEOFENCING_SUBSCRIPTIONS.NOT_MANAGED_AREA_TYPE examples: GENERIC_422_IDENTIFIER_MISMATCH: description: Inconsistency between device identifiers not pointing to the same device. @@ -1437,7 +1474,13 @@ components: value: status: 422 code: GEOFENCING_SUBSCRIPTIONS.INVALID_AREA - message: "The requested area is too small" + GEOFENCING_422_NOT_MANAGED_AREA_TYPE: + summary: Not managed area type + description: The requested area type is currently not supported by implementation. + value: + status: 422 + code: GEOFENCING_SUBSCRIPTIONS.NOT_MANAGED_AREA_TYPE + message: "The requested area type is not managed" Generic429: description: Too Many Requests headers: @@ -1491,8 +1534,35 @@ components: initialEvent: true subscriptionMaxEvents: 10 subscriptionExpireTime: "2024-03-22T05:40:58.469Z" + + REQUEST_POLYGON_AREA_ENTERED: + description: A sample geofence for entering for a polygon area. + value: + protocol: "HTTP" + sink: https://notificationSendServer12.supertelco.com + types: + - org.camaraproject.geofencing-subscriptions.v0.area-entered + config: + subscriptionDetail: + device: + phoneNumber: "+12345678912" + area: + areaType: POLYGON + coordinates: + - latitude: 52.516770 + longitude: 13.378156 + - latitude: 52.516841 + longitude: 13.379433 + - latitude: 52.515917 + longitude: 13.37959 + - latitude: 52.515849 + longitude: 13.378308 + initialEvent: true + subscriptionMaxEvents: 10 + subscriptionExpireTime: "2024-03-22T05:40:58.469Z" + CIRCLE_AREA_ENTERED: - description: The cloud event when a geofence area was entered. + description: The cloud event when a geofence area of circle type was entered. value: id: "123655" source: https://notificationSendServer12.supertelco.com @@ -1510,6 +1580,32 @@ components: latitude: 50.735851 longitude: 7.10066 radius: 2000 + + POLYGON_AREA_ENTERED: + description: The cloud event when a geofence area of polygon type was entered. + value: + id: "123655" + source: https://notificationSendServer12.supertelco.com + type: org.camaraproject.geofencing-subscriptions.v0.area-entered + specversion: "1.0" + datacontenttype: application/json + time: 2023-03-22T05:40:23.682Z + data: + subscriptionId: 987654321 + device: + phoneNumber: +123456789 + area: + areaType: POLYGON + coordinates: + - latitude: 52.516770 + longitude: 13.378156 + - latitude: 52.516841 + longitude: 13.379433 + - latitude: 52.515917 + longitude: 13.37959 + - latitude: 52.515849 + longitude: 13.378308 + CIRCLE_AREA_LEFT: description: The cloud event when a geofence area was left. value: diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index 93a9e3d2..faeec6b9 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -6,10 +6,13 @@ info: # Introduction - API consumers are able to verify whether the location of certain user device is within the area specified. Currently the only area supported as input is a circle determined by a set of coordinates (latitude and longitude) and some expected accuracy (radius). + API consumers are able to verify whether the location of certain user device is within the area specified. Currently two area types are supported as input: + - Circle is determined by a set of coordinates (latitude and longitude) and some expected accuracy (radius). + - Polygon is determined by an array of corner points in form of geo coordinates (latitude and longitude). This area type is not mandatory for implementation by provider. * If the provided area is out of the operator's coverage or it is not supported for any reason, an error `422 LOCATION_VERIFICATION.AREA_NOT_COVERED` will be returned. * Legal restrictions regarding privacy, or other regulatory or implementation issues, may force the operator to set restrictions to the provided area, such as setting a minimum value to the accepted radius. In these cases, an error `422 LOCATION_VERIFICATION.INVALID_AREA` will be returned and the error message will refer to the reason of the limitation. + * If the provided polygonal type of area is not supported by operator, an error `422 GEOFENCING_SUBSCRIPTIONS.NOT_MANAGED_AREA_TYPE` will be returned. The verification result depends on the network's ability and accuracy to locate the device at the requested area. @@ -45,7 +48,7 @@ info: The API exposes a single endpoint/operation: - - Verify whether the device location is within a requested area, currently a circle with center specified by the latitude and longitude, and radius specified by the accuracy. The operation returns a verification result and, optionally, a match rate estimation for the location verification in percent. + - Verify whether the device location is within a requested area defined as circle or polygon. The operation returns a verification result and, optionally, a match rate estimation for the location verification in percent. # Authorization and authentication @@ -134,6 +137,23 @@ paths: longitude: 7.10066 radius: 50000 maxAge: 120 + INPUT_PHONE_NUMBER_POLYGON: + summary: Phone number, polygon and maxAge + description: Verify if device identified by a phone number is within a polygon shaped area, not indicating a maxAge + value: + device: + phoneNumber: "+123456789" + area: + areaType: POLYGON + coordinates: + - latitude: 52.516770 + longitude: 13.378156 + - latitude: 52.516841 + longitude: 13.379433 + - latitude: 52.515917 + longitude: 13.37959 + - latitude: 52.515849 + longitude: 13.378308 INPUT_IP_ADDRESS_V4_CIRCLE: summary: IPv4 address, circle, without maxAge description: Verify if device identified by an IPv4 address is within a circle, not indicating a maxAge @@ -240,14 +260,17 @@ components: propertyName: areaType mapping: CIRCLE: "#/components/schemas/Circle" + POLYGON: "#/components/schemas/Polygon" AreaType: type: string description: | Type of this area. CIRCLE - The area is defined as a circle. + POLYGON - The area is defined as a polygon. enum: - CIRCLE + - POLYGON Circle: description: Circular area @@ -274,6 +297,34 @@ components: longitude: 7.10066 radius: 50000 + Polygon: + description: Polygon based area defined by an ordered geo points array + allOf: + - $ref: "#/components/schemas/Area" + - type: object + properties: + coordinates: + type: array + items: + type: array + items: + $ref: "#/components/schemas/Point" + minItems: 3 + maxItems: 16 + required: + - coordinates + example: + areaType: POLYGON + coordinates: + - latitude: 52.516770 + longitude: 13.378156 + - latitude: 52.516841 + longitude: 13.379433 + - latitude: 52.515917 + longitude: 13.37959 + - latitude: 52.515849 + longitude: 13.378308 + Point: type: object description: Coordinates (latitude, longitude) defining a location in a map @@ -597,6 +648,7 @@ components: - LOCATION_VERIFICATION.AREA_NOT_COVERED - LOCATION_VERIFICATION.INVALID_AREA - LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE + - LOCATION_VERIFICATION.NOT_MANAGED_AREA_TYPE examples: GENERIC_422_IDENTIFIER_MISMATCH: description: Inconsistency between identifiers not pointing to the same device @@ -637,7 +689,7 @@ components: message: "Unable to cover the requested area" LOCATION_VERIFICATION_422_INVALID_AREA: summary: Invalid area - description: The requested area is too small to be supported by the system. + description: The requested area is too small to be supported by the system value: status: 422 code: LOCATION_VERIFICATION.INVALID_AREA @@ -649,3 +701,10 @@ components: status: 422 code: LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE message: "Unable to provide expected freshness for location" + LOCATION_VERIFICATION_422_NOT_MANAGED_AREA_TYPE: + summary: Not managed area type + description: The requested area type is currently not supported by implementation + value: + status: 422 + code: LOCATION_VERIFICATION.NOT_MANAGED_AREA_TYPE + message: "The requested area type is not managed" From 95aacaeca143c74a4a1dce14f1b1b6dd3baccd48 Mon Sep 17 00:00:00 2001 From: Ilia Smirnov Date: Wed, 21 May 2025 09:48:20 +0200 Subject: [PATCH 2/4] fix: reversed changes for location verification --- .../location-verification.yaml | 65 +------------------ 1 file changed, 3 insertions(+), 62 deletions(-) diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index faeec6b9..93a9e3d2 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -6,13 +6,10 @@ info: # Introduction - API consumers are able to verify whether the location of certain user device is within the area specified. Currently two area types are supported as input: - - Circle is determined by a set of coordinates (latitude and longitude) and some expected accuracy (radius). - - Polygon is determined by an array of corner points in form of geo coordinates (latitude and longitude). This area type is not mandatory for implementation by provider. + API consumers are able to verify whether the location of certain user device is within the area specified. Currently the only area supported as input is a circle determined by a set of coordinates (latitude and longitude) and some expected accuracy (radius). * If the provided area is out of the operator's coverage or it is not supported for any reason, an error `422 LOCATION_VERIFICATION.AREA_NOT_COVERED` will be returned. * Legal restrictions regarding privacy, or other regulatory or implementation issues, may force the operator to set restrictions to the provided area, such as setting a minimum value to the accepted radius. In these cases, an error `422 LOCATION_VERIFICATION.INVALID_AREA` will be returned and the error message will refer to the reason of the limitation. - * If the provided polygonal type of area is not supported by operator, an error `422 GEOFENCING_SUBSCRIPTIONS.NOT_MANAGED_AREA_TYPE` will be returned. The verification result depends on the network's ability and accuracy to locate the device at the requested area. @@ -48,7 +45,7 @@ info: The API exposes a single endpoint/operation: - - Verify whether the device location is within a requested area defined as circle or polygon. The operation returns a verification result and, optionally, a match rate estimation for the location verification in percent. + - Verify whether the device location is within a requested area, currently a circle with center specified by the latitude and longitude, and radius specified by the accuracy. The operation returns a verification result and, optionally, a match rate estimation for the location verification in percent. # Authorization and authentication @@ -137,23 +134,6 @@ paths: longitude: 7.10066 radius: 50000 maxAge: 120 - INPUT_PHONE_NUMBER_POLYGON: - summary: Phone number, polygon and maxAge - description: Verify if device identified by a phone number is within a polygon shaped area, not indicating a maxAge - value: - device: - phoneNumber: "+123456789" - area: - areaType: POLYGON - coordinates: - - latitude: 52.516770 - longitude: 13.378156 - - latitude: 52.516841 - longitude: 13.379433 - - latitude: 52.515917 - longitude: 13.37959 - - latitude: 52.515849 - longitude: 13.378308 INPUT_IP_ADDRESS_V4_CIRCLE: summary: IPv4 address, circle, without maxAge description: Verify if device identified by an IPv4 address is within a circle, not indicating a maxAge @@ -260,17 +240,14 @@ components: propertyName: areaType mapping: CIRCLE: "#/components/schemas/Circle" - POLYGON: "#/components/schemas/Polygon" AreaType: type: string description: | Type of this area. CIRCLE - The area is defined as a circle. - POLYGON - The area is defined as a polygon. enum: - CIRCLE - - POLYGON Circle: description: Circular area @@ -297,34 +274,6 @@ components: longitude: 7.10066 radius: 50000 - Polygon: - description: Polygon based area defined by an ordered geo points array - allOf: - - $ref: "#/components/schemas/Area" - - type: object - properties: - coordinates: - type: array - items: - type: array - items: - $ref: "#/components/schemas/Point" - minItems: 3 - maxItems: 16 - required: - - coordinates - example: - areaType: POLYGON - coordinates: - - latitude: 52.516770 - longitude: 13.378156 - - latitude: 52.516841 - longitude: 13.379433 - - latitude: 52.515917 - longitude: 13.37959 - - latitude: 52.515849 - longitude: 13.378308 - Point: type: object description: Coordinates (latitude, longitude) defining a location in a map @@ -648,7 +597,6 @@ components: - LOCATION_VERIFICATION.AREA_NOT_COVERED - LOCATION_VERIFICATION.INVALID_AREA - LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE - - LOCATION_VERIFICATION.NOT_MANAGED_AREA_TYPE examples: GENERIC_422_IDENTIFIER_MISMATCH: description: Inconsistency between identifiers not pointing to the same device @@ -689,7 +637,7 @@ components: message: "Unable to cover the requested area" LOCATION_VERIFICATION_422_INVALID_AREA: summary: Invalid area - description: The requested area is too small to be supported by the system + description: The requested area is too small to be supported by the system. value: status: 422 code: LOCATION_VERIFICATION.INVALID_AREA @@ -701,10 +649,3 @@ components: status: 422 code: LOCATION_VERIFICATION.UNABLE_TO_FULFILL_MAX_AGE message: "Unable to provide expected freshness for location" - LOCATION_VERIFICATION_422_NOT_MANAGED_AREA_TYPE: - summary: Not managed area type - description: The requested area type is currently not supported by implementation - value: - status: 422 - code: LOCATION_VERIFICATION.NOT_MANAGED_AREA_TYPE - message: "The requested area type is not managed" From 3674017ac38cd9fea61892a23a1b97b138cda225 Mon Sep 17 00:00:00 2001 From: Ilia Smirnov Date: Wed, 21 May 2025 10:43:34 +0200 Subject: [PATCH 3/4] fix: polygon datatype replaced with current one from commonalities --- .../geofencing-subscriptions.yaml | 32 ++++++++++--------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml index 92ded827..c6bcfe51 100644 --- a/code/API_definitions/geofencing-subscriptions.yaml +++ b/code/API_definitions/geofencing-subscriptions.yaml @@ -12,7 +12,7 @@ info: * Legal restrictions regarding privacy, or other regulatory or implementation issues, may force the operator to set restrictions to the provided area, such as setting a minimum value to the accepted radius. In these cases, an error `422 GEOFENCING_SUBSCRIPTIONS.INVALID_AREA` will be returned and the error message will refer to the reason of the limitation. * If the provided polygonal type of area is not supported by operator, an error `422 GEOFENCING_SUBSCRIPTIONS.NOT_MANAGED_AREA_TYPE` will be returned. - The area provided in the request is described by a circle or a polygon. The circle area is determined by coordinates (latitude and longitude) and an accuracy defined by the radius. The polygon area is determined by an array of corner points in form of geo coordinates (latitude and longitude). + The area provided in the request is described by a circle or a polygon. The circle area is determined by coordinates (latitude and longitude) and an accuracy defined by the radius. The polygon area is determined by an list of corner points in form of geo coordinates (latitude and longitude). Support of circle type areas is mandatory for provider. Implementation of polygonal areas is optional. Upon successfully creating a subscription, the API will provide an Event Subscription ID, and it will indicate the subscription's expiration date. @@ -788,24 +788,18 @@ components: radius: 50000 Polygon: - description: Polygon based area defined by an ordered geo points array + description: Polygonal area. The Polygon should be a simple polygon defined by an ordered geo points list, i.e. should not intersect itself. allOf: - $ref: "#/components/schemas/Area" - type: object - properties: - coordinates: - type: array - items: - type: array - items: - $ref: "#/components/schemas/Point" - minItems: 3 - maxItems: 16 required: - - coordinates + - boundary + properties: + boundary: + $ref: "#/components/schemas/PointList" example: areaType: POLYGON - coordinates: + boundary: - latitude: 52.516770 longitude: 13.378156 - latitude: 52.516841 @@ -815,6 +809,14 @@ components: - latitude: 52.515849 longitude: 13.378308 + PointList: + description: List of points defining a polygon + type: array + items: + $ref: "#/components/schemas/Point" + minItems: 3 + maxItems: 15 + Point: type: object description: Coordinates (latitude, longitude) defining a location in a map. @@ -1548,7 +1550,7 @@ components: phoneNumber: "+12345678912" area: areaType: POLYGON - coordinates: + boundary: - latitude: 52.516770 longitude: 13.378156 - latitude: 52.516841 @@ -1596,7 +1598,7 @@ components: phoneNumber: +123456789 area: areaType: POLYGON - coordinates: + boundary: - latitude: 52.516770 longitude: 13.378156 - latitude: 52.516841 From 4a516d8968e64cc99a9a611171acf06a2a13fb5b Mon Sep 17 00:00:00 2001 From: Ilya Smirnov <82020671+ilya-smirnov-berlin@users.noreply.github.com> Date: Tue, 3 Jun 2025 09:49:27 +0200 Subject: [PATCH 4/4] Descriptions of polygon area improved Co-authored-by: Jose Luis Urien --- code/API_definitions/geofencing-subscriptions.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/geofencing-subscriptions.yaml b/code/API_definitions/geofencing-subscriptions.yaml index c6bcfe51..12257890 100644 --- a/code/API_definitions/geofencing-subscriptions.yaml +++ b/code/API_definitions/geofencing-subscriptions.yaml @@ -12,7 +12,7 @@ info: * Legal restrictions regarding privacy, or other regulatory or implementation issues, may force the operator to set restrictions to the provided area, such as setting a minimum value to the accepted radius. In these cases, an error `422 GEOFENCING_SUBSCRIPTIONS.INVALID_AREA` will be returned and the error message will refer to the reason of the limitation. * If the provided polygonal type of area is not supported by operator, an error `422 GEOFENCING_SUBSCRIPTIONS.NOT_MANAGED_AREA_TYPE` will be returned. - The area provided in the request is described by a circle or a polygon. The circle area is determined by coordinates (latitude and longitude) and an accuracy defined by the radius. The polygon area is determined by an list of corner points in form of geo coordinates (latitude and longitude). Support of circle type areas is mandatory for provider. Implementation of polygonal areas is optional. + The area provided in the request is described by a circle or a polygon. The circle area is determined by coordinates (latitude and longitude) and an accuracy defined by the radius. The polygon area is defined by an ordered list of geographic points (latitude and longitude) that form its boundary. Support of circle type areas is mandatory for provider. Implementation of polygonal areas is optional. Upon successfully creating a subscription, the API will provide an Event Subscription ID, and it will indicate the subscription's expiration date.