diff --git a/code/API_definitions/location-verification.yaml b/code/API_definitions/location-verification.yaml index 93a9e3d2..9b4b6476 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 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. + * 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. @@ -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,24 @@ 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, providing 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 + 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 @@ -240,14 +261,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 +298,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 +651,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 +692,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 +704,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"