Add Sync26 new changes (Geohashlist)

code/API_definitions/predictive-connectivity-data.yaml

@@ -35,10 +35,15 @@
 
     # API Functionality
 
-    Once a developer specifies (1) the area as a polygon shape, (2) a precision level, (3) the service
+    Once a developer specifies (1) the area (either as a polygon shape or as a list of geohashes),
+    (2) a precision level (only when the area is a polygon), (3) the service
     level and (4) time interval in which they want to obtain the connectivity estimation,
     the API returns a data set consisting of a sequence of time ranges, with each
-    time range containing the input polygon subdivided into equal-sized grid cells.
+    time range containing the requested area subdivided into equal-sized grid cells.
+
+    When the area is provided as a list of geohashes (`areaType: GEOHASHLIST`), the response
+    contains one cell per requested geohash; each geohash determines the granularity of its own
+    response cell, and the `precision` request property MUST NOT be included.
 
     For each of the equal-sized cells of the grid, an analysis of Connectivity Levels
     is reported for each time slot within the range, this includes data classified into:
@@ -64,6 +69,21 @@
       implementation will not be returned. Therefore, if a polygon is located
       entirely outside the supported area, an empty array will be returned.
 
+    When the area is specified as a list of geohashes (`areaType: GEOHASHLIST`):
+
+      - All MNOs must support the `POLYGON` area type; support for `GEOHASHLIST` is optional.
+      If the MNO does not support `GEOHASHLIST`, the API returns the error response
+      `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE`.
+      - The requested geohashes do not need to be adjacent or contiguous; the API
+      returns one cell per requested geohash.
+      - Geohashes within the same request may have different precisions (string
+      lengths), as long as the MNO supports all of them. If any geohash uses a
+      precision not supported by the MNO, the API returns the error response
+      `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION`.
+      - Geohashes within the list that fall outside the MNO coverage area are returned
+      with `layerConnectivities` containing all items set to `ND`. If the entire list
+      is outside the coverage area, the response will have `status` set to `AREA_NOT_SUPPORTED`.
+
     The standard behaviour of the API is synchronous, although for large
     area requests the API may behave asynchronously. An API invoker can enforce
     asynchronous behaviour by providing a callback URL (sink) in the request,
@@ -277,7 +297,7 @@
                 - notificationsBearerAuth: []
 components:
   securitySchemes:
     openId:
       type: openIdConnect
       openIdConnectUrl: https://example.com/.well-known/openid-configuration
     notificationsBearerAuth:
@@ -298,7 +318,7 @@
       schema:
         $ref: "#/components/schemas/XCorrelator"
   schemas:
     XCorrelator:
       type: string
       pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
       example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"
@@ -327,8 +347,10 @@
         precision:
           type: integer
           description: >-
-            Precision required of response cells. Precision defines a geohash level and corresponds to the length of the geohash for each cell. More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash)"
-            If not included the default precision level 7 is used by default. In case of using a not supported level by the MNO, the API returns the error response `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION`.
+            Precision required of response cells. Precision defines a geohash level and corresponds to the length of the geohash for each cell. More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash).
+            If not included the default precision level 7 is used by default.
+            Values within the schema range (1–12) that are not supported by the MNO return the error response `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION`. Values outside the schema range are invalid per the OpenAPI definition and return `400 INVALID_ARGUMENT` via request validation.
+            This property MUST only be set when `area.areaType` is `POLYGON`. When `area.areaType` is `GEOHASHLIST`, each requested geohash determines the granularity of its own response cell; if `precision` is sent, the API returns a `400 INVALID_ARGUMENT` error.
           minimum: 1
           maximum: 12
           default: 7
@@ -376,14 +398,17 @@
         propertyName: areaType
         mapping:
           POLYGON: "#/components/schemas/Polygon"
+          GEOHASHLIST: "#/components/schemas/GeohashList"
     AreaType:
       type: string
       description: |
         Type of this area.
         POLYGON - The area is defined as a polygon.
+        GEOHASHLIST - The area is defined as a list of geohashes.
       enum:
         - POLYGON
+        - GEOHASHLIST
     Polygon:
       description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself.
       allOf:
         - $ref: "#/components/schemas/Area"
@@ -426,6 +451,30 @@
       format: double
       minimum: -180
       maximum: 180
+    GeohashList:
+      description: >-
+        Area defined as a list of geohashes. Geohashes do not need to be adjacent or contiguous and may have different precision levels (string lengths), as long as the MNO supports all of them. The `precision` request property MUST NOT be set when `areaType` is `GEOHASHLIST`; if set, the API returns a `400 INVALID_ARGUMENT` error.
+      allOf:
+        - $ref: "#/components/schemas/Area"
+        - type: object
+          required:
+            - geohashes
+          properties:
+            geohashes:
+              type: array
+              description: List of geohashes that define the area of interest.
+              minItems: 1
+              items:
+                $ref: "#/components/schemas/Geohash"
+    Geohash:
+      type: string
+      description: >-
+        Geohash string identifying a cell using the [Geohash system](https://en.wikipedia.org/wiki/Geohash),
+        encoding a geographic location into a short string. Characters are taken from the
+        base-32 geohash alphabet (`0-9` and `b-z` excluding `a`, `i`, `l`, `o`).
+        The length of the string determines the cell granularity (precision).
+      pattern: ^[0-9bcdefghjkmnpqrstuvwxyz]{1,12}$
+      example: ezdmemd
     ServiceLevel:
       description: >-
         Describes the requested communication service level. Although more
@@ -434,6 +483,8 @@
           - C2: Command and Control. Consists in connecting an unmanned aerial vehicle with its remote controller. This link allows data transmission in both directions, facilitating real-time operation and feedback.
           - STREAM_4K: Streaming in 4K quality.
           - BEST_EFFORT: This service level provides a qualitative estimation of coverage based on each operator's own prediction models or public coverage maps. It does not imply any guarantee of network performance or service availability. The values of GC, MC, NC, and ND should be interpreted as approximate indicators of expected connectivity quality, not as results derived from standardised thresholds.
+
+        An MNO may not support every service level listed in this enum. If the requested service level is not supported by the MNO, the API returns the error response `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL`.
       type: string
       enum:
         - C2
@@ -449,7 +500,7 @@
       enum:
         - 4G
         - 5G
     SinkCredential:
       type: object
       properties:
         credentialType:
@@ -469,7 +520,7 @@
           REFRESHTOKEN: '#/components/schemas/RefreshTokenCredential'
       required:
         - credentialType
     PlainCredential:
       type: object
       description: A plain credential as a combination of an identifier and a secret.
       allOf:
@@ -485,7 +536,7 @@
             secret:
               description: The secret might be a password or passphrase.
               type: string
     AccessTokenCredential:
       type: object
       description: An access token credential.
       allOf:
@@ -512,7 +563,7 @@
             - accessToken
             - accessTokenExpiresUtc
             - accessTokenType
     RefreshTokenCredential:
       type: object
       description: An access token credential with a refresh token.
       allOf:
@@ -582,14 +633,14 @@
         - layerThickness
         - timedConnectivityData
         - status
     AcceptedAsyncResponse:
       type: object
       properties:
         operationId:
           $ref: '#/components/schemas/OperationId'
       required:
         - operationId
     ConnectivityDataAsyncResponse:
       allOf:
         - $ref: '#/components/schemas/ConnectivityDataResponse'
         - type: object
@@ -662,13 +713,7 @@
         its connectivity data.
       properties:
         geohash:
-          type: string
-          description: >-
-            Coordinates of the cell represented as a string using the [Geohash
-            system](https://en.wikipedia.org/wiki/Geohash), encoding a
-            geographic location into a short string. The value length,
-            and thus, the cell granularity, is determined by the request body property `precision`.
-          example: ezdmemd
+          $ref: '#/components/schemas/Geohash'
         layerConnectivities:
           $ref: '#/components/schemas/LayerConnectivities'
         layerSignalStrengths:
@@ -718,14 +763,14 @@
         nullable: true
         description: Signal strength value in dBm, or null if no data is available
         example: -85.5
     Connectivity:
       type: string
       enum:
         - GC
         - MC
         - NC
         - ND
     ErrorInfo:
       type: object
       required:
         - status
@@ -839,6 +884,8 @@
           - Indicated request is too big for both synchronous and asynchronous processing ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_REQUEST", "message": "The indicated request is too big for both synchronous and asynchronous processing")
           - Indicated cell precision (Geohash level) is not supported ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION", "message": "Indicated cell precision (Geohash level) is not supported")
           - Indicated request is too big for synchronous processing and asynchronous processing is not enabled ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SYNC_RESPONSE", "message": "The indicated request is too big for synchronous processing and asynchronous processing is not enabled")
+          - The requested `areaType` is not supported by the MNO ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE", "message": "The requested areaType is not supported by the MNO")
+          - Indicated service level is not supported ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL", "message": "The service level provided is not supported")
       headers:
         x-correlator:
           $ref: '#/components/headers/x-correlator'
@@ -857,6 +904,8 @@
                       - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_REQUEST
                       - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION
                       - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SYNC_RESPONSE
+                      - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE
+                      - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL
           examples:
             PREDICTIVE_CONNECTIVITY_DATA_422_UNSUPPORTED_REQUEST:
               value:
@@ -878,6 +927,16 @@
                 message: >-
                   Indicated combination of area, time interval and precision is too big for synchronous processing
                   and asynchronous processing is not enabled
+            PREDICTIVE_CONNECTIVITY_DATA_422_UNSUPPORTED_AREA_TYPE:
+              value:
+                status: 422
+                code: PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE
+                message: The requested areaType is not supported by the MNO
+            PREDICTIVE_CONNECTIVITY_DATA_422_UNSUPPORTED_SERVICE_LEVEL:
+              value:
+                status: 422
+                code: PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL
+                message: The service level provided is not supported
     Generic400:
       description: Problem with the client request
       headers:
@@ -1036,7 +1095,7 @@
                 code: TOO_MANY_REQUESTS
                 message: Rate limit reached.
   examples:
     ConnectivityDataSupportedAreaResponseExample:
       value:
         layerThickness: 30
         timedConnectivityData:
@@ -1087,7 +1146,7 @@
                   - NC
                   - NC
         status: SUPPORTED_AREA
     ConnectivityDataPartOfAreaNotSupportedResponseExample:
       value:
         layerThickness: 30
         timedConnectivityData:
@@ -1138,12 +1197,12 @@
                   - NC
                   - NC
         status: PART_OF_AREA_NOT_SUPPORTED
     ConnectivityDataAreaNotSupportedResponseExample:
       value:
         layerThickness: 30
         timedConnectivityData: []
         status: AREA_NOT_SUPPORTED
     ConnectivityDataSupportedAreaAsyncResponseExample:
       value:
         layerThickness: 30
         timedConnectivityData:
@@ -1195,14 +1254,14 @@
                   - NC
         status: SUPPORTED_AREA
         operationId: 2322f362-eaab-4cf3-86d2-efcbdf3a7cb4
     ConnectivityDataOperationNotCompletedExample:
       value:
         layerThickness: 30
         timedConnectivityData: []
         status: OPERATION_NOT_COMPLETED
         statusInfo: Some error happened during the processing of the request
         operationId: 2322f362-eaab-4cf3-86d2-efcbdf3a7cb4
     ConnectivityDataWithSignalStrengthResponseExample:
       value:
         layerThickness: 30
         timedConnectivityData:
@@ -1248,7 +1307,7 @@
                   - -81.0
                   - -85.0
         status: SUPPORTED_AREA
     ConnectivityDataSupportedAreaResponseWithHeightExample:
       value:
         layerThickness: 30
         timedConnectivityData: