The European Space Agency
Contact us

Geospatial Explorer

This section outlines the requirements for the interoperability of the APEx Geospatial Explorer services. These requirements must be met to ensure the correct configuration and operation of a dashboard and its instantiation.

A technical challenge of the Geospatial Explorer service being provided by APEx is that it is to be instantiated on demand, with functional requirements potentially varying amongst each service.The geospatial explorer makes ue of a well-defined configuration schema, provided in the form of JSON, that outlines the interactive features and data sources to be used.

This approach allows APEx to define and update the schema required in the interoperability guidelines, which will then enables requesters of the service to configure the Geospatial Explorer on an individual project level with minimal external intervention.

The schema is versioned as it will change throughout the APEx project as the functional capabilities of the Geospatial Explorer matures. This does allow for improvements and extra features to be easily added to the application, and best practices shall be followed to avoid any breaking changes between versions.

Requirements

Table 1 outlines the requirements for configuring an instance of the Geospatial Explorer application.

Table 1: Interoperability requirements for the Geospatial Explorer application
ID Requirement Description
EXPLORER-REQ-01 Configuration of the Geospatial Explorer shall adhere to the provided JSON schema, as described in the Configuration Schema section. The application is configured through a hosted JSON object which is fetched when the client-side application loads. For the application to correctly render, a valid configuration JSON that follows the outlined schema must be provided pre-instantiation. During early development the schema will be subject to change and provided with limited validation.
EXPLORER-REQ-02 Raster sources defined within the config shall be provided as either:
  • A well formed URL to a hosted Cloud Optimised GeoTiff (COG) [1].
  • A well formed URL pointing to STAC item containing a publicly hosted Cloud Optimised Geotiff as an asset.
  • WMS [2] or WMTS [3] endpoint following the relevant OGC specifications.
  • A template URL following the XYZ(*) format serving PNG or JPEG tiles.
The use of these formats ensures that raster data can be visualized using widely recognized and well-established standards.
EXPLORER-REQ-03 Vector sources defined within the config shall be provided as either:
  • A well formed URL to a valid GeoJSON [4] resource.
  • A public WFS [5] or OGC API Features [6] endpoint following the relevant OGC specifications.
  • A well formed URL to a valid FlatGeobuf [7] resource.
The use of these formats ensures that vector data can be visualized using widely recognized and well-established standards.
EXPLORER-REQ-04 All external sources shall be publicly available. Currently the application does not support fetching sources from hosts that require authentication.
EXPLORER-REQ-05 All external sources shall be available utilising the HTTPS protocol. It is best practice to utilise HTTPS where possible. Whilst not as of yet blocked specifically, non-secure resources may not function correctly.
EXPLORER-REQ-06 Web service endpoints for data must be configured to allow cross-origin requests from the domain hosting the Geospatial Explorer. This includes setting the Access-Control-Allow-Origin header to explicitly permit the origin of the requesting front end or using a dynamic or wildcard origin setting if appropriate. Additionally, the web service must handle preflight (OPTIONS) requests correctly, including the Access-Control-Allow-Methods and Access-Control-Allow-Headers headers, to support the HTTP methods and headers used by the front end.
EXPLORER-REQ-07 All datasets shall be projected to CRS EPSG:3857 (Web Mercator); EPSG:4326 (WGS84) or EPSG:3035 (ETRS89-extended / LAEA Europe) Other projections may work but will not be explicitly supported in the initial versions of the application. Support for these projections will be considered and reviewed on a case-by-case basis and will be subject to support by the PROJ4JS library [8].
EXPLORER-REQ-08

Legends support is provided in the Geospatial Explorer via the following mechanisms:

  • Dynamically using “swatch” or “gradient” options in the Geospatial Explorer config, which displays a legend using category, gradient or colormap settings;
  • By calling a WMS [2] getLegendGraphic request (if supported by a WMS source)
  • By specifying in config the URL to a browser supported image resource (PNG, JPEG, SVG).

Legend settings can be configured using the configuration builder tool.

This guideline ensures that the legend is fully compatible with the visualisation library used in the Geospatial Explorer.
EXPLORER-REQ-09 Statistical datasets should be configured by providing public URLs to either: GeoJSON [4] or FlatGeobuf [7]. Details on the structure of these datasets are outlined in the File Formats section. The statistics feature is complex due to the architecture and requirements of the Geospatial Explorer. Statistical datasets contain one or more files that include vector features that describe an area and the relevant statistics for the area can be added to the configuration of an explorer instance.
EXPLORER-REQ-10

To facilitate the integration of STAC datasets within the Geospatial Explorer, it is advisable to follow the recommendations presented in our metadata recommendations. For optimal results within the Geospatial Explorer, the use of the following STAC extensions is recommended:

The usage of the suggested extensions will allow the Geospatial Explorer to automatically configure the visualization properties of the selected dataset without the need for additional manual configuration.
EXPLORER-REQ-11 “Secondary” constraint layers (e.g. elevation; land cover) can be used to filter the data in a “primary” layer (e.g. solar energy potential). Both the primary and secondary layers need to be Cloud Optimised GeoTIFFs. All primary and secondary layers must use the same grid (i.e. CRS, origin and resolution) as each other.

(*) The XYZ approach refers to a de facto API standard for URL structuring (Z = zoom level, X and Y = grid references). While there is no dedicated specification for XYZ, it is widely used (e.g., OpenStreetMap).

Format Specification & Guidelines

To support the smooth integration of datasets in the Geospatial Explorer, it is essential that all datasets adhere to the general file format recommendations. Following these guidelines ensures compatibility and ease of integration within an APEx Geospatial Explorer.

When referencing data through a STAC catalogue, it is further advised to comply with the STAC metadata recommendations. Adhering to these metadata standards will improve dataset discoverability, interoperability, and enable seamless integration with the Geospatial Explorer.

Configuration Schema

The service configuration will be based on a schema that provides administrators with the expected structure and contents of the configuration. Taking this approach enables:

  • Automated and dynamic instantiation of the service with differing functionality.
  • Configuration validation.
  • Definition of a “contract” for easier documentation of features and their configuration.

For more detailed information on this configuration schema, refer to the APEx documentation portal: APEx Configuration Schema Documentation. Numerous example configurations can be found in the APEx Geospatial Explorer Configurations repository on GitHub.