Web Coverage Service

The WCS allows the end user to directly download raster imagery data in either JPEG2000 or GeoTIFF format. The WCS supports the following operations:

• GetCapabilities The GetCapabilities request is used to determine the supported Coverages; each FinishedCatalog product is listed and described as a Coverage.
• DescribeCoverage The DescribeCoverage request is used to obtain the detailed description of a supported Coverage.
• GetCoverage The GetCoverage request is used to obtain the actual product pixels (imagery) for download.

Typical Structure of a WCS Application

Service Details

The Maxar WCS supports KVP (Keyword Value Pair) request encoding only; SOAP (Simple Object Access Protocol) or other protocols are not supported.

The WCS does NOT support the following optional capabilities:

• Range subsetting
• Store capability; all Coverages are returned synchronously

The WCS treats each available product as a separate Coverage, therefore the imagery returned depends on the layer being accessed.

WCS Client-Server Architecture

The following architecture depicts a sample integration of WCS client and server applications. Client Viewer is a series of HTML pages running inside a web browser that can interact with the WCS server via client application through HTTP calls. The WCS client manages the interactions with WCS interfaces through HTTP requests and dynamically generates HTML that can run in a web browser.

The WCS server accepts requests from the WCS client and viewer client in the form of HTTP URL strings, and returns results encoded as XML, GIF, GML, and so on. The database stores geo-feature data that can be accessed and utilized by the WCS server to generate GML documents or draw Maps.

Sample WCS Client Server Application

WCS Service Details

The Maxar WCS provides vector metadata, including imagery footprints, in Geographic Markup Language (GML) format. The Maxar WCS supports the following OGC-defined operations:

GetCapabilities Operation

In response to the GetCapabilities request, the Service returns a description of the available Capabilities, including a list of all available Coverages. Since each Finished Product is defined as a Coverage, the GetCapabilities response can be quite large. In addition, as more data is added, the list of Coverages will grow and change over time, so clients must be careful if they are caching the results.

GetCapabilities Request Format

The GetCapabilities Request is formatted as shown; there are no other options available:

	https://evwhs.digitalglobe.com/deliveryservice/wcsaccess?service=WCS&request=GetCapabilities&version=1.1.1&connectId=<CONNECTID> Note: Replace <CONNECTID> with the connectId provided by Maxar. Parameters are not required to be in the same order as shown above.

GetCapabilities Response Format

In response to a GetCapabilities request, the Service returns an XML document that describes each available operation and Coverage.

DescribeCoverage Operation

DescribeCoverage Request Format

The client provides the following information in a Keyword Value Pair (KVP) format, where the "name" field is the key, and the "value" field is the value; the data is supplied in the format "key=value"; for example, "service=WCS".

DescribeCoverage Request Parameters

Name	Value	Short Description
service*	WCS	Web Coverage Service
version*	1.1.1	Request version
request*	DescribeCoverage	Request name
identifiers*	List of Coverages to be described e.g., 6085f54600b2a8a93137e48750a4441e	The Coverage(s) to be described; each product in the layers is a Coverage and can be requested; multiple identifiers are comma-separated; at least one valid identifier must be included. The Coverage identifiers can be obtained from the GetCapabilities response.
connectId*	Globally Unique Identifier <CONNECTID> supplied to the service user by Maxar.	Value for this parameter is a unique 32-digit alphanumeric value given by Maxar (see Connect ID). A valid Connect ID is mandatory for every request.

* mandatory parameter

DescribeCoverage Response Format

In response to a DescribeCoverage request, an XML document is returned that defines the details of each requested Coverage, using a "CoverageDescription" data structure. The elements of this data structure for this WCS are defined above. This data structure is repeated for each Coverage specified via the "identifiers" values in the DescribeCoverage request.

The following example requests a description of the specified Coverage:



https://evwhs.digitalglobe.com/deliveryservice/wcsaccess?SERVICE=WCS&REQUEST=DescribeCoverage&version=1.1.1&connectId=<CONNECTID>&identifiers=<FeatureID> Note: Replace <CONNECTID> with the connectId provided by Maxar. Replace <FEATUREID> with your desired featureID. Parameters are not required to be in the same order as shown above.

GetCoverage Operation

The GetCoverage request results in an image product being returned to the requesting client. Since the WCS protocol does not support mosaicked images across Coverages, separate GetCoverage requests are required for each Online FinishedCatalog product. Each Online FinishedCatalog product equates to a Coverage.

GetCoverage Request

The GetCoverage request is used to request a full-resolution product file in one of the supported formats, currently GeoTIFF and JPEG2000.

The client provides the following information in a Keyword Value Pair (KVP) format, where the "name" field is the key, and the "value" field is the value; the data is supplied in the format "key=value"; for example, "service=WCS".

GetCoverage Request Parameters

Name	Value	Short Description
service*	WCS	Web Coverage Service
version*	1.1.1	Request version
request*	GetCoverage	Request name
identifier*	A Coverage identifier e.g., 6085f54600b2a8a93137e48750a4441e	The Coverage to be described.
boundingBox*	35.6, -117.7,35.7,-117.6	The Bounding Box of the portion of the Coverage to be returned (minY,minX,maxY,maxX).
gridCRS	EPSG:4326 (each valid EPSG value for UTM)	The CRS in which the Coverage response will be returned; supported CRSs are WGS84 Lat/Long and WGS84 UTM. If not included, the default CRS of the projection will be returned; this will be WGS84 Lat/Long.
gridOffsets*	UTM: 0.5, 0.5 Lat/Long: .0000045, .0000045	Specifies the pixel size to be returned, in the X and Y dimensions. For gridCRS UTM values this is returned in meters. For gridCRS Lat/Long values this is returned in degrees/pixel. Minimum values are 0.5m and .0000045 degrees; these equate to full resolution data for WV01
format*	image/geotiff image/jp2 image/x-mrsid-image image/geopdf	The format in which the Coverage response will be returned. Only one value can be supplied.
connectId*	Character String	Value for this parameter is a unique 32-digit alphanumeric value given by Maxar (see Connect ID). A valid Connect ID is mandatory for every request.

* mandatory parameter

GetCoverage Response

The response to a valid GetCoverage request is a multi-part MIME message, consisting of an XML file containing Coverage metadata, and the Coverage file in the requested format. This Coverage file will consist of the portion of the Coverage contained within the bounding box supplied in the GetCoverage request. Any portion of the bounding box for which no imagery is available in the requested Coverage will contain black-filled pixels.

The following example requests a TIFF product of the same Coverage described in the above example:



https://evwhs.digitalglobe.com/deliveryservice/wcsaccess?service=WCS&version=1.1.1&request=GetCoverage&format=image/tiff&identifier=<FeatureID>&boundingBox=34.959843,-118.013832,36.019478,-117.814011,urn:ogc:def:crs:EPSG:4326&GridBaseCRS=urn:ogc:def:crs:EPSG:4326&GridOffsets=0.00010,0.00010&connectId=<CONNECTID> Note: Replace <CONNECTID> with the connectId provided by Maxar. Replace <FEATUREID> with your desired featureID. Parameters are not required to be in the same order as shown above.

	To see imagery in a generic image viewer, you will need to remove the first 21 lines of the response (i.e., the first part of the MIME message). Remove the MIME message to View Imagery in a Generic Viewer

Integration Procedure

A WCS client application is a program that communicates with the WCS server using the three functions: GetCapabilities, DescribeCoverage, and GetCoverage. More specifically, in a typical WCS client-server interaction, the following steps can be followed:

Step 1

The client must first request GetCapabilities from the WCS server in order to determine what the WCS server can do and what Coverage the WCS server can provide.

Understanding URL

The URL shown above contains Base URL and few parameters as explained in Request Parameters. The key parameter for this request is "request=GetCapabilities" which fetches the capabilities of Web Coverage Service and response in the form of XML data.

WCS GetCapabilities Request Parameters

Name	Value	Short Description
SERVICE*	WCS	See Web Coverage Service.
REQUEST*	GetCapabilities	The value for this parameter should always be "GetCapabilities" for step 1.
VERSION	1.1.1	See Web Coverage Service.
CONNECTID*	<CONNECTID> provided by Maxar	Value for this parameter is a unique 32-digit alphanumeric value given by Maxar (see Connect ID). A valid Connect ID is mandatory for every request.

* mandatory parameter

Response

In response to a GetCapabilities request, the WCS server produces an XML document containing the WCS server's service metadata, describing all the operations it supports, and providing information about the available Coverage. The client application has to parse the XML capabilities document to retrieve the necessary information used to request a Coverage. The Document Object Model (DOM) is a widely-used and efficient XML parser, which can be utilized to parse the XML document and retrieve the information. The DOM represents an XML document as a tree of nodes that can be easily traversed and edited with its standard interfaces.

The response XML to the GetCapabilities request contains the following details:

• WCS Service details, such as Name, Title, URL
• Contact Information, such as Person, Organization, Address, Telephone, Fax and Email
• WCS Capabilities, such as GetCapabilties, GetCoverage and DescribeCoverage along with respective formats and URLs.

Step 2

The client can request DescribeCoverage with the WCS server's capabilities information in order to get the Coverage information. Once a user has obtained a description of the supported Coverage, the GetCoverage request is used to access the metadata associated with one or more identifiers.

Understanding URL

The parameters available in the DescribeCoverage request are shown the table below. The client provides the following information in a Keyword Value Pair (KVP) format, where the "name" field is the key, and the "value" field is the value; the data is supplied in the format "key=value"; for example, "service=WCS".

DescribeCoverage Request Parameters

Name	Value	Short Description
service*	WCS	Web Coverage Service
version*	1.1.1	Request version
request*	DescribeCoverage	Request name
identifiers*	List of Coverages to be described e.g., 6085f54600b2a8a93137e48750a4441e	The Coverage(s) to be described; each product in the layers is a Coverage and can be requested; multiple identifiers are comma-separated; at least one valid identifier must be included. The Coverage identifiers can be obtained from the GetCapabilities response.
connectId*	Globally Unique Identifier <CONNECTID> supplied to the service user by Maxar.	Value for this parameter is a unique 32-digit alphanumeric value given by Maxar (see Connect ID). A valid Connect ID is mandatory for every request.

Response

In response to a valid DescribeCoverage request, the WCS returns a GML document containing zero or more Coverages that match the request criteria. Each Coverage is described by a list of properties contained in a GML document.

Step 3

To get the description of the supported GetCoverage, the user can use the following URL:

Understanding URL

The client provides the following information in a Keyword Value Pair (KVP) format, where the "name" field is the key, and the "value" field is the value; the data is supplied in the format "key=value"; for example, "service=WCS". See API Reference for the URL parameters for the GetCoverage request.

Response

In response to a GetCoverage request, a GML document is returned that defines the elements of the requested Coverage. The elements of each supported Feature type are defined in API Reference. In the cases where returned data is dependent on the value of elements within the Coverage, the dependency is noted in the Description column.

Service Exceptions

In the event that a Web Coverage Service encounters an error while processing a request or receives an unrecognized request, it will generate an XML document indicating that an error has occurred.

An <ExceptionReport> element will contain one or more WCS processing exceptions specified using the <Exception> element. The mandatory version attribute is used to indicate the version of the service exception report schema. For this version of the specification, this value is fixed at 1.1.0. Individual exception messages are contained within the <ExceptionText> element.

The following is an example of an exception report. This exception indicates that the first insert statement failed because of a missing closing XML tag in the request.

1
2
3
4
5
6
7
8
9
<?xml version="1.0" encoding="UTF-8" ?>
<ows:ExceptionReport version="1.1.0" 
xsi:schemaLocation="http://www.opengis.net/ows/1.1 http://evwhs.digitalglobe.com/deliveryservice/schemas/ows/1.1.0/owsAll.xsd" 
xmlns:ows="http://www.opengis.net/ows/1.1" 
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <ows:Exception exceptionCode="NoApplicableCode">
        <ows:ExceptionText>DescribeCoverage: Could not find coverage: 334034 null Translator error DescribeCoverage: Could not find coverage: 334034</ows:ExceptionText>
    </ows:Exception>
</ows:ExceptionReport>

WCS Layers

API Reference

This section provides a list of all possible request parameters for every WCS operation as well as detailed information about corresponding response.

The client should provide the respective information in a Keyword Value Pair (KVP) format for every WCS request, where the "name" field is the key, and the "value" field is the value; the data is supplied in the format "key=value"; for example, "service=WCS".

GetCapabilities

The following table shows all possible request parameters for GetCapabilities operation of WCS server.

WCS GetCapabilities Request Parameters

Name	Value	Short Description
SERVICE*	WCS	See Web Coverage Service.
REQUEST*	GetCapabilities	The value for this parameter should always be "GetCapabilities" for step 1.
VERSION	1.1.1	See Web Coverage Service.
CONNECTID*	<CONNECTID> provided by Maxar	Value for this parameter is a unique 32-digit alphanumeric value given by Maxar (see Connect ID). A valid Connect ID is mandatory for every request.

*mandatory parameter

GetCoverage

The following table shows the URL parameters for the GetCoverage request.

GetCoverage Request Parameters

Name	Value	Short Description
service*	WCS	Web Coverage Service
version*	1.1.1	Request version
request*	GetCoverage	Request name
identifier*	A Coverage identifier e.g., 6085f54600b2a8a93137e48750a4441e	The Coverage to be described.
boundingBox*	35.6, -117.7,35.7,-117.6	The Bounding Box of the portion of the Coverage to be returned (minY,minX,maxY,maxX).
gridCRS	EPSG:4326 (each valid EPSG value for UTM)	The CRS in which the Coverage response will be returned; supported CRSs are WGS84 Lat/Long and WGS84 UTM. If not included, the default CRS of the projection will be returned; this will be WGS84 Lat/Long.
gridOffsets*	UTM: 0.5, 0.5 Lat/Long: .0000045, .0000045	Specifies the pixel size to be returned, in the X and Y dimensions. For gridCRS UTM values this is returned in meters. For gridCRS Lat/Long values this is returned in degrees/pixel. Minimum values are 0.5m and .0000045 degrees; these equate to full resolution data for WV01
format*	image/geotiff image/jp2 image/x-mrsid-image image/geopdf	The format in which the Coverage response will be returned. Only one value can be supplied.
connectId*	Character String	Value for this parameter is a unique 32-digit alphanumeric value given by Maxar (see Connect ID). A valid Connect ID is mandatory for every request.

*mandatory parameter

DescribeCoverage

DescribeCoverage Request Parameters

Name	Value	Short Description
service*	WCS	Web Coverage Service
version*	1.1.1	Request version
request*	DescribeCoverage	Request name
identifiers*	List of Coverages to be described e.g., 6085f54600b2a8a93137e48750a4441e	The Coverage(s) to be described; each product in the layers is a Coverage and can be requested; multiple identifiers are comma-separated; at least one valid identifier must be included. The Coverage identifiers can be obtained from the GetCapabilities response.
connectId*	Globally Unique Identifier <CONNECTID> supplied to the service user by Maxar.	Value for this parameter is a unique 32-digit alphanumeric value given by Maxar (see Connect ID). A valid Connect ID is mandatory for every request.

*mandatory parameter