From a2d67c705f7c39318d023742b980250782938da5 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Wed, 3 Jul 2024 13:30:55 +0200 Subject: [PATCH 1/3] include yaml --- .../most-frequent-location.yaml | 605 ++++++++++++++++++ 1 file changed, 605 insertions(+) create mode 100644 code/API_definitions/most-frequent-location.yaml diff --git a/code/API_definitions/most-frequent-location.yaml b/code/API_definitions/most-frequent-location.yaml new file mode 100644 index 0000000..5372082 --- /dev/null +++ b/code/API_definitions/most-frequent-location.yaml @@ -0,0 +1,605 @@ +openapi: 3.0.3 +info: + title: Most Frequent Location + description: | + The Most Frequent Location API provides customers with the ability to verify the frequency of a device's location within a specific area. + + # Introduction + + This API verifies if a device is present most of the time in a certain location. This location insight is useful as an approach to the residence location of the user. + + This API can be used in anti-fraud cases where a service provider needs further evidence about the reported place of residence of the customer. Also, for service provision or personalization tasks when the service provider needs to manage their offer depending on the habits of the customer. + + Such use cases are transversal to different sectors such as: + + - Financial institutions: to mitigate risks about identity fraud, helping in their compliance with AML/KYC regulation. + - Insurance companies: to assess risks and prevent fraudulent claims. + - E-commerce and retail: to ensure accurate shipping and delivery, fraud prevention and targeted marketing. + - Digital Content Delivery companies: to verify service provisioning and billing, and to comply with regulation. + - Utilities: to verify service provisioning and billing, and to prevent service theft. + - Real estate: to screen potential tenants and ensure that lease agreements are in compliance with local laws. + + # Relevant terms and definitions + + * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. + + * **Area**: It specifies the geographical surface where a device may be physically located. + + * **Verification**: The process triggered on the API server to calculate the frequency of time a device is at a given location. + + # API functionality + + The API allows customers to verify how often a device is in a specific location. The location can be specified using an area of type: + - `CIRCLE`: A circle defined by a central point specified by the latitude and longitude, and radius specified by the accuracy. + - `POSTAL_CODE`: A zip code or postal code that delimits a geographic area. + + The operation returns several scores representing how frequently the device was connected to antennas whose coverage cover the requested area in certain time slots. The range of score values is between "0" and "100", where higher scores indicate a more frequent presence in the location. + + This is the structure of the different scores: + - `scoreDetail`: It is a detailed breakdown of the scores distributed in specific time slots. Each score is calculated using an algorithm that analyzes location patterns, considering the historical location data for different time slots over the past 30 days. It is composed of: + - `daytime`: the frequency that covers working hours during the day. + - `night`: the frequency that covers nighttime hours. + - `weekend`: the frequency that covers days typically considered as the weekend. + - `general`: the frequency that covers all hours every day of the week. + - `totalScore`: It is the summary metric derived from analysis of the device's connections to antennas covering the requested area across all time slots. It is a combination based on all the `scoreDetail` scores. + + The `score` value maps to the frequency as follows: + - `score = 0`: The device has never been in the specified location. + - `score = 100`: The device is almost always in the specified location. + + # Further info and support + + (FAQs will be added in a later version of the documentation) + termsOfService: http://swagger.io/terms/ + contact: + email: project-email@sample.com + license: + name: Apache 2.0 + url: https://www.apache.org/licenses/LICENSE-2.0.html + version: 0.1.0 +externalDocs: + description: Product documentation at CAMARA + url: https://github.com/camaraproject/ +servers: + - url: "{apiRoot}/most-frequent-location/v0" + variables: + apiRoot: + default: http://localhost:9091 + description: API root +tags: + - name: Frequent location verification + description: Verification of the most frequent location of a device +paths: + /verify: + post: + security: + - openId: + - most-frequent-location:verify + tags: + - Frequent location verification + summary: Verify the most frequent location of a device + description: |- + Verify how often a device is within a requested area location. The location can be defined by a postal code or a circular area defined by a central point and radius. The operation returns a score representing how frequently the device was connected to antennas whose coverage covers the requested area and a detailed breakdown of all the individual score values used to calculate the total scored separated in time slots. + operationId: verifyFrequentLocation + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/VerifyFrequentLocationRequest' + examples: + INPUT_PHONE_NUMBER_POSTAL_CODE: + summary: Phone number and postal code + description: Verify how often the device, identified by a phone number, has been in a location delimited by a postal code + value: + device: + phoneNumber: '+123456789' + area: + areaType: POSTAL_CODE + postalCode: '12345' + INPUT_PHONE_NUMBER_CIRCLE: + summary: Phone number and circle area + description: Verify how often the device, identified by a phone number, has been in a location delimited by a circular area + value: + device: + phoneNumber: '+123456789' + area: + areaType: CIRCLE + center: + latitude: 50.735851 + longitude: 7.10066 + radius: 500 + INPUT_IP_ADDRESS_V4_POSTAL_CODE: + summary: IPv4 address and postal code + description: Verify how often the device, identified by an IPv4 address, has been in a location delimited by a postal code + value: + device: + ipv4Address: + publicAddress: '123.234.1.2' + publicPort: 1234 + area: + areaType: POSTAL_CODE + postalCode: '12345' + INPUT_IP_ADDRESS_V4_CIRCLE: + summary: IPv4 address and circle area + description: Verify how often the device, identified by an IPv4 address, has been in a location delimited by a circular area + value: + device: + ipv4Address: + publicAddress: '123.234.1.2' + publicPort: 1234 + area: + areaType: CIRCLE + center: + latitude: 50.735851 + longitude: 7.10066 + radius: 500 + responses: + '200': + description: Most frequent location verification result + content: + application/json: + schema: + $ref: '#/components/schemas/VerifyFrequentLocationResponse' + examples: + HIGH_SCORE: + summary: High score with detail + description: The device has been at the requested location with high frequency for most of the time slots. + value: + totalScore: 86 + scoreDetail: + daytime: 60 + night: 90 + weekend: 80 + general: 75 + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + '400': + $ref: '#/components/responses/VerifyFrequentLocationBadRequest400' + '401': + $ref: '#/components/responses/Generic401' + '403': + $ref: '#/components/responses/VerifyFrequentLocationPermissionDenied403' + '404': + $ref: '#/components/responses/VerifyFrequentLocationNotFound404' + '422': + $ref: '#/components/responses/VerifyFrequentLocationUnprocessableEntity422' + '500': + $ref: '#/components/responses/Generic500' + '503': + $ref: '#/components/responses/Generic503' + parameters: + - $ref: '#/components/parameters/x-correlator' +components: + securitySchemes: + openId: + type: openIdConnect + openIdConnectUrl: https://example.com/.well-known/openid-configuration + schemas: + VerifyFrequentLocationRequest: + type: object + required: + - device + - area + properties: + device: + $ref: '#/components/schemas/Device' + area: + $ref: '#/components/schemas/Area' + VerifyFrequentLocationResponse: + type: object + required: + - totalScore + - scoreDetail + properties: + totalScore: + $ref: '#/components/schemas/TotalScore' + scoreDetail: + $ref: '#/components/schemas/ScoreDetail' + Device: + description: |- + End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. + + The developer can choose to provide the below specified device identifiers: + + * `ipv4Address` + * `ipv6Address` + * `phoneNumber` + * `networkAccessIdentifier` + + NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + type: object + properties: + phoneNumber: + $ref: '#/components/schemas/PhoneNumber' + networkAccessIdentifier: + $ref: '#/components/schemas/NetworkAccessIdentifier' + ipv4Address: + $ref: '#/components/schemas/DeviceIpv4Addr' + ipv6Address: + $ref: '#/components/schemas/DeviceIpv6Address' + minProperties: 1 + PhoneNumber: + description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'. + type: string + pattern: '^\+[1-9][0-9]{4,14}$' + example: "+123456789" + NetworkAccessIdentifier: + description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access + identifier is not subjected to portability ruling in force, and is individually managed by each operator. + type: string + example: 123456789@domain.com + DeviceIpv4Addr: + type: object + description: |- + The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers). + + If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress. + + If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object) + + In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone. + properties: + publicAddress: + $ref: '#/components/schemas/SingleIpv4Addr' + privateAddress: + $ref: '#/components/schemas/SingleIpv4Addr' + publicPort: + $ref: '#/components/schemas/Port' + anyOf: + - required: + - publicAddress + - privateAddress + - required: + - publicAddress + - publicPort + example: + publicAddress: 84.125.93.10 + publicPort: 59765 + SingleIpv4Addr: + description: A single IPv4 address with no subnet mask + type: string + format: ipv4 + example: 84.125.93.10 + Port: + description: TCP or UDP port number + type: integer + minimum: 0 + maximum: 65535 + DeviceIpv6Address: + description: |- + The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix). + type: string + format: ipv6 + example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 + Area: + description: |- + The geographic area where the `device` can be physically located. The boundaries of the area can be defined in different ways, such as by a circle or a postal code. + type: object + properties: + areaType: + $ref: '#/components/schemas/AreaType' + required: + - areaType + discriminator: + propertyName: areaType + mapping: + CIRCLE: '#/components/schemas/Circle' + POSTAL_CODE: '#/components/schemas/PostalCode' + AreaType: + type: string + description: |- + Type of this area. + - `CIRCLE`: The area is defined as a circle. + - `POSTAL_CODE`: A zip code or postal code that delimits a geographic area. + enum: + - CIRCLE + - POSTAL_CODE + Circle: + description: Circular area + allOf: + - $ref: '#/components/schemas/Area' + - type: object + properties: + center: + $ref: '#/components/schemas/Point' + radius: + type: integer + description: Expected accuracy for the verification in meters, from location (radius) + minimum: 500 + maximum: 200000 + required: + - center + - radius + example: + areaType: CIRCLE + center: + latitude: 50.735851 + longitude: 7.10066 + radius: 50000 + Point: + type: object + description: Coordinates (latitude, longitude) defining a location in a map + required: + - latitude + - longitude + properties: + latitude: + $ref: '#/components/schemas/Latitude' + longitude: + $ref: '#/components/schemas/Longitude' + example: + latitude: 50.735851 + longitude: 7.10066 + Latitude: + description: Latitude component of a location + type: number + format: double + minimum: -90 + maximum: 90 + example: 50.735851 + Longitude: + description: Longitude component of location + type: number + format: double + minimum: -180 + maximum: 180 + example: 7.10066 + PostalCode: + description: Area associated to an administrative or geographical code + allOf: + - $ref: '#/components/schemas/Area' + - type: object + properties: + postalCode: + type: string + description: Zip code or postal code. + required: + - postalCode + TotalScore: + type: integer + description: |- + The value is a summary metric derived from analysis of the device's connections to antennas covering the requested area across all time slots. It is a combination based on all the `scoreDetail` scores. + The range of score values is between "0" and "100", where higher scores indicate a more frequent presence in the location. + minimum: 0 + maximum: 100 + example: 86 + ScoreDetail: + type: object + description: |- + A detailed breakdown of all the individual score values used to calculate the `totalScore`, separated in time slots. + Each value represents the frequency with which the device was connected to antennas covering the requested area for a specific time slot based on the historical location data of the last 30 days. + The range of score values is between "0" and "100", where higher scores indicate a more frequent presence in the location. + required: + - daytime + - night + - weekend + - general + properties: + daytime: + type: integer + description: Represents the frequency that covers working hours during the day. + minimum: 0 + maximum: 100 + example: 60 + night: + type: integer + description: Represents the frequency that covers nighttime hours. + minimum: 0 + maximum: 100 + example: 90 + weekend: + type: integer + description: Represents the frequency that covers days typically considered as the weekend. + minimum: 0 + maximum: 100 + example: 80 + general: + type: integer + description: Represents the frequency that covers all hours every day of the week. + minimum: 0 + maximum: 100 + example: 75 + ErrorInfo: + type: object + required: + - message + - status + - code + properties: + message: + type: string + description: A human readable description of what the event represent + status: + type: integer + description: HTTP response status code + code: + type: string + description: Friendly Code to describe the error + responses: + VerifyFrequentLocationBadRequest400: + description: |- + Bad Request. + In addition to regular scenario of `INVALID_ARGUMENT`, other scenarios may exist: + + - Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested ("code": "OUT_OF_RANGE","message": "Client specified an invalid range.") + - The postal code value does not exist or is invalid ("code": "MOST_FREQUENT_LOCATION.POSTAL_CODE_NOT_VALID","message": "Requested postal code value does not exist or is invalid."). + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + GENERIC_400_INVALID_ARGUMENT: + description: Invalid Argument. Generic Syntax Exception + value: + status: 400 + code: INVALID_ARGUMENT + message: Client specified an invalid argument, request body or query param. + GENERIC_400_OUT_OF_RANGE: + description: Out of Range. Specific Syntax Exception used when a given field has a pre-defined range or a invalid filter criteria combination is requested + value: + status: 400 + code: OUT_OF_RANGE + message: Client specified an invalid range. + POSTAL_CODE_NOT_VALID: + description: The postal code value does not exist or is invalid + value: + status: 400 + code: MOST_FREQUENT_LOCATION.POSTAL_CODE_NOT_VALID + message: Requested postal code value does not exist or is invalid. + Generic401: + description: Unauthorized + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_401_UNAUTHENTICATED: + description: Request cannot be authenticated + value: + status: 401 + code: UNAUTHENTICATED + message: Request not authenticated due to missing, invalid, or expired credentials. + GENERIC_401_AUTHENTICATION_REQUIRED: + description: New authentication is needed, authentication is no longer valid + value: + status: 401 + code: AUTHENTICATION_REQUIRED + message: New authentication is required. + VerifyFrequentLocationPermissionDenied403: + description: |- + Forbidden. + In addition to regular scenario of `PERMISSION_DENIED`, another scenarios may exist: + + - Phone number cannot be deducted from access token context.("code": "INVALID_TOKEN_CONTEXT","message": "Phone number is not consistent with access token.") + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + GENERIC_403_PERMISSION_DENIED: + description: Permission denied. OAuth2 token access does not have the required scope or when the user fails operational security + value: + status: 403 + code: PERMISSION_DENIED + message: Client does not have sufficient permissions to perform this action. + GENERIC_403_INVALID_TOKEN_CONTEXT: + description: Reflect some inconsistency between information in some field of the API and the related OAuth2 Token + value: + status: 403 + code: INVALID_TOKEN_CONTEXT + message: Phone number is not consistent with access token. + VerifyFrequentLocationNotFound404: + description: |- + Not found. + In addition to regular scenario of `NOT_FOUND`, other scenarios may exist: + + - Device identifier not found ("code": "DEVICE_NOT_FOUND","message": "Device identifier not found."). + - There is not enough information to calculate the score ("code": "MOST_FREQUENT_LOCATION.INFORMATION_NOT_AVAILABLE","message": "Requested information is not available"). + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + GENERIC_404_NOT_FOUND: + description: Resource is not found + value: + status: 404 + code: NOT_FOUND + message: The specified resource is not found. + GENERIC_404_DEVICE_NOT_FOUND: + description: Device identifier not found + value: + status: 404 + code: DEVICE_NOT_FOUND + message: Device identifier not found. + INFORMATION_NOT_AVAILABLE: + description: There is not enough information to calculate the score + value: + status: 404 + code: MOST_FREQUENT_LOCATION.INFORMATION_NOT_AVAILABLE + message: Requested information is not available. + VerifyFrequentLocationUnprocessableEntity422: + description: |- + Unprocessable Content. + In addition to regular scenario of `UNPROCESSABLE_ENTITY`, other scenarios may exist: + + - The device identifiers provided do not identify a single device ("code": "DEVICE_IDENTIFIERS_MISMATCH","message": "Provided device identifiers are not consistent."). + - The device identifiers provided are not supported ("code": "DEVICE_NOT_APPLICABLE","message": "The service is not available for the provided device."). + headers: + x-correlator: + $ref: '#/components/headers/x-correlator' + content: + application/json: + schema: + $ref: '#/components/schemas/ErrorInfo' + examples: + GENERIC_422_DEVICE_IDENTIFIERS_MISMATCH: + description: Inconsistency between device identifiers not pointing to the same device + value: + status: 422 + code: DEVICE_IDENTIFIERS_MISMATCH + message: Provided device identifiers are not consistent. + GENERIC_422_DEVICE_NOT_APPLICABLE: + description: Service is not available for the provided device + value: + status: 422 + code: DEVICE_NOT_APPLICABLE + message: The service is not available for the provided device. + Generic500: + description: Internal Server Error + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_500_INTERNAL: + description: Problem in Server side. Regular Server Exception + value: + status: 500 + code: INTERNAL + message: Unknown server error. Typically a server bug. + Generic503: + description: Service Unavailable + headers: + x-correlator: + $ref: "#/components/headers/x-correlator" + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorInfo" + examples: + GENERIC_503_UNAVAILABLE: + description: Service is not available. Temporary situation usually related to maintenance process in the server side + value: + status: 503 + code: UNAVAILABLE + message: Service Unavailable. + headers: + x-correlator: + description: Correlation id for the different services + schema: + type: string + parameters: + x-correlator: + name: x-correlator + in: header + description: Correlation id for the different services + schema: + type: string From 836d30d2af097f5d7c170c009ad316d7931a8f30 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Wed, 17 Jul 2024 19:08:39 +0200 Subject: [PATCH 2/3] update proposal --- .../most-frequent-location.yaml | 196 ++++++------------ 1 file changed, 63 insertions(+), 133 deletions(-) diff --git a/code/API_definitions/most-frequent-location.yaml b/code/API_definitions/most-frequent-location.yaml index 5372082..6a4c082 100644 --- a/code/API_definitions/most-frequent-location.yaml +++ b/code/API_definitions/most-frequent-location.yaml @@ -2,7 +2,7 @@ openapi: 3.0.3 info: title: Most Frequent Location description: | - The Most Frequent Location API provides customers with the ability to verify the frequency of a device's location within a specific area. + The Most Frequent Location API provides customers with the ability to verify the frequency of a device's location within a specific geographic area. # Introduction @@ -21,27 +21,19 @@ info: # Relevant terms and definitions - * **Device**: A device refers to any physical entity that can connect to a network and participate in network communication. + * **Device**: Any physical entity that can connect to a network and participate in network communication. - * **Area**: It specifies the geographical surface where a device may be physically located. + * **Geographical reference**: Using coordinates or a reference code, the geographical surface where a device can be physically located is specified. * **Verification**: The process triggered on the API server to calculate the frequency of time a device is at a given location. # API functionality - The API allows customers to verify how often a device is in a specific location. The location can be specified using an area of type: - - `CIRCLE`: A circle defined by a central point specified by the latitude and longitude, and radius specified by the accuracy. + The API allows customers to verify how often a device is in a specific location. The location can be specified using a geographical reference of type: + - `COVERAGE_ZONE`: It is specified by latitude and longitude coordinates. The coverage area is generated by one or more antennas closest to the specified coordinates, determining the device's connection to these antennas. - `POSTAL_CODE`: A zip code or postal code that delimits a geographic area. - The operation returns several scores representing how frequently the device was connected to antennas whose coverage cover the requested area in certain time slots. The range of score values is between "0" and "100", where higher scores indicate a more frequent presence in the location. - - This is the structure of the different scores: - - `scoreDetail`: It is a detailed breakdown of the scores distributed in specific time slots. Each score is calculated using an algorithm that analyzes location patterns, considering the historical location data for different time slots over the past 30 days. It is composed of: - - `daytime`: the frequency that covers working hours during the day. - - `night`: the frequency that covers nighttime hours. - - `weekend`: the frequency that covers days typically considered as the weekend. - - `general`: the frequency that covers all hours every day of the week. - - `totalScore`: It is the summary metric derived from analysis of the device's connections to antennas covering the requested area across all time slots. It is a combination based on all the `scoreDetail` scores. + The operation returns a score representing how frequently the device was connected to antennas whose coverage cover the requested area in certain time slots. The range of score values is between "0" and "100", where higher scores indicate a more frequent presence in the location. The `score` value maps to the frequency as follows: - `score = 0`: The device has never been in the specified location. @@ -79,7 +71,7 @@ paths: - Frequent location verification summary: Verify the most frequent location of a device description: |- - Verify how often a device is within a requested area location. The location can be defined by a postal code or a circular area defined by a central point and radius. The operation returns a score representing how frequently the device was connected to antennas whose coverage covers the requested area and a detailed breakdown of all the individual score values used to calculate the total scored separated in time slots. + Verify how often a device is within a requested geographic area location. The location can be defined by a postal code or a latitude and longitude coordinates. The operation returns a score representing how frequently the device was connected to antennas whose coverage covers the requested area. operationId: verifyFrequentLocation requestBody: required: true @@ -94,21 +86,19 @@ paths: value: device: phoneNumber: '+123456789' - area: - areaType: POSTAL_CODE + geoReference: + type: POSTAL_CODE postalCode: '12345' - INPUT_PHONE_NUMBER_CIRCLE: - summary: Phone number and circle area - description: Verify how often the device, identified by a phone number, has been in a location delimited by a circular area + INPUT_PHONE_NUMBER_COVERAGE_ZONE: + summary: Phone number and coverage zone + description: Verify how often the device, identified by a phone number, has been in a location delimited by a coverage zone specified by latitude and longitude coordinates value: device: phoneNumber: '+123456789' - area: - areaType: CIRCLE - center: - latitude: 50.735851 - longitude: 7.10066 - radius: 500 + geoReference: + type: COVERAGE_ZONE + latitude: 50.735851 + longitude: 7.10066 INPUT_IP_ADDRESS_V4_POSTAL_CODE: summary: IPv4 address and postal code description: Verify how often the device, identified by an IPv4 address, has been in a location delimited by a postal code @@ -117,23 +107,21 @@ paths: ipv4Address: publicAddress: '123.234.1.2' publicPort: 1234 - area: - areaType: POSTAL_CODE + geoReference: + type: POSTAL_CODE postalCode: '12345' - INPUT_IP_ADDRESS_V4_CIRCLE: - summary: IPv4 address and circle area - description: Verify how often the device, identified by an IPv4 address, has been in a location delimited by a circular area + INPUT_IP_ADDRESS_V4_COVERAGE_ZONE: + summary: IPv4 address and coverage zone + description: Verify how often the device, identified by an IPv4 address, has been in a location delimited by a coverage zone specified by latitude and longitude coordinates value: device: ipv4Address: publicAddress: '123.234.1.2' publicPort: 1234 - area: - areaType: CIRCLE - center: - latitude: 50.735851 - longitude: 7.10066 - radius: 500 + geoReference: + type: COVERAGE_ZONE + latitude: 50.735851 + longitude: 7.10066 responses: '200': description: Most frequent location verification result @@ -144,14 +132,9 @@ paths: examples: HIGH_SCORE: summary: High score with detail - description: The device has been at the requested location with high frequency for most of the time slots. + description: The device has been at the requested location with high frequency for most of the time. value: - totalScore: 86 - scoreDetail: - daytime: 60 - night: 90 - weekend: 80 - general: 75 + score: 86 headers: x-correlator: $ref: '#/components/headers/x-correlator' @@ -181,22 +164,19 @@ components: type: object required: - device - - area + - geoReference properties: device: $ref: '#/components/schemas/Device' - area: - $ref: '#/components/schemas/Area' + geoReference: + $ref: '#/components/schemas/GeoReference' VerifyFrequentLocationResponse: type: object required: - - totalScore - - scoreDetail + - score properties: - totalScore: - $ref: '#/components/schemas/TotalScore' - scoreDetail: - $ref: '#/components/schemas/ScoreDetail' + score: + $ref: '#/components/schemas/Score' Device: description: |- End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. @@ -208,7 +188,9 @@ components: * `phoneNumber` * `networkAccessIdentifier` - NOTE: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + NOTE1: the MNO might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different MNOs. In this case the identifiers MUST belong to the same device. + + NOTE2: for the Commonalities release v0.4, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines. type: object properties: phoneNumber: @@ -273,63 +255,47 @@ components: type: string format: ipv6 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 - Area: + GeoReference: description: |- - The geographic area where the `device` can be physically located. The boundaries of the area can be defined in different ways, such as by a circle or a postal code. + Specific Geographical reference. It can be defined in different ways, such as by a postal code or coverage zone specified by latitude and longitude coordinates. type: object properties: - areaType: - $ref: '#/components/schemas/AreaType' + type: + $ref: '#/components/schemas/GeoReferenceType' required: - - areaType + - type discriminator: - propertyName: areaType + propertyName: type mapping: - CIRCLE: '#/components/schemas/Circle' + COVERAGE_ZONE: '#/components/schemas/CoverageZone' POSTAL_CODE: '#/components/schemas/PostalCode' - AreaType: + GeoReferenceType: type: string description: |- - Type of this area. - - `CIRCLE`: The area is defined as a circle. + Type of this geographical reference. + - `COVERAGE_ZONE`: It is specified by latitude and longitude coordinates. The coverage area is generated by one or more antennas closest to the specified coordinates, determining the device's connection to these antennas. - `POSTAL_CODE`: A zip code or postal code that delimits a geographic area. enum: - - CIRCLE + - COVERAGE_ZONE - POSTAL_CODE - Circle: - description: Circular area + CoverageZone: + description: Coverage zone specified by latitude and longitude coordinates allOf: - - $ref: '#/components/schemas/Area' + - $ref: '#/components/schemas/GeoReference' - type: object properties: - center: - $ref: '#/components/schemas/Point' - radius: - type: integer - description: Expected accuracy for the verification in meters, from location (radius) - minimum: 500 - maximum: 200000 + latitude: + $ref: '#/components/schemas/Latitude' + longitude: + $ref: '#/components/schemas/Longitude' + example: + latitude: 50.735851 + longitude: 7.10066 required: - - center - - radius - example: - areaType: CIRCLE - center: - latitude: 50.735851 - longitude: 7.10066 - radius: 50000 - Point: - type: object - description: Coordinates (latitude, longitude) defining a location in a map - required: - - latitude - - longitude - properties: - latitude: - $ref: '#/components/schemas/Latitude' - longitude: - $ref: '#/components/schemas/Longitude' + - latitude + - longitude example: + type: COVERAGE_ZONE latitude: 50.735851 longitude: 7.10066 Latitude: @@ -349,7 +315,7 @@ components: PostalCode: description: Area associated to an administrative or geographical code allOf: - - $ref: '#/components/schemas/Area' + - $ref: '#/components/schemas/GeoReference' - type: object properties: postalCode: @@ -357,50 +323,14 @@ components: description: Zip code or postal code. required: - postalCode - TotalScore: + Score: type: integer description: |- - The value is a summary metric derived from analysis of the device's connections to antennas covering the requested area across all time slots. It is a combination based on all the `scoreDetail` scores. + The value is a summary metric derived from analysis of the device's connections to antennas covering the requested area across all time slots. The range of score values is between "0" and "100", where higher scores indicate a more frequent presence in the location. minimum: 0 maximum: 100 example: 86 - ScoreDetail: - type: object - description: |- - A detailed breakdown of all the individual score values used to calculate the `totalScore`, separated in time slots. - Each value represents the frequency with which the device was connected to antennas covering the requested area for a specific time slot based on the historical location data of the last 30 days. - The range of score values is between "0" and "100", where higher scores indicate a more frequent presence in the location. - required: - - daytime - - night - - weekend - - general - properties: - daytime: - type: integer - description: Represents the frequency that covers working hours during the day. - minimum: 0 - maximum: 100 - example: 60 - night: - type: integer - description: Represents the frequency that covers nighttime hours. - minimum: 0 - maximum: 100 - example: 90 - weekend: - type: integer - description: Represents the frequency that covers days typically considered as the weekend. - minimum: 0 - maximum: 100 - example: 80 - general: - type: integer - description: Represents the frequency that covers all hours every day of the week. - minimum: 0 - maximum: 100 - example: 75 ErrorInfo: type: object required: From 21fa08a6e6816a9ba3f08c1bbc0b5dc43d303833 Mon Sep 17 00:00:00 2001 From: Fernando Prado Date: Fri, 20 Sep 2024 12:43:31 +0200 Subject: [PATCH 3/3] change initial version --- code/API_definitions/most-frequent-location.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/most-frequent-location.yaml b/code/API_definitions/most-frequent-location.yaml index 6a4c082..cbe7c0e 100644 --- a/code/API_definitions/most-frequent-location.yaml +++ b/code/API_definitions/most-frequent-location.yaml @@ -48,12 +48,12 @@ info: license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html - version: 0.1.0 + version: wip externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/ servers: - - url: "{apiRoot}/most-frequent-location/v0" + - url: "{apiRoot}/most-frequent-location/vwip" variables: apiRoot: default: http://localhost:9091