diff --git a/code/API_definitions/predictive-connectivity-data.yaml b/code/API_definitions/predictive-connectivity-data.yaml index 25541db..1d3fe14 100644 --- a/code/API_definitions/predictive-connectivity-data.yaml +++ b/code/API_definitions/predictive-connectivity-data.yaml @@ -35,10 +35,15 @@ info: # API Functionality - Once a developer specifies (1) the area as a polygon shape, (2) a precision level, (3) the service + Once a developer specifies (1) the area (either as a polygon shape or as a list of geohashes), + (2) a precision level (only when the area is a polygon), (3) the service level and (4) time interval in which they want to obtain the connectivity estimation, the API returns a data set consisting of a sequence of time ranges, with each - time range containing the input polygon subdivided into equal-sized grid cells. + time range containing the requested area subdivided into equal-sized grid cells. + + When the area is provided as a list of geohashes (`areaType: GEOHASHLIST`), the response + contains one cell per requested geohash; each geohash determines the granularity of its own + response cell, and the `precision` request property MUST NOT be included. For each of the equal-sized cells of the grid, an analysis of Connectivity Levels is reported for each time slot within the range, this includes data classified into: @@ -64,6 +69,21 @@ info: implementation will not be returned. Therefore, if a polygon is located entirely outside the supported area, an empty array will be returned. + When the area is specified as a list of geohashes (`areaType: GEOHASHLIST`): + + - All MNOs must support the `POLYGON` area type; support for `GEOHASHLIST` is optional. + If the MNO does not support `GEOHASHLIST`, the API returns the error response + `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE`. + - The requested geohashes do not need to be adjacent or contiguous; the API + returns one cell per requested geohash. + - Geohashes within the same request may have different precisions (string + lengths), as long as the MNO supports all of them. If any geohash uses a + precision not supported by the MNO, the API returns the error response + `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION`. + - Geohashes within the list that fall outside the MNO coverage area are returned + with `layerConnectivities` containing all items set to `ND`. If the entire list + is outside the coverage area, the response will have `status` set to `AREA_NOT_SUPPORTED`. + The standard behaviour of the API is synchronous, although for large area requests the API may behave asynchronously. An API invoker can enforce asynchronous behaviour by providing a callback URL (sink) in the request, @@ -327,8 +347,10 @@ components: precision: type: integer description: >- - Precision required of response cells. Precision defines a geohash level and corresponds to the length of the geohash for each cell. More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash)" - If not included the default precision level 7 is used by default. In case of using a not supported level by the MNO, the API returns the error response `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION`. + Precision required of response cells. Precision defines a geohash level and corresponds to the length of the geohash for each cell. More information at [Geohash system](https://en.wikipedia.org/wiki/Geohash). + If not included the default precision level 7 is used by default. + Values within the schema range (1–12) that are not supported by the MNO return the error response `422 PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION`. Values outside the schema range are invalid per the OpenAPI definition and return `400 INVALID_ARGUMENT` via request validation. + This property MUST only be set when `area.areaType` is `POLYGON`. When `area.areaType` is `GEOHASHLIST`, each requested geohash determines the granularity of its own response cell; if `precision` is sent, the API returns a `400 INVALID_ARGUMENT` error. minimum: 1 maximum: 12 default: 7 @@ -376,13 +398,16 @@ components: propertyName: areaType mapping: POLYGON: "#/components/schemas/Polygon" + GEOHASHLIST: "#/components/schemas/GeohashList" AreaType: type: string description: | Type of this area. POLYGON - The area is defined as a polygon. + GEOHASHLIST - The area is defined as a list of geohashes. enum: - POLYGON + - GEOHASHLIST Polygon: description: Polygonal area. The Polygon should be a simple polygon, i.e. should not intersect itself. allOf: @@ -426,6 +451,30 @@ components: format: double minimum: -180 maximum: 180 + GeohashList: + description: >- + Area defined as a list of geohashes. Geohashes do not need to be adjacent or contiguous and may have different precision levels (string lengths), as long as the MNO supports all of them. The `precision` request property MUST NOT be set when `areaType` is `GEOHASHLIST`; if set, the API returns a `400 INVALID_ARGUMENT` error. + allOf: + - $ref: "#/components/schemas/Area" + - type: object + required: + - geohashes + properties: + geohashes: + type: array + description: List of geohashes that define the area of interest. + minItems: 1 + items: + $ref: "#/components/schemas/Geohash" + Geohash: + type: string + description: >- + Geohash string identifying a cell using the [Geohash system](https://en.wikipedia.org/wiki/Geohash), + encoding a geographic location into a short string. Characters are taken from the + base-32 geohash alphabet (`0-9` and `b-z` excluding `a`, `i`, `l`, `o`). + The length of the string determines the cell granularity (precision). + pattern: ^[0-9bcdefghjkmnpqrstuvwxyz]{1,12}$ + example: ezdmemd ServiceLevel: description: >- Describes the requested communication service level. Although more @@ -434,6 +483,8 @@ components: - C2: Command and Control. Consists in connecting an unmanned aerial vehicle with its remote controller. This link allows data transmission in both directions, facilitating real-time operation and feedback. - STREAM_4K: Streaming in 4K quality. - BEST_EFFORT: This service level provides a qualitative estimation of coverage based on each operator's own prediction models or public coverage maps. It does not imply any guarantee of network performance or service availability. The values of GC, MC, NC, and ND should be interpreted as approximate indicators of expected connectivity quality, not as results derived from standardised thresholds. + + An MNO may not support every service level listed in this enum. If the requested service level is not supported by the MNO, the API returns the error response `PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL`. type: string enum: - C2 @@ -662,13 +713,7 @@ components: its connectivity data. properties: geohash: - type: string - description: >- - Coordinates of the cell represented as a string using the [Geohash - system](https://en.wikipedia.org/wiki/Geohash), encoding a - geographic location into a short string. The value length, - and thus, the cell granularity, is determined by the request body property `precision`. - example: ezdmemd + $ref: '#/components/schemas/Geohash' layerConnectivities: $ref: '#/components/schemas/LayerConnectivities' layerSignalStrengths: @@ -839,6 +884,8 @@ components: - Indicated request is too big for both synchronous and asynchronous processing ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_REQUEST", "message": "The indicated request is too big for both synchronous and asynchronous processing") - Indicated cell precision (Geohash level) is not supported ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION", "message": "Indicated cell precision (Geohash level) is not supported") - Indicated request is too big for synchronous processing and asynchronous processing is not enabled ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SYNC_RESPONSE", "message": "The indicated request is too big for synchronous processing and asynchronous processing is not enabled") + - The requested `areaType` is not supported by the MNO ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE", "message": "The requested areaType is not supported by the MNO") + - Indicated service level is not supported ("code": "PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL", "message": "The service level provided is not supported") headers: x-correlator: $ref: '#/components/headers/x-correlator' @@ -857,6 +904,8 @@ components: - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_REQUEST - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_PRECISION - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SYNC_RESPONSE + - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE + - PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL examples: PREDICTIVE_CONNECTIVITY_DATA_422_UNSUPPORTED_REQUEST: value: @@ -878,6 +927,16 @@ components: message: >- Indicated combination of area, time interval and precision is too big for synchronous processing and asynchronous processing is not enabled + PREDICTIVE_CONNECTIVITY_DATA_422_UNSUPPORTED_AREA_TYPE: + value: + status: 422 + code: PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_AREA_TYPE + message: The requested areaType is not supported by the MNO + PREDICTIVE_CONNECTIVITY_DATA_422_UNSUPPORTED_SERVICE_LEVEL: + value: + status: 422 + code: PREDICTIVE_CONNECTIVITY_DATA.UNSUPPORTED_SERVICE_LEVEL + message: The service level provided is not supported Generic400: description: Problem with the client request headers: