From 25a261d600674215a5d1c344ebcd998c68f0d9ed Mon Sep 17 00:00:00 2001 From: Ilia Smirnov Date: Wed, 21 May 2025 17:01:48 +0200 Subject: [PATCH 1/4] feature: added polygon area type for location verification --- .../location-verification.yaml | 67 ++++++++++++++++++- 1 file changed, 64 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index 93a9e3d2..a51984ea 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). Support of circle type areas is mandatory for provider. + - 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 + boundary: + - 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,36 @@ components: longitude: 7.10066 radius: 50000 + Polygon: + 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 + required: + - boundary + properties: + boundary: + $ref: "#/components/schemas/PointList" + example: + areaType: POLYGON + boundary: + - latitude: 52.516770 + longitude: 13.378156 + - latitude: 52.516841 + longitude: 13.379433 + - latitude: 52.515917 + longitude: 13.37959 + - 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 @@ -597,6 +650,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 +691,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 +703,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 9781452002a05da01cb0b806887d15778003d6fb Mon Sep 17 00:00:00 2001 From: Ilya Smirnov <82020671+ilya-smirnov-berlin@users.noreply.github.com> Date: Tue, 3 Jun 2025 09:53:33 +0200 Subject: [PATCH 2/4] Descriptions of polygon areas improved Co-authored-by: Jose Luis Urien --- code/API_definitions/location-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index a51984ea..e839a9c7 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -8,7 +8,7 @@ info: 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). Support of circle type areas is mandatory for provider. - - 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. + - Polygon is defined by an ordered list of geographic points (latitude and longitude) that form its boundary. 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. From aea52a670edf4c1d1a4ce2f4ca92856e3b01af5e Mon Sep 17 00:00:00 2001 From: Ilya Smirnov <82020671+ilya-smirnov-berlin@users.noreply.github.com> Date: Tue, 3 Jun 2025 09:54:09 +0200 Subject: [PATCH 3/4] Fixed wrong error code for NOT_MANAGED_AREA in description Co-authored-by: Jose Luis Urien --- code/API_definitions/location-verification.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index e839a9c7..8b0c8944 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -12,7 +12,7 @@ info: * 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. + * If the provided polygonal type of area is not supported by operator, an error `422 LOCATION_VERIFICATION.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. From e32f69d653e23a3752e84385c8ea4915d96fe117 Mon Sep 17 00:00:00 2001 From: Ilia Smirnov Date: Tue, 3 Jun 2025 09:57:30 +0200 Subject: [PATCH 4/4] Polygon area type example contains maxAge --- code/API_definitions/location-verification.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index 8b0c8944..9b4b6476 100644 --- a/code/API_definitions/location-verification.yaml +++ b/code/API_definitions/location-verification.yaml @@ -139,7 +139,7 @@ paths: 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 + description: Verify if device identified by a phone number is within a polygon shaped area, providing a maxAge value: device: phoneNumber: "+123456789" @@ -154,6 +154,7 @@ paths: longitude: 13.37959 - latitude: 52.515849 longitude: 13.378308 + maxAge: 120 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