Define first WIP version of Predictive Connectivity Data API#20
Define first WIP version of Predictive Connectivity Data API#20albertoramosmonagas merged 1 commit intomainfrom
Conversation
| serviceLevel: | ||
| $ref: '#/components/schemas/ServiceLevel' | ||
| area: | ||
| $ref: '#/components/schemas/Area' |
There was a problem hiding this comment.
I'd propose to add an optional height parameter here. If specified, only the relevant layer is returned. If not specified, all layers are returned. We can discuss if a maximum height is required and, if so, what its value should be.
| $ref: '#/components/schemas/Area' | |
| $ref: '#/components/schemas/Area' | |
| height: | |
| description: Requested prediction height in metres above ground level. If no prediction height is specified, the response will include all available prediction heights. | |
| type: integer | |
| minimum: 0 | |
| maximum: 250 |
There was a problem hiding this comment.
@VGF-TEF - Thanks Eric, we support the inclusion of the optional height parameter.
It makes sense that, if specified, only the relevant layer is returned — that’s aligned with our expectations.
Regarding the maximum height: we are open to defining a reasonable limit for consistency and would be happy to contribute to that discussion.
Although we’re discussing it here, we can also revisit this point during the upcoming meeting.
There was a problem hiding this comment.
Decision: OK with maximum of 250 meters and as optional parameter.
| End date time in [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) | ||
| and must have time zone. Recommended format is | ||
| YYYY-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows | ||
| 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). |
There was a problem hiding this comment.
An optional precision parameter should be included here, in exactly the same way as is done for Population Density Data. You will also need to add a new error code PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION.
| 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). | |
| 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z). | |
| 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`. | |
| minimum: 1 | |
| maximum: 12 | |
| default: 7 |
There was a problem hiding this comment.
@VGF-TEF
Thanks Eric, we agree with including the optional precision parameter, aligned with the approach taken in the Population Density API.
From Telefónica’s side, we would like to ensure that this remains optional not only for the client but also for the provider. In our current implementation of the Population API, we only support precision level 7, and we would not want to be required to support multiple levels.
As long as each MNO can define which precision levels are supported — and return the appropriate error when unsupported — this proposal works for us.
Please note that these kinds of inclusions have already been discussed at a product level, but we still need to review them with our technical team. We can also briefly revisit this point in the upcoming meeting.
There was a problem hiding this comment.
Decision: Let’s include this optional precision parameter and align with the Population Density API behavior.
| type: string | ||
| enum: | ||
| - C2 | ||
| - STREAM_4K |
There was a problem hiding this comment.
Add option to request signal strength prediction only
| - STREAM_4K | |
| - STREAM_4K | |
| - SIGNAL_STRENGTH |
There was a problem hiding this comment.
Decision for Signal Strength comments: If the API consumer says, I want signal strength we can respond, no, that feature's not supported or we can have another endpoint for service level and one for signal strength.
| the cell granularity, is determined by the implementation. | ||
| example: ezdmemd | ||
| layerConnectivities: | ||
| $ref: '#/components/schemas/LayerConnectivities' |
There was a problem hiding this comment.
Add option to include signal strength estimates in response
| $ref: '#/components/schemas/LayerConnectivities' | |
| $ref: '#/components/schemas/LayerConnectivities' | |
| signalStrength: | |
| type: array | |
| items: | |
| description: Predicted signal strength values in dBm for each layer | |
| type: number |
There was a problem hiding this comment.
@VGF-TEF
Thanks Eric. From Telefónica’s perspective, we currently do not provide signal strength prediction as a service level, so we would not be able to support this value at the moment.
If SIGNAL_STRENGTH is defined as an optional service level that providers can choose whether or not to implement, we are fine with its inclusion. However, if support becomes mandatory for all providers, we would need to push back.
This applies for all comments that have the SIGNAL_STRENGTH
| - GC | ||
| - MC | ||
| - NC | ||
| - ND |
There was a problem hiding this comment.
Add "null" value indicating that only a signal strength estimate is being provided, and not a connectivity quality estimate
| - ND | |
| - ND | |
| - SS |
What type of PR is this?
Add one of the following kinds:
What this PR does / why we need it:
This PR introduces the first version (Work In Progress) of the API now named Predictive Connectivity Data, aligned with the CAMARA working group naming, to decouple the API name from any single use case (e.g., drone use cases).
It introduces asynchronous support via callback (sink) and optional authentication through sinkCredential, following the same pattern as the Population Density Data API. When sink is provided, the API returns a 202 and responds asynchronously via POST to the given URL.
The PR improves documentation with clearer definitions (e.g., AGL), adds detailed descriptions of asynchronous behavior, and includes error handling logic (OPERATION_NOT_COMPLETED, etc.).
Four new status values have been documented (SUPPORTED_AREA, PART_OF_AREA_NOT_SUPPORTED, AREA_NOT_SUPPORTED, OPERATION_NOT_COMPLETED), along with examples.
Error code 410 has been added to the callback for cases where the consumer’s endpoint is no longer available. Other error responses have also been expanded and aligned with the structure of the Population Density Data API.
Which issue(s) this PR fixes:
Fixes #15
Special notes for reviewers:
The inclusion of asynchronous behavior affects both the main endpoint and callback structure. Please verify sinkCredential structure and operationId traceability. Alignment with CAMARA commonalities has been considered.
Changelog input
Additional documentation
N/A