Basic Service Elements

This section specifies aspects of Web Map Server (WMS) 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. Specifically, 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 (e.g., HTML files and images) or generates such content as required, or performs other functions on behalf of the client, 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 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 an '&'. In practice, however, Clients should be prepared to add a necessary trailing '?' or '&' before appending the operation parameters defined by the specification in order to construct a valid request URL.

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. The Service 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

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, Maxar 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.

HTTP Responses and WMS

Response objects are accompanied by the appropriate Multipurpose Internet Mail Extensions (MIME) type for that object, as shown in the table below.

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 "GML" 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 following table summarizes the possible values for the "outputFormat" attribute.

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 Maxar services, the client needs to append parameters to the base URL. Maxar provides the base URL for each service.

Username and Password are required only for some accounts, the ones within the AuthenticationCredentialsRequired Security Group. All others simply require the Connect ID.

Connect ID

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 Maxar to get your unique Connect ID.

Service

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

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 Service provided by Maxar is numbered independently according to OGC specification standards.

• The latest version of WMS implemented for the OGC specification is 1.1.1.

• The latest version of WFS implemented for the OGC specification is 1.1.0.

• The latest version of WCS implemented for the OGC specification is 1.1.0.

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.

Request

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

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 server, the server throws a Service Exception (with the code "InvalidFormat").

Exceptions

The exceptions parameter in a request indicates the format in which the Client wants to be notified of Service Exceptions.

The only value of the exceptions parameter that is defined for WCS, WFS, and WMS is "application/vnd.ogc.se_xml", which means "Service Exception XML."

Individual error messages appear as <ServiceException> elements within the <ServiceExceptionReport> in Service Exception XML.

See individual Service documentation for more information on Service Exceptions.

SRS (Spatial Reference System)

The SRS is a text parameter that names a horizontal coordinate reference system code. The name includes a namespace prefix, a colon, a numeric identifier, and possibly a comma followed by additional parameters. The Maxar WMS implementation is defined with EPSG and AUTO namespaces. If a request contains an SRS not offered by a Maxar WMS server, the server throws a Service Exception (code = "InvalidSRS").

The EPSG namespace makes use of the European Petroleum Survey Group tables, which define numeric identifiers (the EPSG "CRS code," corresponding to the field "COORD_REF_SYS_CODE" in the EPSG database) for many common projections and which associate projection or coordinate metadata (such as measurement units or central meridian) for each identifier. An SRS name in the EPSG namespace includes the prefix and the identifier. This format is used both as the value of the SRS parameter in a service request and as the value of an <SRS> element in the Capabilities XML.

When the SRS parameter specifies a Geographic Coordinate Reference System, e.g. "EPSG:4326", the returned image is implicitly projected using a pseudo-Plate Carrée projection that plots longitude along the X-axis and latitude along the Y-axis. The BBOX request parameter values for such a coordinate reference system shall be specified in the order minimum longitude, minimum latitude, maximum longitude, and maximum latitude.

Bounding Box (BBOX)

Bounding Box details vary slightly per Service. Refer to the section below for the applicable Service.

WCS and WFS

The Bounding Box (BBOX) is a set of four comma-separated decimal, scientific notation or integer values representing the geo-referenced bounding parameters of the Area Of Interest (AOI). These values specify the minimum Y, minimum X, maximum Y, and maximum X ranges, in that order, expressed in units of the Spatial Reference System (SRS) of the request, such that a rectangular area is defined in those units.

The four bounding box values indicate the outside edges of a rectangle: minimum X is the left edge, maximum X the right, minimum Y the bottom, and maximum Y the top. The relation of the Bounding Box to the image pixel matrix is shown: the bounding box goes around the "outside" of the pixels of the image rather than through the centers of the border pixels. In this context, individual pixels have an area.

Rules to follow while defining BBOX:

• A Bounding Box should not have zero area.
• Minimum X should be less than or equal to the Maximum X and Minimum Y should be less than or equal to the Maximum Y.

WMS

The Bounding Box (BBOX) is a set of four comma-separated decimal, scientific notation or integer values representing the geo-referenced bounding parameters of the Area Of Interest (AOI). These values specify the minimum X, minimum Y, maximum X, and maximum Y ranges, in that order, expressed in units of the Spatial Reference System (SRS) of the request, such that a rectangular area is defined in those units.

The four bounding box values indicate the outside edges of a rectangle: minimum X is the left edge, maximum X the right, minimum Y the bottom, and maximum Y the top. The relation of the Bounding Box to the image pixel matrix is shown: the bounding box goes around the "outside" of the pixels of the image rather than through the centers of the border pixels. In this context, individual pixels have an area.

Rules to follow while defining BBOX:

• A Bounding Box should not have zero area.
• Minimum X should be less than or equal to the Maximum X and Minimum Y should be less than or equal to the Maximum Y.

Type Name

If additional metadata about either all Features in a particular tile, or a single Feature included in a particular tile is needed, it can be retrieved by the typeName from the getFeature Request.

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) should use a comma (",") as the separator between items in the list. Do not use additional whitespace 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.