Common Request Parameters |
The VERSION parameter specifies the protocol version number. The format of the version number, and version negotiation, are described in Version Numbering and Negotiation.
The REQUEST parameter indicates which service operation is being invoked. The value shall be the name of one of the operations offered by the OGC Web Service Instance.
The FORMAT parameter specifies the output format of the response to an operation.
An OGC Web Service may offer only a subset of the formats known for that type of operation, but the server shall advertise in its Capabilities XML those formats it does support and shall accept requests for any format it advertises. A Service Instance may optionally offer a new format not previously offered by other instances, with the recognition that clients are not required to accept or process an unknown format. If a request contains a Format not offered by a particular server, the server shall throw a Service Exception (with code "InvalidFormat").
A Client may accept only a subset of the formats known for that type of operation. If a Client and Service do not support any mutually agreeable formats, the Client may, at its discretion, cease communicating with that service, or search for an intermediary service provider that performs format conversion, or allow the user to choose other disposition methods (e.g., saving to local storage or passing to helper application).
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.
Generally, OGC Web Service MIME types are chosen from among those in common use on the Internet. However, additional OGC-specific types have been adopted to distinguish among different types of XML-formatted content (the generic XML MIME types being text/xml and application/xml), as listed in Table 1.
Table 1 OGC Specific MIME Types
| MIME Type | Document Content |
| application/vnd.ogc.wms_xml | WMS Capabilities XML. |
| application/vnd.ogc.gml | Geography Markup Language XML. |
| application/vnd.ogc.se_xml | Service Exception XML. |
| application/vnd.ogc.se_inimage | Image overwritten with Exception message. |
| application/vnd.ogc.se_blank | Blank image because Exception occurred. |
The EXCEPTIONS parameter states the format in which to report errors.See on Service Exceptions, below.
The Spatial Reference System (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. This specification defines two namespaces, EPSG and AUTO, which are discussed below.
OGC Web Services are not required to support all possible SRSes, but shall advertise in their Capabilities XML those projections which they do offer and shall accept requests for all advertised projections. If a request contains an SRS not offered by a particular server, the server shall throw a Service Exception (code = "InvalidSRS").
Clients are not required to support all possible SRSes. If a Client and Service do not support any mutually agreeable SRS, the Client may, at its discretion, cease communicating with that service, or search for an intermediary service provider that performs coordinate transformations, or allow the user to choose other disposition methods.
The EPSG namespace makes use of the European Petroleum Survey Group tables [EPSG], 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 only the prefix and the identifier, not any additional parameters. This format is used both as the value of the SRS parameter in a service request and as the value of an 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, maximum latitude. The BBOX parameter values shall use the coordinate reference system units.
For the time being we only support EPSG: 4326.
The AUTO namespace is used for "automatic" projections; that is, for a class of projections that include an arbitrary center of projection. An SRS request parameter specifying an automatic projection includes the AUTO namespace prefix, a numeric projection identifier from the AUTO namespace, a numeric identifier from the EPSG [EPSG] namespace indicating what units are to be used for bounding boxes in that SRS, and values for the central longitude and latitude in decimal degrees:
AUTO:auto_proj_id,epsg_units_id,lon0,lat0
In a request for a georeferenced map or data, the complete AUTO SRS is specified including longitude, latitude, and units. In Capabilities XML, the longitude, latitude, and units variables are omitted because they are chosen by the client in a request for an AUTO SRS.
Example: A service instance indicates that it supports Auto Orthographic projection by including the element "AUTO:42003" in its Capabilities XML. A client may issue a GetMap request for a map in this projection, with bounding box in meters, centered at 100 degrees West longitude and 45 degrees North latitude, using the parameter "SRS=AUTO:42003,9001,-100,45".
The Bounding Box (BBOX) is a set of four comma-separated decimal, scientific notation, or integer values (if integers are provided where floating point is needed, the decimal point is assumed at the end of the number). These values specify the minimum X, minimum Y, maximum X, and maximum Y ranges, in that order, expressed in units of the SRS of the request, such that a rectangular area is defined in those units.
Figure 1
A Bounding Box should not have zero area.
If a request contains an invalid Bounding Box (e.g., one whose minimum X is greater than or equal to the maximum X, or whose minimum Y is greater than or equal to the maximum Y) the server shall throw an exception.
If a request contains a Bounding Box whose area does not overlap at all with the BoundingBox advertised in the Capabilities XML for the requested geodata object, the server should return empty content (e.g., a blank map, empty coverage file, null feature set) for that element. Any elements that are partly or entirely contained in the Bounding Box should be returned in the appropriate format.
If the Bounding Box values are not defined for the given SRS (e.g., latitudes greater than 90 degrees in EPSG:4326), the server should return empty content for areas outside the valid range of the SRS.
In the particular case of longitude, the following behavior may apply regarding the antimeridian at 180 degrees of longitude. There is a legitimate desire for maps that span the anti-meridian (for example, a map centered on the Pacific Ocean). However, a strict interpretation of the previous paragraph suggests that areas beyond 180 degrees should be shown as empty content; this corresponds to the STRICT constraint below. A server may choose to relax this behavior by instead applying the LOOSE constraint below. If minx is the west-most longitude in degrees and maxx is the east-most, then:
STRICT longitude constraint (default):
-180 <= Xmin < Xmax < 540
LOOSE longitude constraint (optional):
-180 <= minx="" <="" maxx="" +="" 360="" 540
EXAMPLES: minx,maxx values and the corresponding scope of the bounding box:
-180, 180 = Earth centered at Greenwich
0, 360 = Earth with Greenwich at left edge
120, 250 = Pacific Ocean
Some geospatial information may be available at multiple times (for example, an hourly weather map). An OGC Web Service may announce available times in its Capabilities XML, and some operations include a parameter for requesting a particular time. Depending on the context, time values may appear as a single value, a list of values, or an interval. When providing temporal information, Servers should declare a default value in Capabilities XML unless there is compelling reason to behave otherwise, and Servers shall respond with the default value if one has been declared and the Client request does not include a value.
Some geospatial information may be available at multiple elevations (for example, ozone concentrations at different heights in the atmosphere). An OWS may announce available elevations in its Capabilities XML, and some operations include a parameter for requesting a particular elevation. A single elevation value is an integer or real number whose units are declared by naming an EPSG datum. Depending on the context, elevation values may appear as a single value, a list of values, or an interval When providing elevation information, Servers should declare a default value in Capabilities XML unless there is compelling reason to behave otherwise, and Servers shall respond with the default value if one has been declared and the Client request does not include a value.
Some geospatial information may be available at other dimensions (for example, satellite images in different wavelength bands). The dimensions other than the four space-time dimensions are referred to as "sample dimensions". An OWS may announce available sample dimensions in its Capabilities XML, and some operations include a mechanism for including dimensional parameters. Each sample dimension has a Name and one or more valid values.
Most service requests require additional parameters (beyond REQUEST) to unambiguously state what result to construct. Each OGC Web Service specification defines the required and optional parameters for its operation(s).
Finally, the requests allow for optional vendor-specific parameters (VSPs) that will enhance the results of a request. Typically, these are used for private testing of nonstandard functionality prior to possible standardization. A generic client is not required or expected to make use of these VSPs.
Clients may read the internal DTD and formulate requests using any VSPs advertised therein.
Vendors should choose vendor-specific parameter names with care to avoid clashes with standard parameters.