02-Web Coverage Service (WCS) core requests

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: http://earthserver.ecmwf.int/rasdaman/ows?
Service and version specification: service=WCS&version=2.0.1&

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.

Optional parameters:

  • DescribeCoverage: &coverageId=coverageId
  • GetCoverage:
    • &coverageId=coverageId
    • &subset=axisSubset1&subset=axisSubset2...
      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>
    • &format=formatSupported
      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.

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

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.

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)


  • Retrieve the global field of 2m air temperature for 6 July 2010 at 00 UTC encoded as XML (default). (Reduction from 3D to 2D)


  • 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 Colouring on the fly)


Trim operation (extent reduction)

You now know how to access and retrieve data from a WCS server using the WCS core requests. The next tutorial chapter 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.

© 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.