Land Cover Classification System Web Service - Specification

About

Currently, there are several data sets on regional, national and global scales with information on land use and land cover that aim to support a large number of applications, including the management of natural resources, climate change and its impacts, and biodiversity conservation. These data products are generated using different approaches and methodologies, which present information about different classes of the earth's surface, such as forests, agricultural plantations, among others. Initiatives that generate land use and land cover maps normally develop their own classification system, with different nomenclatures and meanings of the classes used.

In this context, the LCCS-WS (Land Cover Classification System Web Service) aims to provide a simple interface to access the various classification systems in use and their respective classes. Therefore, this service proposes a representation for the classification systems and provides an API to access the classes and their symbolizations. It is also possible to stablish mappings between classes of different systems.

Free and Open Source implementations based on this service can be found in the lccs-ws (server) and lccs.py (Python client). See also the service Web Land Trajectory System (WLTS), which uses LCCS-WS to represent the classes associated with the features retrieved in its queries.

Repository Organization

api: LCCS Specification using OpenAPI 3.0.
jsonschemas: JSON Schema for the classification systems and classes.

Overview of Service Operations

The /classification_systems operation when queried with a GET method returns the list of land use and cover classification systems available in the service. A POST request on this route allow the client to add a new classification system.
The /classification_systems/{system_id_or_identifier} operation when queried with a GET method returns a document with full information about the classification system.
The /classification_systems/{system_id_or_identifier}/classes operation when queried with a GET method returns the list of classes from a classification system.
The /classification_systems/{system_id_or_identifier}/classes/{class_id} operation when queried with a GET method returns information about a class from a classification system
The /classification_systems/{system_id_or_identifier}/styles operation when queried with a GET method returns the list of styles of the classification.
The /classification_system/{system_id_or_identifier}/styles/{style_id} operation when queried with a GET method returns a document with the style of the classification system.
The /mappings/{system_id_or_identifier_source} operation when queried with a GET method returns a list of available mappings for the classification system.
The /mappings/{system_id_or_identifier_source}/{system_id_or_identifier_target}: operation when queried with a GET method returns the mapping between the classification systems. A POST request on this route allow the client to add a new mapping.

Building the Documentation

Requirements

The build system for the REST API documentation relies on the Node.js run-time environment:

Node.js (Version 8+).

ReDoc: generates HTML reference documentation from an OpenAPI specification file.

Build

If you have Node.js installed, please, execute the following command to install the ReDoc dependency:

$ npm install

After that, generate the documentation:

$ npm run build

The above command will create a folder named dist with the bundled file index.html. You may open it in your web browser or may serve it with an HTTP Server.

For Python developers, you can serve the HTML with:

python3.7 -m http.server 8080 --directory dist

License

Land Cover Classification System Web Service is free software; you can redistribute it and/or modify it under the terms of the MIT License; see LICENSE file for more details.

brazil-data-cube/lccs-ws-spec