#!/usr/bin/env python
# coding: utf-8
# # 01-Introduction to web services and OGC WCS
# << Index 02-WCS core requests >>
# ## Why do we need web services?
# Earth Science data have complex data structures. They are often multi-dimensional gridded fields that need extensive processing to retrieve meaningful and communicable information for users and decision-makers. With advances in processing power, the spatial resolution of Earth Science data is more and more refined, which leads to an increase in detail, but at the same time also to larger data volumes.
#
# The European Centre for Medium-Range Weather Forecasts (ECMWF) for example operates the Meteorological Archive and Retrieval System (MARS), the world's largest archive of meterological data, which holds at the beginning of 2016 ~ 90 PB of data and it continues growing by additional ~3 PB per month.
#
# Transport of petabytes (even terrabytes) of raw data is costly and should be avoided. The challenge for data providers is to provide access to the full range of data and information while minimising the need to download the data. Ideally, data access and processing is performed on server-side and only kilobytes of refined information are downloaded (see Figure below).
#
# Web services offer a variety of standard protocols that use the internet to view, access and retrieve geospatial data. Especially **standard data-access protocols**, such as Web Coverage Service, help to access the full range of raw data and allow the retrieval of refined information.
#
# 
#
#
#
# Data, information, knowledge hierarchy - How raw data is turned into value-added information
# and knowledge for users and decision-makers and the role of data providers in the hierarchy
#
# ***
# ## How does a web service work?
# Web services consist of **four components**:
# * the **service** itself, that processes the request made by the client
# * a **server** that stores the data and information
# * a **client**, which is an application that is using the web service, and
# * the **internet**, that transfers the request from the client to the web service and vice versa.
#
# In the case of a web coverage service (WCS), multi-dimensional gridded data are stored on a server that is hosted by a data provider (e.g. ECMWF). With the help of a WCS , the data can be accessed and processed in an interoperable way. Service requests are HTTP (Hypertext Transfer Protocol) requests, which are used to transfer data via the internet. Thus, service requests are a URL that can easily be integrated into processing routines or scripts to build customized web-appications for decision-makers or end-users. See Figure below.
#
# A **Web Coverage Service** can be of great value, especially for scientists or developers who build applications and want to have access to large data volumes but do not want to store all the data on their local discs.
#
#
# 
#
#
# Example how a Web Coverage Service can be integrated into a commen (web-based) data processing chain
# ***
# ## What is OGC WC(P)S?
# The **Web Coverage Service (WCS)** is defined by the Open Geospatial Consortium (OGC) (2012) as:
#
# > *The OGC WCS supports **electronic retrieval of geospatial data** as 'coverages' - that is, digital geospatial information representing space/time-varying phenomena.*
#
#
# Therefore, WCS is a standard data-access protocol that defines and enables the web-based retrieval of multi-dimensional geospatial datasets. It provided access to the full range of geospatial data served from a web-server and allows for requesting only a subset of the data. A WCS support and trim operations, where either the data dimension (slice) or the data extent (trim) is reduced.
#
# Unlike Web Mapping Service (WMS), another widely-used OGC standard for geospatial datasets, which returns spatial data as an image or 'static map', WCS returns data in its raw form, which it's original semantics. This allows for further data processing and analysis or the building of web applications while at the same time the data volume transferred is minimised.
#
# WCS and WCPS are **machine-to-machine interfaces** and therefore aimed at technical data users or developers, rather than at end users.
#
#
# ### Three core WCS requests
# The WCS core supports three main HTTP requests (operations), which are submitted in the form of a URL:
# > the ** *GetCapabilities* ** request returns an XML document with information to the service and data provider and an overview of all the coverages (geospatial fields) available on the web server
#
# >> Example: http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.11&request=GetCapabilities
# > the ** *DescribeCoverage* ** request returns an XML document with metadata information of one specific coverage
# >> Example: get information about 2m air temperature coverage
# http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.11&request=DescribeCoverage&coverageId=temp2m
# > the ** *GetCoverage* ** request returns a full coverage encoded in a specified format, e.g GeoTiff, XML or netCDF
# >> Example: retrieve a 2D global field of 2m air temperature of 15 December 2013 in XML format
# http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.11&request=GetCoverage&coverageId=temp2m&subset=ansi("2013-12-15T00:00")&format=application/gml+xml
# ### The processing extension WCPS
# A **Web Coverage Processing Service** is an extension supported by the WCS 2.0 core specification and can optionally be implemented by a WCS server. WCSPS allows for crafting queries to be run on the data using a text based query language, similar to SQL.
# The extension specifies an additional WCS request:
# > the ***ProcessCoverages*** request returns a coverage encoded in a specified format (e.g. netCDF or csv) and allows for mathematical calculations on the requestes coverages.
# >> Example: Convert a 2D field of 2m air temperature for Italy from 31 December 2015 from K to degC
# http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=ProcessCoverages&query=for c in (temp2m) return encode (c[Lat(35.4:47.1),Long(6.6:18.5),ansi("2015-12-31T00:00")] - 273.15,"csv")
#
#
# ***
# You should have now a better understanding about the purpose of web services and the OGC Web Coverage Service in specific. The [next tutorial chapter](./02-WCS_core_requests.ipynb) will introduce you the basic setup of WCS core requests.
# ***
# © 2017 ECMWF
#
# This software is licensed under the terms of the Apache Licence Version 2.0 which can be obtained at http://www.apache.org/licenses/LICENSE-2.0. In applying this licence, ECMWF does not waive the privileges and immunities granted to it by virtue of its status as an intergovernmental organisation nor
# does it submit to any jurisdiction.