diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index b968f6c..2892b00 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -2,140 +2,131 @@ openapi: 3.0.3 info: title: Predictive Connectivity Data description: | + The Predictive Connectivity Data API provides estimated connectivity quality information for a specified geographic area, time interval and height, delivered by 4G/5G networks. + # Introduction - With the Dynamic Predictive Connectivity Data API, the consumer can retrieve an estimation of connectivity delivered by 4/5G networks along a volume/area for a future date, time and height. + The Predictive Connectivity Data API allows API consumers to retrieve estimations of connectivity quality in each grid cell of a given area for a future time interval. The resulting data is prepared by the API provider, derived from network data and/or prediction models trained on such data. The API supports both synchronous and asynchronous processing depending on the size and complexity of the request. - This functionality can be used for multiple use cases, some of the possible use cases for this API are: + - The defined **area** is either a polygon (a list of geographical coordinates) or a list of geohashes. + - The provided **time interval** is a future time interval defined by `startTime` and `endTime`. + - An optional **height** in metres above ground level can be specified to obtain connectivity data for a specific altitude layer. + - The resulting estimations include a **connectivity level** (`GC`, `MC`, `NC`, or `ND`) for each cell, each time slot, and each vertical layer. Optionally, if supported by the implementation and requested by the API Consumer, raw **signal strength** values in dBm can also be returned. - - Network Airspace Connectivity Information for Drones: supporting drone flight planning with detailed analysis of mobile network coverage in the airspace across specific geographic areas. + This API supports a wide range of use cases, including but not limited to: - - Mobile Network Analysis for Autonomous Cars: enabling route planning through in-depth evaluation of mobile network availability. + - **BVLOS (Beyond Visual Line of Sight) drone operations**, supporting drone flight planning with detailed analysis of mobile network coverage in the airspace across specific geographic areas. + - **Autonomous vehicle route planning**, enabling route optimization through in-depth evaluation of mobile network availability along planned routes. - The list above is just a few examples, the API can be used for other use cases as well. + These examples illustrate typical applications, but the API can be used in many other scenarios where predictive connectivity estimation is relevant. - # Relevant Definitions and concepts + # Relevant Terms and Definitions - * **AGL**: Means "Above Ground Level" and describes the vertical height - above the ground. + **Connectivity Level** + A qualitative classification of expected connectivity quality for a given cell, time slot and layer, relative to the requested `serviceLevel` and `networkType`: + - **GC** (Good Connectivity): Service level met even in unfavorable conditions. + - **MC** (Marginal Connectivity): Service level might not be met. + - **NC** (No Connectivity): Service level not met. + - **ND** (No Data): No connectivity data available. - * **Service Level**: Describes, in measurable terms, the quality of service - a telecommunication provider furnishes a consumer within a given time period. + **Service Level** + Describes, in measurable terms, the quality of service a telecommunication provider furnishes a consumer. The currently defined service levels are: + - **C2**: Command and Control. Connecting an unmanned aerial vehicle with its remote controller. + - **STREAM_4K**: Streaming in 4K quality. + - **BEST_EFFORT**: A qualitative estimation of coverage based on operator prediction models or public coverage maps, without guarantees of network performance. - * **Network Type**: Refers to the type of connectivity (4G/5G) for which to retrieve data. + The API provider (mobile network operator) may not support every service level. If the requested service level is not supported, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL`. - * **Signal Strength**: Raw signal strength measurements in dBm that can be optionally included in the response when supported by the implementation. + **Network Type** + The type of connectivity (4G or 5G) for which to retrieve data. If not specified, connectivity quality is returned considering both 4G and 5G networks. - * **Notification URL and token**: Developers may provide a callback URL (`sink`) for receiving an async response. - This is an optional parameter. If `sink` is included, it is RECOMMENDED for the client to provide as well the `sinkCredential` - property to protect the notification endpoint. In the current version, `sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT` if provided. + **AGL (Above Ground Level)** + The vertical height above the ground, in metres. Used to define the prediction height and to describe the vertical layering of connectivity data. - Using `credentialType: PRIVATE_KEY_JWT` requires the JWT authentication parameters to be pre-configured - out-of-band between the API consumer and the API provider as part of the onboarding process. No response of - this API returns `sinkCredential`, so the provider's `jwksUri` is never conveyed in-band. Unlike an event - subscription, this operation creates no resource to read back, the same static `jwksUri` would be repeated on - every `202` response, and the callback may be delivered before the API consumer has processed that response. - If `PRIVATE_KEY_JWT` is requested and no JWK Set is configured for the API consumer, the API returns the - error response `422 PRIVATE_KEY_JWT_NOT_CONFIGURED`. A failure to authenticate against the API consumer's - authorization server when the callback is delivered cannot be detected while the request is being processed, - and is therefore reported in the callback with property `status` set to `OPERATION_NOT_COMPLETED`. + **Layer** + A vertical subdivision of the airspace above a grid cell. All layers have the same thickness (`layerThickness` metres) and are ordered consecutively starting from the ground (index 0 = 0 m AGL). The layer at index N covers the altitude range from N x `layerThickness` to (N+1) x `layerThickness` metres AGL. - When an asynchronous response is requested, the 202 response of the API will include an `operationId` property. This `operationId` property will - also be sent in the callback notification. The purpose of the `operationId` is to correlate an asynchronous response with its corresponding request. + **Signal Strength** + Raw signal strength predictions in dBm that can be optionally included in the response when supported by the implementation and requested via `includeSignalStrength`. + **Area Types** + - **POLYGON**: Area defined by a list of latitude/longitude points forming a simple polygon. The polygon is subdivided into a grid of cells. The set of cells corresponds to the geohashes, at the requested precision, that cover the polygon. + - **GEOHASHLIST**: Area defined as a list of geohash strings. Geohashes may be individual, non-contiguous geographical areas each with their own (possibly different) precision. - # API Functionality + **Grid Cell** + A subdivision of the requested area. + - For polygon areas, the grid is the set of geohash cells, at the applicable precision level, that cover the polygon. All cells have the same precision level. + - For geohash lists, each geohash corresponds to a single cell at its own precision level. - 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 requested area subdivided into equal-sized grid cells. + **Geohash** + A geohash is a string-encoded representation of a geographical area/point on the globe. The (32-base) geohash model represents the globe as a grid of 32 fixed rectangular areas, referred to as cells. Each cell is identified by a single letter or digit. Zooming in to one cell (recursively) gives a more granular (or higher precision) 32-cell grid at the next level with each cell again identified by a single letter or digit. + The geohash is a string that identifies a cell at a given zoom level by concatenating the identifiers of all previous level grid cells selected. The deeper the zoom, the longer the string and the higher the granularity/precision of the cell. The maximum zoom/precision level supported by this API is 12, which gives grid cells with a maximum dimension of 37.2 mm or less. The length (number of characters) of the geohash indicates its precision (zoom level/granularity). More information can be found at [Geohash system](https://en.wikipedia.org/wiki/Geohash). - 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. + **Precision** + Defines the granularity level of grid cells. + - **POLYGON**: The precision level is given by the `precision` request property. If not included, the default precision level 7 is used. + - **GEOHASHLIST**: Each geohash's own length determines its precision. The `precision` 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: + **Mobile Network Coverage Area** + The geographic area where the Mobile Network Operator (MNO) provides connectivity services. Cells outside this area are returned with all connectivity values set to `ND`. - - `GC`: Means good connectivity. Service level met even in unfavorable conditions. - - `MC`: Means marginal connectivity. Service level might not be met. - - `NC`: Means no connectivity. Service level not met. - - `ND`: No connectivity data. + **Synchronous vs Asynchronous Processing** + - **Synchronous**: The API returns the result immediately in the response. + - **Asynchronous**: For large requests or when explicitly requested via `sink`, the API returns a `202` response with an `operationId` and later delivers the result to the callback URL, including the same `operationId`. - Optionally, if supported by the implementation and requested by the client, raw signal strength values in dBm can also be returned for each layer. + **OperationId** + A unique identifier generated by the API Provider to correlate an asynchronous request with its callback notification. It is mandatory in the 202 response and in the callback payload. It differs from `x-correlator` (which is optional, supplied by the API Consumer, and not guaranteed to be present or unique). - These values are calculated based on network data and/or prediction models trained on - such data. + **Callback URL and Token** + A callback URL (`sink`) may be provided to receive asynchronous results. When `sink` is used, it is RECOMMENDED for the API Consumer to also provide `sinkCredential` to secure the callback endpoint. Supported credential types are `ACCESSTOKEN` and `PRIVATE_KEY_JWT`. - The polygon provided must comply with certain restrictions, which must be - previously validated by the developer: + # API Functionality - - The polygon will not exceed a certain area. - - The polygon cannot have an arbitrary complexity (unlimited number of - sides, complex shapes, etc.). - - The polygon must be associated with a location where the telco provides - mobile connectivity services. Cells outside the area supported by the - implementation will not be returned. Therefore, if a polygon is located - entirely outside the supported area, an empty array will be returned. + To retrieve predictive connectivity data, the API consumer specifies: + 1. The **area** (polygon or geohash list) + 2. The **precision** (only for polygon areas; defaults to 7 if omitted) + 3. The **service level** (currently one of C2, STREAM_4K, or BEST_EFFORT) + 4. The **time interval** (`startTime` and `endTime`) + 5. Optionally, a **height** in metres AGL to limit predictions to a single layer + 6. Optionally, a **network type** (4G or 5G; both if omitted) + 7. Optionally, **includeSignalStrength** to request raw dBm values - When the area is specified as a list of geohashes (`areaType: GEOHASHLIST`): + The API returns a sequence of time slots covering the specified interval. Each time slot contains connectivity data for all the grid cells covering the requested area. - - 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`. + - For polygon areas, the API generates a grid of geohash cells at the requested precision level that cover the polygon. + - For geohash lists, each geohash corresponds to a single cell, and the `precision` property MUST NOT be included. - 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, - in this case the API sends a callback to the callback URL provided with the - result of the request. See the **Notification URL and token** definition - above for the details about `sink`, `sinkCredential` and `operationId`. + Connectivity levels are calculated based on network data and/or prediction models trained on such data. - ## Error handling: + Polygon areas must meet certain constraints: + - Maximum polygon area size (implementation-specific). + - Must have a minimum of 3 and can have a maximum of 15 geographical points defining the polygon. + - Must lie at least partially within the mobile network coverage area; otherwise, the response has `status` set to `AREA_NOT_SUPPORTED` and an empty array is returned. - Three different `422` error responses distinguish why a request cannot be served. They are - mutually exclusive and are evaluated in this order: + For geohash lists: + - Support for `POLYGON` is mandatory for all API providers, whilst support for `GEOHASHLIST` is optional. If the API provider does not support `GEOHASHLIST`, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE`. + - Geohashes may be non-contiguous and have varying precision. + - Unsupported geohash precisions result in `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION`. + - Geohashes outside coverage are returned with `layerConnectivities` containing all items set to `ND`. + - If all geohashes are outside coverage, the response status is `AREA_NOT_SUPPORTED`. - - `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_ASYNC_RESPONSE`: the API consumer requested the - asynchronous behaviour by providing `sink`, but the API provider does not support asynchronous - processing at all. This error depends only on the capabilities of the implementation, never on - the size of the request: it is returned even for a request small enough to be served - synchronously. The API consumer can retry the same request without `sink` to obtain a - synchronous response. + The API normally behaves synchronously. However, large requests may trigger asynchronous processing. API Consumers may request asynchronous behavior by providing a `sink` callback URL. If asynchronous processing is not supported, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_ASYNC_RESPONSE`. - - `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SYNC_RESPONSE`: the combination of area, precision, - startTime and endTime involves an amount of processing that cannot be handled synchronously, - and asynchronous processing is not enabled. Unlike the previous error, this one depends on the - size of the request, so a smaller request would succeed. + Three mutually exclusive `422` errors indicate why a request cannot be served. They are evaluated in this order: + - **PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_ASYNC_RESPONSE**: `sink` is provided but asynchronous processing is not supported by the API provider. It does not depend on the size of the request; the API consumer can retry the same request without `sink` to obtain a synchronous response. + - **PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SYNC_RESPONSE**: The request is too large for synchronous processing, and asynchronous processing has not been requested. A smaller request for a synchronous response may succeed. + - **PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_REQUEST**: The request is too large for both synchronous and asynchronous processing. The requested coverage area and/or precision must be reduced. - - `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_REQUEST`: the combination of area, precision, - startTime and endTime is too big to be processed **even asynchronously**. Retrying with `sink` - does not help; only a smaller request does. + If an error occurs during asynchronous processing, the callback includes `status = OPERATION_NOT_COMPLETED` and a `statusInfo` field with additional details. - If an error happens during the asynchronous processing of the request. The - API callback will have property status with value OPERATION_NOT_COMPLETED - as an error cannot be returned in the callback. The callback will also - include the statusInfo property to add extra information about the error. + # Resources and Operations Overview - NOTE: In case the property "networkType" is not included, the quality of connectivity - will be returned considering both 4G and 5G networks. + The API exposes a single POST endpoint (`/retrieve`) for retrieving predictive connectivity data for a specified area, service level, network type, and time interval. + The API call result is an array of time slots (`timedConnectivityData`), with each time slot containing an array of cells (`cellConnectivityData`), and each cell containing the connectivity levels per vertical layer (see **Connectivity Level** in the definitions above). - # Resources and Operations overview + When an asynchronous response is requested (using `sink`, see Callback URL and Token in the Relevant Terms and Definitions section above), the 202 response of the API will include an `operationId` property. This `operationId` property will also be sent in the callback payload, correlating the asynchronous response with its corresponding request. If provided, `sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT`. - The API provides one endpoint that accepts POST requests for obtaining the - connectivity in a concrete area for a concrete service level and network - type/s. + Using `credentialType: PRIVATE_KEY_JWT` requires the JWT authentication parameters (a.k.a. JWK Set) to be pre-configured by an agreement between the API consumer and the API provider as part of the onboarding process. The API never returns `sinkCredential`, so the API provider's `jwksUri` is never conveyed in the response. Unlike an event subscription, the `/retrieve` operation creates no resource to read back, the same static `jwksUri` would be repeated on every `202` response, and the callback may be delivered before the API consumer has processed that response. If `PRIVATE_KEY_JWT` is provided and no JWK Set is configured for the API consumer, the API returns the error response `422 PRIVATE_KEY_JWT_NOT_CONFIGURED`. A failure to authenticate against the API consumer's authorization server when the callback is delivered cannot be detected while the request is being processed, and is therefore reported in the callback with property `status` set to `OPERATION_NOT_COMPLETED`. @@ -333,7 +324,7 @@ components: serviceLevel: $ref: '#/components/schemas/ServiceLevel' area: - $ref: '#/components/schemas/Area' + $ref: '#/components/schemas/GeoArea' startTime: $ref: "../common/CAMARA_common.yaml#/components/schemas/DateTime" endTime: @@ -346,7 +337,7 @@ components: 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). When `area.areaType` is `POLYGON`, if not included the default precision level 7 is used. - 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. + Values within the schema range (1-12) that are not supported by the API provider 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 @@ -385,20 +376,20 @@ components: - area - startTime - endTime - Area: + GeoArea: description: Base schema for all areas type: object properties: areaType: - $ref: "#/components/schemas/AreaType" + $ref: "#/components/schemas/GeoAreaType" required: - areaType discriminator: propertyName: areaType mapping: - POLYGON: "#/components/schemas/Polygon" + POLYGON: "#/components/schemas/GeoPolygon" GEOHASHLIST: "#/components/schemas/GeohashList" - AreaType: + GeoAreaType: type: string description: | Type of this area. @@ -407,10 +398,10 @@ components: enum: - POLYGON - GEOHASHLIST - Polygon: - description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself. + GeoPolygon: + description: Polygonal area. The polygon should be a simple polygon, i.e. should not intersect itself. allOf: - - $ref: "#/components/schemas/Area" + - $ref: "#/components/schemas/GeoArea" - type: object required: - boundary @@ -421,7 +412,7 @@ components: 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" + - $ref: "#/components/schemas/GeoArea" - type: object required: - geohashes @@ -489,11 +480,11 @@ components: $ref: '#/components/schemas/TimedConnectivityData' maxItems: 168 status: - $ref: '#/components/schemas/ResponseStatus' + $ref: '#/components/schemas/ResponseQualityInfo' statusInfo: type: string maxLength: 512 - description: Information about the status, mandatory when property `status` is `OPERATION_NOT_COMPLETED` for adding extra information about the error. + description: Provides additional context about `status`. Mandatory when `status` is `OPERATION_NOT_COMPLETED`, to convey the reason the asynchronous processing could not be completed. example: Some error happened during the processing of the request requestedHeight: type: integer @@ -531,16 +522,14 @@ components: maxLength: 256 description: The unique identifier of the asynchronous operation that is returned when the operation is initiated. example: 2322f362-eaab-4cf3-86d2-efcbdf3a7cb4 - ResponseStatus: + ResponseQualityInfo: type: string description: >- - Represents the state of the response for the input area defined in the request, the possible values are: + Provides additional information about the quality and coverage of the included response data for the requested area. This is not an HTTP error indicator - it characterises how completely the API was able to fulfil the request: - `SUPPORTED_AREA`: The whole request area is supported. Connectivity data for the entire requested area is returned. - - `PART_OF_AREA_NOT_SUPPORTED`: Part of the requested area is outside the MNOs coverage area, the cells outside the coverage - area will have property `layerConnectivities` with all items in the array with value `ND`. - - `AREA_NOT_SUPPORTED`: The whole requested area is outside the MNOs coverage area. No data will be returned. - - `OPERATION_NOT_COMPLETED`: An error happened during asynchronous processing of the request. This status will only be returned - in case the asynchronous API behaviour is used. + - `PART_OF_AREA_NOT_SUPPORTED`: Part of the requested area is outside the mobile network's coverage area. Cells outside coverage have property `layerConnectivities` with all items set to `ND`. + - `AREA_NOT_SUPPORTED`: The whole requested area is outside the mobile network's coverage area. No connectivity data is returned. + - `OPERATION_NOT_COMPLETED`: The asynchronous processing of the request could not be completed. This value is only used in asynchronous callbacks. See `statusInfo` for details. enum: - SUPPORTED_AREA - PART_OF_AREA_NOT_SUPPORTED