Areas API proposal

[hubertp-ericsson]

What type of PR is this?

enhancement/feature

What this PR does / why we need it:

This PR proposes a new API to be added to the Dedicated Network API family to provide information about the geographical areas where consistent service coverage according to one or more network profiles is supported. This API makes such areas discoverable.

Which issue(s) this PR fixes:

Fixes #86

Special notes for reviewers:

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[hubertp-ericsson]

Attaching a presentation describing the concept.
AreasAPIforCAMARA.pptx

[Masa8106]

@hubertp-ericsson, thank you for providing the slide decks.
I see the proposed Areas API is within Dedicated Network repository and is designed only for Dedicated Network as I can see ServiceArea includes networkProfiles. Just in my opinion, I think it would be better if this Areas API can be generalised not only for Dedicated Network but also for other CAMARA APIs.

[Masa8106]

As far as I see so far, my comments are the followings:

• AreaName would be good to be kept, as it is used as input parameter of QoS B API.
• ServiceArea schema would be good to have QoS Profile as well as networkProfiles, as it can be applicable in a case of QoS B API.

[hubertp-ericsson]

To align with QoS Booking API I have added to the service area a list of supported QoS profiles. The service area has a 'name' property with content that is not necessarily unique. To uniquely identify the service area QoS Booking API could use the 'id' property which is meant to be unique, and is also a string but in uuid format.

[Masa8106]

It makes sense that the serviceArea has "name" and "id", so far.

[sergiobrisio]

I would like to propose a more standard approach for the geographical area definition, which could be in line with geoJSON structure. GeoJSON is a standard IETF RFC 7946. It provides a widely accepted, flexible, and structured format for representing geographic data, making them ideal for defining service coverage areas and customer-requested service zones.
GeoJSON is a widely adopted (as web mapping, geospatial analysis, and data interchange format), lightweight data format for encoding geographic structures (points, lines, polygons) based on JavaScript Object Notation (JSON):

{
  "type": "Feature",
  "geometry": {
    "type": "Point",
    "coordinates": [125.6, 10.1]
  },
  "properties": {
    "name": "Dinagat Islands"
  }
}

The format encodes a variety of geographic data structures:

• Point (Longitude, Latitude) → Useful for single-location requests
• MultiPoint → Multiple points, e.g., multiple service centers
• LineString → Paths or service corridors
• Polygon → Ideal for defining a service area with boundaries
• MultiPolygon → Multiple service zones in different locations

Uses of geoJSON in SW:

Web Mapping Libraries and APIs:

• Leaflet: A leading open-source JavaScript library that natively supports GeoJSON for interactive maps.
• Mapbox GL JS: A mapping platform that supports GeoJSON for creating custom, interactive maps and visualizations.
• Google Maps JavaScript API: to import, display, and style GeoJSON data using the Data Layer (map.data.loadGeoJson).
• MapLibre GL: An open-source alternative to Mapbox GL that supports GeoJSON sources and layers.
• OpenLayers: A high-performance library for all types of web maps that integrates well with GeoJSON

GIS Desktop and Server Software using geoJSON:

• QGIS: An open-source desktop GIS that supports loading, viewing, editing, and exporting GeoJSON.
• GDAL/OGR: The standard library for geospatial data processing, which includes robust read/write support for GeoJSON.
• ArcGIS Online/Pro: Supports GeoJSON for creating web maps, uploading data, and via the Data Interoperability extension.
• GeoServer & MapServer: Popular open-source servers for publishing spatial data that support GeoJSON output.
• SpatiaLite: A database engine that supports importing and exporting GeoJSON

Databases and Platforms using geoJSON:

• PostGIS: An extension for PostgreSQL that can generate GeoJSON directly from database queries using functions like ST_AsGeoJSON. (PostGIS uses a custom internal geometry binary type based on WKB - Well-Known Binary, industry standard for efficient database storage).
• MariaDB: Supports storing and querying geometric shapes, facilitating the management of GeoJSON-sourced data

Other Spatial DBs:

• Oracle Spatial uses the SDO_GEOMETRY object type as its native standard. Modern versions like Oracle Database 23ai (released in 2024) natively manage spatial data and can store GeoJSON in JSON-specific columns with full spatial indexing and SQL function support.
• SQL Server: Offers two native types: geometry (for flat-earth Euclidean coordinates) and geography (for round-earth ellipsoidal data like GPS coordinates).

Other competing standards:

TopoJSON: Web Developers & Data Visualizers
primarily adopted by those who need to deliver high-quality maps over the web while minimizing bandwidth. 80% smaller than GeoJSON because it encodes shared boundaries (topology) once rather than duplicating them for every adjacent polygon.
GML (Geography Markup Language): Government & Enterprise
GML is an XML-based international standard (ISO 19136) used by large-scale institutions that require strict data validation and rich metadata. Is the mandatory exchange format for the INSPIRE directive, which aims to create a shared spatial data infrastructure across Europe.
GeoParquet: cloud-native big data analysis
A rising standard for cloud-native big data analysis, allowing direct spatial queries on large datasets without full downloads.