#!/usr/bin/env python
# coding: utf-8

# # 02-Web Coverage Service (WCS) core requests

# <a href="./01-OGC_WCS.ipynb"><< 01-Introduction to web services and OGC</a>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space>&nbsp;<space> <a href="./03-WCPS_extension.ipynb">03-WCPS_extension >></a>

# ## Basic Web Coverage Service (WCS) request setup

# A WCS request can be divided into three main components: 
#   * Service endpoint, 
#   * request type and 
#   * optional parameters  
# 
# All components are concatenated with a *"&"* into one single URL. 

# ### Example of a manual WCS request setup

# > **Service endpoint:** <a href="http://earthserver.ecmwf.int/rasdaman/ows?" target="_blank">http://earthserver.ecmwf.int/rasdaman/ows?</a>  
# > **Service and version specification:** <font color="blue">service=WCS&version=2.0.1&</font>

# > **Request type:**  
# There are three core request types. A "&" indicates that the request requires an optional add-on. Therefore, *DescribeCoverage* and *GetCoverage* requests require further specifications.
# - [<font color="blue">GetCapabilities</font>](#get_capabilities)
# - [<font color="blue">DescribeCoverage&</font>](#describe_coverage)
# - [<font color="blue">GetCoverage&</font>](#get_coverage)

# > ***Optional* parameters:**  
# - **DescribeCoverage:**  <font color="blue"><b>&coverageId=</b><i>coverageId</i></font>
# - **GetCoverage:**  
#   - <font color="blue"><b>&coverageId=</b><i>coverageId</i></font>
#   - <font color="blue"><b>&subset=</b><i>axisSubset1</i>&subset=<i>axisSubset2</i>...</font>  
# With the add-on **&subset** a coverage axis can be subsetted. For every subsetting operation a subset request has to be concatenated. If you want to do e.g. a temporal (time axis) and spatial subset (latitude and longitude axes), you have to concatenate three subset requests. If no **&subset** is specified, the entire coverage is requested, which can be multiple GBs of data</p>  
#   - <font color="blue"><b>&format=</b><i>formatSupported</i></font>  
# With the add-on **&format** a custom format can be specified. The supported formats are specified in the ***GetCapabilites document***. The default format is application/gml+xml. If the format parameter is not specified, the result is returned in a xml file. 
#   Following formats are currently supported by OGC WCS 2.0.1:  
#  
#   >> * **netCDF:** applications/netcdf
# * **JPEG2000:** image/jp2
# * **GeoTIFF:** image/tiff
# * **XML:** application/gml+xml
# * **PNG:** image/png
# 
# 

# ***

# The following sections show how the concatenated strings per request will look like.   
# Examples base on ERA-interim 2m air temperature global fields, 6-hourly values from 1 January 1979 to 31 December 2015.

# ## <a id='get_capabilities'></a><font color="black"><i>GetCapabilites</i> request</font>

# <a href="http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCapabilities" target="_blank">http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCapabilities</a>

# The ***GetCapabilities*** request returns the ***Capabilities document***, which is a XML-document that gives general information to the Web Coverage Service Server. If you use the WCS Server for the first time, the GetCapabilities documents is helpful to see what the service offers.  
# 
# The XML tree contains following child elements:
# * **Service Identification**: General information about the Web Coverage Service and WCS profiles it supports
# * **Service Provider**: Name and contact details about the service and data provider
# * **OperationsMetadata**: Supported WCS operations of the service
# * **ServiceMetadata**: Supported format encodings and interpolations methods of the service
# * **Contents**: Available data sets of the service
# 

# ***

# ## <a id='describe_coverage'></a><font color="black"><i>DescribeCoverage</i> request</font>

# <a href="http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=DescribeCoverage&coverageId=temp2m" target="_blank">http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=DescribeCoverage&coverageId=temp2m</a>

# The ***DescribeCoverage*** request returns a ***CoverageDescription*** document, that contains the metadata of a dataset encoded in XML.  
# 
# The example below shows the metadata of the coverage "temp2m", which is ERA-interim 2m air temperature. Important XML tree child elements are:
# * **boundedBy**: this shows you the dimension of the coverage (number and name of axes as well as their dimensions)
# * **domainSet**: this shows you the resolution of each axis. In the example, the spatial resolution is 0.5 deg (~50 km) and the temporal resolution is a quarter of a day, meaning 6 hours.

# ***

# ## <a id='get_coverage'></a><font color="black"><i>GetCoverage</i> request</font>

# The ***GetCoverage*** operation requests the actual spatial data. The power of the GetCoverage request is the ability to subset domains (spatial and temporal) and to encode the output in different formats. All examples will take 2m air temperature as example coverage.

# ### Slice ooperation (dimension reduction)

# With the subset parameter, the dimensionality of the coverage can be reduced. From a multi-dimensional data cube, a **time series of a specific latitude/longitude grid point** or a **2D field for one specific time** can be retrieved. Examples are provided below.
# 
# By default, the data is returned in a XML file. The XML tree child element **rangeSet**  contains the actual data.
# 
# - Retrieve the **2m  air temperature time series** for every time step for the location Reading, UK. (Reduction from 3D to 1D)  
# 
# <a href='http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=Lat(51.0)&subset=Long(-1.0)&subset=ansi("2014-01-01T00:00","2014-12-31T18:00")&format=application/gml+xml' target="_blank">http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=Lat(51.0)&subset=Long(-1.0)&subset=ansi("2014-01-01T00:00","2014-12-31T18:00")&format=application/gml+xml</a>
# 

# - Retrieve the **global field of 2m  air temperature** for 6 July 2010 at 00 UTC encoded as XML (default). (Reduction from 3D to 2D) 
# 
# <a href='http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=ansi("2010-07-06T00:00")&format=application/gml+xml' target="_blank">http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=ansi("2010-07-06T00:00")&format=application/gml+xml</a>

# - Retrieve the **global field of 2m  air temperature** for 30 November 2010 at 00 UTC encoded as png image. (Reduction from 3D to 2D)
# 
# *(NOTE: for a coloured output a colour-scheme has to be applied on-the-fly - see <a href="./03-WCPS_extension.ipynb#colouring_wcps">Colouring on the fly</a>)*
# 
# <a href='http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=ansi("2010-11-30T00:00")&format=image/png' target="_blank">http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=ansi("2010-11-30T00:00")&format=image/png</a>

# ### Trim operation (extent reduction)

# - Retrieve the **2m  air temperature for Europe** on 15 August 2003 at 12 UTC encoded as XML. (Reduction from 3D to a 2D subset) 
# 
# <a href='http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=Lat(-30.0,65.0)&subset=Long(35.0,80.0)&subset=ansi("2010-08-15T00:00")&format=application/gml+xml' target="_blank">http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=Lat(-30.0,65.0)&subset=Long(35.0,80.0)&subset=ansi("2010-08-15T00:00")&format=application/gml+xml</a>

# - Retrieve the **2m  air temperature for Europe** on 15 August 2003 at 12 UTC encoded as netCDF. (Reduction from 3D to a 2D subset)
# 
# <a href='http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=Lat(-30.0,65.0)&subset=Long(35.0,80.0)&subset=ansi("2010-08-15T00:00")&format=application/netcdf' target="_blank">http://earthserver.ecmwf.int/rasdaman/ows?service=WCS&version=2.0.1&request=GetCoverage&coverageId=temp2m&subset=Lat(-30.0,65.0)&subset=Long(35.0,80.0)&subset=ansi("2010-08-15T00:00")&format=application/netcdf</a>

# ***

# You now know how to access and retrieve data from a WCS server using the WCS core requests. The [next tutorial chapter](./03-WCPS_extension.ipynb) introduces you to Web Coverage *Processing* Service, which is an extension of the WCS core suite and a powerful tool to access, process and retrieve spatial data on-the-fly.

# ***

# &copy; 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.