From 94e713ca2408c149d13756e078ca5a04aa1d6800 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Mon, 5 Oct 2026 15:20:57 +0200 Subject: [PATCH 01/10] docs: Restructure info.description for clarity (issue #84) --- .../predictive-connectivity-data.yaml | 195 +++++++++--------- 1 file changed, 97 insertions(+), 98 deletions(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index b968f6c..0108bc9 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -2,140 +2,139 @@ 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 client, 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. + - **IoT deployment planning**, assessing connectivity coverage for planned sensor or device installations. - 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. + An MNO 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 × `layerThickness` to (N+1) × `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 measurements 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 equal-sized cells based on the requested precision. + - **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 and therefore the same size in degrees of latitude and longitude. + - For geohash lists, each geohash corresponds to a single cell at its own precision level. + + **Geohash** + A string-encoded representation of a geographical area using the [Geohash system](https://en.wikipedia.org/wiki/Geohash). The length (number of characters) of the geohash indicates its precision (zoom level/granularity). The maximum precision level supported by this API is 12. - 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. + **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. As a reference, a cell is approximately 153 m × 153 m at level 7. + - **GEOHASHLIST**: Each geohash's own length determines its precision. The `precision` property MUST NOT be included. - 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. + **MNO 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`. - 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: + **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`. - - `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. + **OperationId** + A unique identifier correlating an asynchronous request with its callback notification. - Optionally, if supported by the implementation and requested by the client, raw signal strength values in dBm can also be returned for each layer. + **Callback URL and Token** + A callback URL (`sink`) may be provided to receive asynchronous results. When `sink` is used, it is RECOMMENDED for the client to also provide `sinkCredential` to secure the callback endpoint. Supported credential types are `ACCESSTOKEN` and `PRIVATE_KEY_JWT`. + + # API Functionality - These values are calculated based on network data and/or prediction models trained on - such data. + 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** (C2, STREAM_4K, or BEST_EFFORT) + 4. The **time interval** (`startTime` and `endTime`) + 5. Optionally, a **height** in metres AGL to filter to a single layer + 6. Optionally, a **network type** (4G or 5G; both if omitted) + 7. Optionally, **includeSignalStrength** to request raw dBm values - The polygon provided must comply with certain restrictions, which must be - previously validated by the developer: + 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. - - 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. + - For polygon areas, the API subdivides the polygon into equal-sized grid cells based on the requested precision. + - For geohash lists, each geohash corresponds to a single cell, and the `precision` property MUST NOT be included. - When the area is specified as a list of geohashes (`areaType: GEOHASHLIST`): + Connectivity levels are calculated based on network data and/or prediction models trained on such data. - - 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`. + Polygon areas must meet certain constraints: + - Maximum polygon area size (implementation-specific). + - The polygon cannot have an arbitrary complexity (unlimited number of sides, complex shapes, etc.). + - Must lie at least partially within the MNO coverage area; otherwise, the response has `status` set to `AREA_NOT_SUPPORTED` and an empty array is returned. - 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`. + For geohash lists: + - Support for `POLYGON` is mandatory for all MNOs, while support for `GEOHASHLIST` is optional. If the MNO 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`. - ## Error handling: + The API normally behaves synchronously. However, large requests may trigger asynchronous processing. Clients may enforce asynchronous behavior by providing a `sink` callback URL. If asynchronous processing is not supported, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_ASYNC_RESPONSE`. - Three different `422` error responses distinguish why a request cannot be served. They are - mutually exclusive and are evaluated in this order: + 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 at all. 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**: Request too large for synchronous processing and asynchronous processing is not enabled. A smaller request would succeed. + - **PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_REQUEST**: Request too large for both synchronous and asynchronous processing. Retrying with `sink` does not help; only a smaller request does. - - `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. + If an error occurs during asynchronous processing, the callback includes `status = OPERATION_NOT_COMPLETED` and a `statusInfo` field with additional details. - - `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. + # Resources and Operations Overview - - `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. + 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 per time slot an array of cells (`cellConnectivityData`), with for each cell the connectivity levels per vertical layer. The possible connectivity values are: - 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. + - **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 connectivity data available. - NOTE: In case the property "networkType" is not included, the quality of connectivity - will be returned considering both 4G and 5G networks. + **Callback URL and token** + Developers may provide a callback URL (`sink`) for receiving an asynchronous 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. If provided, `sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT`. - # Resources and Operations overview + - When an asynchronous response is requested (using `sink`), the 202 response of the API will include an `operationId` property. This `operationId` property will also be sent in the callback payload. The purpose of the `operationId` is to correlate an asynchronous response with its corresponding request. - 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`. From 677674f7e1cd534e393220864d1f5225de185cf2 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Mon, 5 Oct 2026 15:43:29 +0200 Subject: [PATCH 02/10] fix: Rename local schemas that clash with CAMARA common datatypes (issue #85) --- .../predictive-connectivity-data.yaml | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 0108bc9..eb35763 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -332,7 +332,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: @@ -384,20 +384,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. @@ -406,10 +406,10 @@ components: enum: - POLYGON - GEOHASHLIST - Polygon: + 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 @@ -420,7 +420,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 From 2444095a14df422d7de7817cd9876e0120ed1b3b Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Mon, 5 Oct 2026 15:47:06 +0200 Subject: [PATCH 03/10] fix: Rename ResponseStatus to DataQualityInfo and clarify descriptions (issue #86) --- .../predictive-connectivity-data.yaml | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index eb35763..15d136e 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -488,11 +488,11 @@ components: $ref: '#/components/schemas/TimedConnectivityData' maxItems: 168 status: - $ref: '#/components/schemas/ResponseStatus' + $ref: '#/components/schemas/DataQualityInfo' 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 @@ -530,16 +530,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: + DataQualityInfo: 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 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 MNO'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 MNO'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 From 38c11b4ce92afd99b054ad65ee0f7b6f58d0a9d1 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 6 Oct 2026 13:20:01 +0200 Subject: [PATCH 04/10] fix: Address review feedback on issues #84, #85 and #86 --- .../predictive-connectivity-data.yaml | 25 ++++++------------- 1 file changed, 8 insertions(+), 17 deletions(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 15d136e..6c14e0e 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -17,7 +17,6 @@ info: - **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. - - **IoT deployment planning**, assessing connectivity coverage for planned sensor or device installations. These examples illustrate typical applications, but the API can be used in many other scenarios where predictive connectivity estimation is relevant. @@ -45,7 +44,7 @@ info: The vertical height above the ground, in metres. Used to define the prediction height and to describe the vertical layering of connectivity data. **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 × `layerThickness` to (N+1) × `layerThickness` metres AGL. + 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. **Signal Strength** Raw signal strength measurements in dBm that can be optionally included in the response when supported by the implementation and requested via `includeSignalStrength`. @@ -64,7 +63,7 @@ info: **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. As a reference, a cell is approximately 153 m × 153 m at level 7. + - **POLYGON**: The precision level is given by the `precision` request property. If not included, the default precision level 7 is used. As a reference, a cell is approximately 153 m x 153 m at level 7. - **GEOHASHLIST**: Each geohash's own length determines its precision. The `precision` property MUST NOT be included. **MNO Coverage Area** @@ -77,9 +76,6 @@ info: **OperationId** A unique identifier correlating an asynchronous request with its callback notification. - **Callback URL and Token** - A callback URL (`sink`) may be provided to receive asynchronous results. When `sink` is used, it is RECOMMENDED for the client to also provide `sinkCredential` to secure the callback endpoint. Supported credential types are `ACCESSTOKEN` and `PRIVATE_KEY_JWT`. - # API Functionality To retrieve predictive connectivity data, the API consumer specifies: @@ -100,7 +96,7 @@ info: Polygon areas must meet certain constraints: - Maximum polygon area size (implementation-specific). - - The polygon cannot have an arbitrary complexity (unlimited number of sides, complex shapes, etc.). + - 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 MNO coverage area; otherwise, the response has `status` set to `AREA_NOT_SUPPORTED` and an empty array is returned. For geohash lists: @@ -122,12 +118,7 @@ info: # Resources and Operations Overview 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 per time slot an array of cells (`cellConnectivityData`), with for each cell the connectivity levels per vertical layer. The possible connectivity values are: - - - **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 connectivity data available. + The API call result is an array of time slots (`timedConnectivityData`), with per time slot an array of cells (`cellConnectivityData`), with for each cell the connectivity levels per vertical layer (see **Connectivity Level** in the definitions above). **Callback URL and token** Developers may provide a callback URL (`sink`) for receiving an asynchronous 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. If provided, `sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT`. @@ -345,7 +336,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 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 @@ -488,7 +479,7 @@ components: $ref: '#/components/schemas/TimedConnectivityData' maxItems: 168 status: - $ref: '#/components/schemas/DataQualityInfo' + $ref: '#/components/schemas/ResponseQualityInfo' statusInfo: type: string maxLength: 512 @@ -530,10 +521,10 @@ 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 - DataQualityInfo: + ResponseQualityInfo: type: string description: >- - Provides additional information about the quality and coverage of the included response data for the requested area. This is not an error indicator — it characterises how completely the API was able to fulfil the request: + 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 MNO'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 MNO's coverage area. No connectivity data is returned. From 46ab897530e0ce0314d1b8e9c970546d89afcca7 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 6 Oct 2026 16:11:28 +0200 Subject: [PATCH 05/10] fix: Align terminology with PDD review feedback --- code/API_definitions/predictive-connectivity-data.yaml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 6c14e0e..0d8637b 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -50,12 +50,12 @@ info: Raw signal strength measurements 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 equal-sized cells based on the requested precision. + - **POLYGON**: Area defined by a list of latitude/longitude points forming a simple polygon. The set of cells for the polygon correspond to the geohashes covering the polygon obtained by applying the requested precision. - **GEOHASHLIST**: Area defined as a list of geohash strings. Geohashes may be individual, non-contiguous geographical areas each with their own (possibly different) precision. **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 and therefore the same size in degrees of latitude and longitude. + - 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. **Geohash** @@ -89,7 +89,7 @@ info: 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. - - For polygon areas, the API subdivides the polygon into equal-sized grid cells based on the requested precision. + - 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. Connectivity levels are calculated based on network data and/or prediction models trained on such data. @@ -121,7 +121,7 @@ info: The API call result is an array of time slots (`timedConnectivityData`), with per time slot an array of cells (`cellConnectivityData`), with for each cell the connectivity levels per vertical layer (see **Connectivity Level** in the definitions above). **Callback URL and token** - Developers may provide a callback URL (`sink`) for receiving an asynchronous 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. If provided, `sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT`. + API Consumers may provide a callback URL (`sink`) for receiving an asynchronous response. This is an optional parameter. If `sink` is included, it is RECOMMENDED for the API Consumer to provide as well the `sinkCredential` property to protect the callback endpoint. If provided, `sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT`. - When an asynchronous response is requested (using `sink`), the 202 response of the API will include an `operationId` property. This `operationId` property will also be sent in the callback payload. The purpose of the `operationId` is to correlate an asynchronous response with its corresponding request. From 864f881bb8f2614da6649629c5cd1606a747893e Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 6 Oct 2026 18:10:11 +0200 Subject: [PATCH 06/10] fix: Align statusInfo and Resources section structure with PDD --- .../predictive-connectivity-data.yaml | 22 +++++++++---------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 0d8637b..8379e50 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -11,7 +11,7 @@ info: - 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 client, raw **signal strength** values in dBm can also be returned. + - 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. This API supports a wide range of use cases, including but not limited to: @@ -59,11 +59,11 @@ info: - For geohash lists, each geohash corresponds to a single cell at its own precision level. **Geohash** - A string-encoded representation of a geographical area using the [Geohash system](https://en.wikipedia.org/wiki/Geohash). The length (number of characters) of the geohash indicates its precision (zoom level/granularity). The maximum precision level supported by this API is 12. + 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. The length (number of characters) of the geohash indicates its precision (zoom level/granularity). More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash). **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. As a reference, a cell is approximately 153 m x 153 m at level 7. + - **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. **MNO Coverage Area** @@ -74,7 +74,10 @@ info: - **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`. **OperationId** - A unique identifier correlating an asynchronous request with its callback notification. + 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). + + **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`. # API Functionality @@ -106,7 +109,7 @@ info: - 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`. - The API normally behaves synchronously. However, large requests may trigger asynchronous processing. Clients may enforce asynchronous behavior by providing a `sink` callback URL. If asynchronous processing is not supported, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_ASYNC_RESPONSE`. + The API normally behaves synchronously. However, large requests may trigger asynchronous processing. API Consumers may enforce asynchronous behavior by providing a `sink` callback URL. If asynchronous processing is not supported, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_ASYNC_RESPONSE`. 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 at all. 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. @@ -120,12 +123,9 @@ info: 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 per time slot an array of cells (`cellConnectivityData`), with for each cell the connectivity levels per vertical layer (see **Connectivity Level** in the definitions above). - **Callback URL and token** - API Consumers may provide a callback URL (`sink`) for receiving an asynchronous response. This is an optional parameter. If `sink` is included, it is RECOMMENDED for the API Consumer to provide as well the `sinkCredential` property to protect the callback endpoint. If provided, `sinkCredential.credentialType` MUST be set to `ACCESSTOKEN` or `PRIVATE_KEY_JWT`. - - - When an asynchronous response is requested (using `sink`), the 202 response of the API will include an `operationId` property. This `operationId` property will also be sent in the callback payload. The purpose of the `operationId` is to correlate an asynchronous response with its corresponding request. + 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`. - - 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`. + 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`. @@ -398,7 +398,7 @@ components: - POLYGON - GEOHASHLIST GeoPolygon: - description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself. + description: Polygonal area. The polygon should be a simple polygon, i.e. should not intersect itself. allOf: - $ref: "#/components/schemas/GeoArea" - type: object From e5747e227b298cc3d1d41b590b96c32ca0ca01d5 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 6 Oct 2026 18:19:15 +0200 Subject: [PATCH 07/10] fix: Align POLYGON area type wording with PDD --- code/API_definitions/predictive-connectivity-data.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 8379e50..74f4302 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -50,7 +50,7 @@ info: Raw signal strength measurements 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 set of cells for the polygon correspond to the geohashes covering the polygon obtained by applying the requested precision. + - **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. **Grid Cell** From e63c7d370775d2c26a3a17ed74b50e37da6ce23e Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 13 Oct 2026 13:19:02 +0200 Subject: [PATCH 08/10] Apply eric's suggestion for wording Co-authored-by: Eric Murray --- .../predictive-connectivity-data.yaml | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 74f4302..a10bc29 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -35,7 +35,7 @@ info: - **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. - An MNO may not support every service level. If the requested service level is not supported, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL`. + 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`. **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. @@ -47,7 +47,7 @@ info: 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. **Signal Strength** - Raw signal strength measurements in dBm that can be optionally included in the response when supported by the implementation and requested via `includeSignalStrength`. + 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. @@ -59,14 +59,15 @@ info: - For geohash lists, each geohash corresponds to a single cell at its own precision level. **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. The length (number of characters) of the geohash indicates its precision (zoom level/granularity). More information at [Geohash system](https://en.wikipedia.org/wiki/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). **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. - **MNO Coverage Area** + **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`. **Synchronous vs Asynchronous Processing** @@ -84,9 +85,9 @@ info: 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** (C2, STREAM_4K, or BEST_EFFORT) + 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 filter to a single layer + 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 @@ -100,21 +101,21 @@ info: 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 MNO coverage area; otherwise, the response has `status` set to `AREA_NOT_SUPPORTED` and an empty array is returned. + - 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. For geohash lists: - - Support for `POLYGON` is mandatory for all MNOs, while support for `GEOHASHLIST` is optional. If the MNO does not support `GEOHASHLIST`, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE`. + - 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`. - The API normally behaves synchronously. However, large requests may trigger asynchronous processing. API Consumers may enforce asynchronous behavior by providing a `sink` callback URL. If asynchronous processing is not supported, the API returns `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_ASYNC_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`. 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 at all. 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**: Request too large for synchronous processing and asynchronous processing is not enabled. A smaller request would succeed. - - **PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_REQUEST**: Request too large for both synchronous and asynchronous processing. Retrying with `sink` does not help; only a smaller request does. + - **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. If an error occurs during asynchronous processing, the callback includes `status = OPERATION_NOT_COMPLETED` and a `statusInfo` field with additional details. From 459acb09319f1ae4c092391d83b95f6943979ec7 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 13 Oct 2026 13:21:49 +0200 Subject: [PATCH 09/10] Apply eric's suggestion for wording Co-authored-by: Eric Murray --- code/API_definitions/predictive-connectivity-data.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index a10bc29..1be60b4 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -122,7 +122,7 @@ info: # Resources and Operations Overview 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 per time slot an array of cells (`cellConnectivityData`), with for each cell the connectivity levels per vertical layer (see **Connectivity Level** in the definitions above). + 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). 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`. From 9d28f931f88e4fae3a3659638e30dd86828f7302 Mon Sep 17 00:00:00 2001 From: Alberto Ramos Monagas Date: Tue, 13 Oct 2026 14:59:20 +0200 Subject: [PATCH 10/10] Apply eric's suggestion from code review Co-authored-by: Eric Murray --- code/API_definitions/predictive-connectivity-data.yaml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 1be60b4..2892b00 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -337,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 @@ -527,8 +527,8 @@ components: description: >- 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 MNO'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 MNO's coverage area. No connectivity data is returned. + - `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