DGCS Portal

DigitalGlobe Cloud Services Documentation Portal

Welcome to the DigitalGlobe Cloud Services Documentation Portal. You'll find comprehensive guides and documentation to help you start working with DigitalGlobe Cloud Services as quickly as possible. Let's jump right in!

Get Started    

Introduction to OGC Protocols

Basic Service Elements

This section of the Developer Guides specifies aspects of Web Map Server behavior that are independent of particular operations or are common to several operations.

HTTP Request

In the client-server computing model, HTTP functions as a request-response protocol. For example, in HTTP, a web browser acts as a client, while an application running on a computer hosting a web site functions as a server. The client submits an HTTP request message to the server. The server, which stores content or provides resources, such as HTML files and images, returns a response message to the client. A response contains completion status information about the request and may contain any content requested by the client in its message body.

An HTTP Uniform Resource Locator (URL) locates the Online Resource of each operation supported by a service instance. The URL may be different for each operation, or the same, at the discretion of the service provider.

HTTP supports two request methods: GET and POST. One or both of these methods may be defined for a particular web service and offered by a service instance. The use of the Online Resource URL differs in each case.

HTTP GET

An Online Resource URL intended for HTTP GET requests, is, in fact, only a URL prefix to which additional parameters must be appended in order to construct a valid Operation request. A URL prefix is defined as an opaque string including the protocol, hostname, optional port number, path, a question mark ‘?’, and, optionally, one or more server-specific parameters ending in an ampersand ‘&’. The prefix uniquely identifies the particular service instance.

A client can append the necessary request parameters as name/value pairs in the form “name=value&”. The resulting URL must be valid according to the HTTP Common Gateway Interface (CGI) standard, which mandates the presence of ‘?’ before the sequence of query parameters and the ‘&’ between each parameter.

The URL prefix must end in either a ‘?’ (in the absence of additional server-specific parameters) or a ‘&’. In practice, however, Clients should be prepared to add a necessary trailing ‘?’ or ‘&’ before appending the operation parameters defined as per DG-WMS specification in order to construct a valid request URL.

A General GET Request

URL COMPONENT
DESCRIPTION

URL prefix of service operation. [ ] denotes 0 or 1 occurrence of an optional part; {} denotes 0 or more occurrences. The prefix is entirely at
the discretion of the service provider.

name=value&

One or more standard request parameter name/value pairs defined by a web feature service. The actual list of required and optional parameters is mandated by each specific service.

Reserved Characters in HTTP GET Query

CHARACTER
RESERVED USAGE

?

Separator indicating start of query string.

&

Separator between parameters in query string.

=

Separator between name and value of parameter.

/

Separator between MIME type and subtype in format parameter value.

:

Separator between Namespace and Identifier in SRS parameter value.

,

Separator between individual values in list-oriented parameters.

HTTP POST

  • An Online Resource URL intended for HTTP POST requests is a complete and valid URL to which clients transmit encoded requests in the body of the POST document. DGCS-WMTS does not require additional parameters to be appended to the URL in order to construct a valid target for the Operation request. The following figure shows a sample of an HTTP Post request.
Sample HTTP POST Request/Response

Sample HTTP POST Request/Response

Advantages of HTTP POST Instead of HTTP GET

  • The Parameter’s name and value are visible to the user and to anyone who is looking at the URL in the browser.
  • GET requests are passed as the URL string and are therefore limited by the URL length limit specified by the browser.
  • HTTP Post method can upload files to the server.

HTTPS

In addition to or instead of offering web map services using the HTTP protocol, DigitalGlobe offers web map services using HTTPS. HTTPS is HTTP over a secure communication channel which allows encrypted information to be transferred between machines over the World Wide Web.

The use of HTTPS does not affect the description of the requests and responses described in this document, but may require additional actions to be taken on both the client and the service in order to initiate secure communication.

HTTP Response

Upon receiving a valid HTTP request, the service sends a response corresponding to the request exactly as detailed, based on parameters for the specific operations.

Response objects will be accompanied by other HTTP entity headers as appropriate and to the extent possible. In particular, the Expires and Last-Modified headers provide important information for caching; Content-Length may be used by clients to know when data transmission is complete and to efficiently allocate space for results, and Content-Encoding or Content-Transfer-Encoding may be necessary for proper interpretation of the results. If the request is invalid, the service issues a Service Exception.

Output Formats

The optional “outputFormat” attribute specifies the format of the response to a Cloud Service request.

The default value is text/xml; “subtype=gml/3.1.1” indicating that a valid GML3 document, that validates against a valid GML3 application schema, must be generated.

For backward compatibility, the values “GML2” or “text/xml; subtype=gml/2.1.2” may be specified indicating that a valid GML2 document that validates against a valid GML2 application schema, must be generated.

The next table summarizes the possible values for the “outputFormat” attribute.

Values for OutputFormat Attribute

OUTPUTFORMAT VALUE
DESCRIPTION

GML2

This value is kept for backward compatibility and indicates that an XML instance document
must be generated that validates against a GML2 application schema.

text/xml; subtype=gml/2.1.2

Same as GML2.

text/xml; subtype=gml/3.1.1

This value indicates that an XML instance document must be generated that validates
against a GML3 application schema. This is the default values of the outputFormat attribute if the attribute is not specified in the GetFeature request.

Request Parameters

As per the specification standards, a client application has to form the HTTP(S)-based URL dynamically, based on the requirement or operation it has to perform.

Base URL

For every request to DigitalGlobe services, the client needs to append parameters to the base URL. DigitalGlobe provides the base URL for each service.

Username and Password are required only for some accounts, the ones within the AuthenticationCredentialsRequired Security Group.

An alternative way for these users to do authentication is to provide a dgtoken in the request.
All others simply require the Connect ID.

ConnectID

The ConnectID parameter name must be appended as a unique 32 digit alphanumeric value to the base URL. It is a mandatory parameter which should be part of every request the client makes to the server. Please contact DigitalGlobe to get your unique ConnectID.

ConnectID format:

xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx where x is an alpha-numeric character

Service

The service parameter defines the type of service the client is requesting. DigitalGlobe provides different OGC services including WMS, WFS, WMTS and WCS. Therefore, the client must provide appropriate values based on the service requested.

Example: service=WMTS

Version

The version parameter specifies the protocol version number. The version number indicates the specification compliance level as defined by OGC. The format of the version number contains three positive integers separated by decimal points in the form, “x.y.z”. The numbers “y” and “z” will never exceed 99. Each Feature Service provided by DigitalGlobe is numbered independently according to OGC specification standards.

The version number appears in the following two places:

  • In the response XML of the GetCapabilities request describing the service
  • In the parameter list of client requests to the service

In response to a GetCapabilities request containing a version number, a service responds with output that conforms to that version of the specification, or negotiates a mutually agreeable version if the requested version is not implemented on the server. If no version number is specified in the request, the server responds with the highest version it understands and labels the response accordingly. Please refer to the OGC specification for service negotiation rules.

Example: version=1.0.0 (recommended until DigitalGlobe implements newer version per OGC specification)

Request

The request parameter indicates which service operation is being invoked. The value is the name of one of the operations offered by the DigitalGlobe Service. Refer to the documentation of each service for descriptions of supported operations.

Example: request=GetCapabilities

Format

The format parameter specifies the output format of the response to a request operation. Formats are expressed in both Capabilities XML and in operation requests using MIME types. Each Operation has a distinct list of supported formats. Some formats may be offered by several operations, and are then duplicated as needed in each list. If a request contains a format not offered by the service, the service throws a Service Exception (with the code “InvalidFormat”).

Example: format=image/jpeg

Exceptions

The exceptions parameter in a request indicates the format in which the Client wants to be notified of Service Exceptions. Individual error messages appear as <ServiceException> elements within the <ServiceExceptionReport> in the Service Exception XML. Refer to the documentation of each service for more details on service exceptions.

Example: exceptions=application/vnd.ogc.se_xml

Request Parameter Rules

While forming the request URL, client applications should follow specific rules:

  • Parameter names are not case sensitive, but parameter values are case sensitive.
  • Parameter names are typically shown in uppercase for typographical clarity, not as a requirement.
  • Parameters in a request may be specified in any order.
  • When request parameters are duplicated with conflicting values, the response from the server may be undefined.
  • Parameters consisting of lists (for example, BBOX, LAYERS and STYLES in WMS GetMap) should use the comma (“,”) as the separator between items in the list. Do not use dditional white to delimit list items.
  • Two successive commas indicate an empty item, as does a leading comma or a trailing comma. An empty list (“ “) shall be interpreted either as a list containing no items or as a list containing a single empty item, depending on the context.

Introduction to OGC Protocols