Skip to content

WMS vendor parameters

WMS vendor parameters are non-standard request parameters that are defined by an implementation to provide enhanced capabilities. GeoServer supports a variety of vendor-specific parameters.

General Vendor Options

These vendor options are available for all operations.

content-disposition ^^^^^^^^^^^^^^^^^^^

The content-disposition parameter directs how a web browser directed to handle returned content. The syntax is::

content-disposition=

Where content-disposition =attachment to direct the browser to save the content to disk.

Where content-disposition=inline asks the browser to display the content. Note this may present performance issues when asked to display very large content.

filename ^^^^^^^^

The filename parameter provides a suggested filename when a browser saves a file (e.g. to Downloads folder). The syntax is::

filename=

An example of filename use is::

filename=features.json

When service output is saved as a file, the vendor-option filename is used to provide the file name used.

GetCapabilities Request

format

The format parameter can be used to request capabilities documents in a certain format. If the requested format is not supported the default format will be used. Refer to the GetCapabilities response for the list of supported formats, which differs according to the WMS version.

An example request:

http://localhost:8080/geoserver/ows?service=wms&version=1.1.1&request=GetCapabilities&format=text/xml

<?xml version="1.0" encoding="UTF-8"?>
<WMT_MS_Capabilities version="1.1.1" updateSequence="247">
   <Capability>
      <Request>
         <GetCapabilities>
            <Format>application/vnd.ogc.wms_xml</Format>
            <Format>text/xml</Format>
...

Note

Currently this parameter can only be used to request WMS 1.1.1 capabilities documents encoded in text/xml, if used with other WMS versions or other formats it will have no effect. application/json is not supported.

namespace

The namespace parameter causes WMS GetCapabilities responses to be filtered to only contain layers in a particular namespace. The syntax is:

namespace=<namespace>

where <namespace> is the namespace prefix.

Warning

Using an invalid namespace prefix will not cause an error, but the capabilities document returned will contain no layers, only layer groups.

Note

This affects the capabilities document only, not other requests. Other WMS operations will still process all layers, even when a namespace is specified.

rootLayer

The rootLayer parameter can be used to request capabilities documents to include or not a top level root Layer container. By default this top level root is always included as a parent of the configured layers and groups. The default can be changed at the service (WMS) level, or at the layer / group level.

Using this parameter it is possible to exclude the default root when the resulting document has a single top element (e.g. a single group with nested children). To do that, use the false value.

The parameter can also be used to override what is defined at the WMS or layer / group level. For example if the service is configure to exclude the Root element, we can force it with rootLayer=true.

An example request:

http://localhost:8080/geoserver/ows?service=wms&version=1.1.1&request=GetCapabilities&rootLayer=false

An example with XML POST:

<?xml version="1.0" encoding="UTF-8"?>
<ogc:GetCapabilities xmlns:ogc="http://www.opengis.net/ows"
            xmlns:gml="http://www.opengis.net/gml"
   version="1.1.1" service="WMS" rootLayer="false">
</ogc:GetCapabilities>

GetMap Request

angle

The angle parameter rotates the output map clockwise around its center. The syntax is:

angle=<x>

where <x> is the number of degrees to rotate by.

Map rotation is supported in all raster formats, PDF, and SVG when using the Batik producer (which is the default).

buffer

The buffer parameter specifies the number of additional border pixels that are used in the GetMap and GetFeatureInfo operations. The syntax is:

buffer=<bufferwidth>

where <bufferwidth> is the width of the buffer in pixels.

In the GetMap operation, buffering includes features that lie outside the request bounding box, but whose styling is thick enough to be visible inside the map area.

In the GetFeatureInfo operation, buffering creates a "search radius" around the location of the request. Feature info is returned for features intersecting the search area. This is useful when working with an OpenLayers map (such as those generated by the Layer Preview page) since it relaxes the need to click precisely on a point for the appropriate feature info to be returned.

In both operations GeoServer attempts to compute the buffer value automatically by inspecting the styles for each layer. All active symbolizers are evaluated, and the size of the largest is used (i.e. largest point symbolizer, thickest line symbolizer). Automatic buffer sizing cannot be computed if:

  • the SLD contains sizes that are specified as feature attribute values
  • the SLD contains external graphics and does not specify their size explicitly

In this event, the following defaults are used:

  • 0 pixels for GetMap requests
  • 5 pixels for GetFeatureInfo requests (a different min value can be set via the org.geoserver.wms.featureinfo.minBuffer system variable, e.g., add -Dorg.geoserver.wms.featureinfo.minBuffer=10 to make the min buffer be 10 pixels)

If these are not sufficiently large, the explicit parameter can be used.

cql_filter

The cql_filter parameter is similar to the standard filter parameter, but the filter is expressed using ECQL (Extended Common Query Language). ECQL provides a more compact and readable syntax compared to OGC XML filters. For full details see the ECQL Reference and CQL and ECQL tutorial.

If more than one layer is specified in the layers parameter, then a separate filter can be specified for each layer, separated by semicolons. The syntax is:

cql_filter=filter1;filter2...

An example of a simple CQL filter is:

cql_filter=INTERSECTS(the_geom,%20POINT%20(-74.817265%2040.5296504))

sortBy

The sortBy parameter allows to control the order of features/rasters displayed in the map, using the same syntax as WFS 1.0, that is:

  • &sortBy=att1 A|D,att2 A|D, ... for a single layer request
  • &sortBy=(att1Layer1 A|D,att2Layer1 A|D, ...)(att1Layer2 A|D,att2Layer2 A|D, ...)... when requesting multiple layers

Care should be taken when using it as it has different behavior for raster layers, vector layers, and layer groups. In particular:

  • | For raster layers, sortBy maps to a "SORTING" read parameter that the reader might expose (image mosaic exposes such parameter). | In image mosaic, this causes the first granule found in the sorting will display on top, and then the others will follow. | Thus, to sort a scattered mosaic of satellite images so that the most recent image shows on top, and assuming the time attribute is called ingestion in the mosaic index, the specification will be &sortBy=ingestion D.

  • | For vector layers, sortBy maps to a sort by clause in the vector data source, and then painting happens using the normal "painter model" rules, so the first item returned is painted first, and then all others on top of it. | Thus, to sort a set of event points so that the most recent event is painted on top, and assuming the attribute is called "date" in the vector layer, the specification will be &sortBy=date or &sortBy=date A (ascending direction being the default one).

  • | For layer groups, the sort specification is going to be copied over all internal layers, so the spec has to be valid for all of them, or an error will be reported. | An empty spec can be used for layer groups in this case, for example, layers=theGroup,theLayer&sortBy=(),(date A)

env

The env parameter defines the set of substitution values that can be used in SLD variable substitution. The syntax is:

env=param1:value1;param2:value2;...

See Variable substitution in SLD for more information.

featureid

The featureid parameter filters by feature ID, a unique value given to all features. Multiple features can be selected by separating the featureids by comma, as in this example:

featureid=states.1,states.45

filter

The WMS specification allows only limited filtering of data. GeoServer enhances the WMS filter capability to match that provided by WFS. The filter parameter can specify a list of OGC XML filters. The list is enclosed in parentheses: ( ). When used in a GET request, the XML tag brackets must be URL-encoded.

If more than one layer is specified in the layers parameter then a separate filter can be specified for each layer.

An example of an OGC filter encoded in a GET request is:

filter=%3CFilter%20xmlns:gml=%22http://www.opengis.net/gml%22%3E%3CIntersects%3E%3CPropertyName%3Ethe_geom%3C/PropertyName%3E%3Cgml:Point%20srsName=%224326%22%3E%3Cgml:coordinates%3E-74.817265,40.5296504%3C/gml:coordinates%3E%3C/gml:Point%3E%3C/Intersects%3E%3C/Filter%3E

An example of an OGC filter encoding standard 2.0 in a GET request is:

filter=%3Cfes%3AFilter%20xmlns%3Axsi%3D%22http%3A%2F%2Fwww.w3.org%2F2001%2FXMLSchema-instance%22%20xmlns%3Agml%3D%22http%3A%2F%2Fwww.opengis.net%2Fgml%2F3.2%22%20xmlns%3Awfs%3D%22http%3A%2F%2Fwww.opengis.net%2Fwfs%22%20xmlns%3D%22http%3A%2F%2Fwww.opengis.net%2Ffes%2F2.0%22%20xmlns%3Afes%3D%22http%3A%2F%2Fwww.opengis.net%2Ffes%2F2.0%22%3E%3Cfes%3APropertyIsLike%20wildCard%3D%22*%22%20singleChar%3D%22.%22%20escapeChar%3D%22!%22%3E%3Cfes%3AValueReference%3ENAME%3C%2Ffes%3AValueReference%3E%3Cfes%3ALiteral%3E*United*%3C%2Ffes%3ALiteral%3E%3C%2Ffes%3APropertyIsLike%3E%3C%2Ffes%3AFilter%3E

An example of an OGC filter encoding standard 2.0 :

<fes:Filter xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:gml="http://www.opengis.net/gml/3.2" xmlns:wfs="http://www.opengis.net/wfs" xmlns="http://www.opengis.net/fes/2.0" xmlns:fes="http://www.opengis.net/fes/2.0"><fes:PropertyIsLike wildCard="*" singleChar="." escapeChar="!"><fes:ValueReference>NAME</fes:ValueReference><fes:Literal>*United*</fes:Literal></fes:PropertyIsLike></fes:Filter>

format_options

The format_options is a container for parameters that are format-specific. The syntax is:

format_options=param1:value1;param2:value2;...

The supported format options are:

  • antialias (values = on, off, text): controls the use of antialiased rendering in raster output.
  • callback: specifies the callback function name for the jsonp response format (default is parseResponse).
  • dpi: sets the rendering DPI (dots-per-inch) for raster outputs. The OGC standard output resolution is 90 DPI. If you need to create high resolution images (e.g for printing) it is advisable to request a larger image size and specify a higher DPI. In general, the image size should be increased by a factor equal to targetDPI/90, with the target dpi set in the format options. For example, to print a 100x100 image at 300 DPI request a 333x333 image with the DPI value set to 300: &width=333&height=333&format_options=dpi:300
  • layout: specifies a layout name to use. Layouts are used to add decorators such as compasses and legends. This capability is discussed further in the WMS Decorations section.
  • quantizer (values = octree, mediancut): controls the color quantizer used to produce PNG8 images. GeoServer 2.2.0 provides two quantizers, a fast RGB quantizer called octree that does not handle translucency and a slower but more accurate RGBA quantizer called mediancut. By default the first is used on opaque images, whilst the second is enabled if the client asks for a transparent image (transparent=true). This vendor parameter can be used to manually force the usage of a particular quantizer.
  • timeout: Apply a timeout value for a getMap request. If the timeout is reached, the getMap request is cancelled and an error is returned. The value used for the timeout will be the minimum of this format option and the global WMS timeout defined in the WMS configuration. A value of zero means no timeout.
  • kmattr (values = true, false): determines whether the KML returned by GeoServer should include clickable attributes or not. This parameter primarily affects Google Earth rendering.
  • legend (values = true, false): KML may add the legend.
  • kmscore (values = between 0 to force raster output and 100 to force vector output): parameter sets whether GeoServer should render KML data as vector or raster. This parameter primarily affects Google Earth rendering.
  • kmltitle: parameter sets the KML title.
  • kmlrefresh (values = greater than 0 or expires): Force Network Link reload in refresh mode on interval of seconds. When expires is specified client will refresh whenever the time has elapsed specified in cache expiration headers. The caching time may be set in the Layer configuration under Publishing tab setting HTTP Cache Time. This parameter primarily affects Google Earth rendering and is dependent on being respected by the client. Using a second interval is a more reliable choice.
  • kmlvisible (values = true, false): Indicates whether layers selected will default to enabled or not. Default behavior is enabled. This parameter primarily affects Google Earth rendering.
  • advancedProjectionHandling (values = true, false): Enable Disable advanced projection handling, if it is enabled in the GUI. If it is disabled in the GUI, this option has no effect.
  • mapWrapping (values = true, false): Enable Disable continuous map wrapping, if it is enabled in the GUI. If it is disabled in the GUI, this option has no effect. Continuous map wrapping will also be disabled if advancedProjectionHandling is disabled.
  • decorationsOnly (values = true, false): Disabled by default. When value is true, it allows to get a transparent sized image for the request on which maps are not rendered, but it keeps the decorations applied (if present).

maxFeatures and startIndex

The parameters maxFeatures and startIndex can be used together to provide "paging" support. Paging is helpful in situations such as KML crawling, where it is desirable to be able to retrieve the map in sections when there are a large number of features.

The startindex=n parameter specifies the index from which to start rendering in an ordered list of features. n must be a positive integer.

The maxfeatures=n parameter sets a limit on the amount of features rendered. n must be a positive integer. When used with startindex, the features rendered will be the ones starting at the startindex value.

Note that not all layers support paging. For a layer to be queried in this way, the underlying feature source must support paging. This is usually the case for databases (such as PostGIS).

palette

It is sometimes advisable (for speed and bandwidth reasons) to downsample the bit depth of returned maps. The way to do this is to create an image with a limited color palette, and save it in the palettes directory inside your GeoServer Data Directory. It is then possible to specify the palette parameter of the form:

palette=<image>

where <image> is the filename of the palette image (without the extension). To force a web-safe palette, use the syntax palette=safe. For more information see the tutorial on Paletted Images

propertyName

The propertyName parameter specifies which properties are included in the response of the GetFeatureInfo operation. The syntax is the same as in the WFS GetFeature operation. For a request for a single layer the syntax is:

propertyName=name1,...,nameN

For multiple layers the syntax is:

propertyName=(nameLayer11,...,nameLayer1N)...(name1LayerN,...,nameNLayerN)

The nature of the properties depends on the layer type:

  • For vector layers the names specify the feature attributes.
  • For raster layers the names specify the bands.
  • For cascaded WMS layers the names specify the GML properties to be returned by the remote server.

tiled

Meta-tiling prevents issues with duplicated labels when using a tiled client such as OpenLayers. When meta-tiling is used, images are rendered and then split into smaller tiles (by default in a 3x3 pattern) before being served. In order for meta-tiling to work, the tile size must be set to 256x256 pixels, and the tiled and tilesorigin parameters must be specified.

The tiled parameter controls whether meta-tiling is used. The syntax is:

tiled=[true|false]

To invoke meta-tiling use tiled=true.

tilesorigin

The tilesorigin parameter is also required for meta-tiling. The syntax is:

tilesorigin=x,y

where x and y are the coordinates of the lower left corner (the "origin") of the tile grid system.

OpenLayers example

In OpenLayers, a good way to specify the tilesorigin is to reference the map extents directly.

Warning

If the map extents are modified dynamically, the tilesorigin of each meta-tiled layer must be updated accordingly.

The following code shows how to specify the meta-tiling parameters:

var options = {
    ...
    maxExtent: new OpenLayers.Bounds(-180, -90, 180, 90),
    ...
};
map = new OpenLayers.Map('map', options);

tiled = new OpenLayers.Layer.WMS(
    "Layer name", "http://localhost:8080/geoserver/wms",
    {
        srs: 'EPSG:4326',
        width: 391,
        styles: '',
        height: 550,
        layers: 'layerName',
        format: 'image/png',
        tiled: true,
        tilesorigin: map.maxExtent.left + ',' + map.maxExtent.bottom
    },
    {buffer: 0} 
);

scaleMethod

The scaleMethod parameter controls how the scale denominator is computed by GeoServer The two possible values are:

  • OGC (default): the scale denominator is computed according to the OGC SLD specification, which

    imposes simplified formulas for the sake of interoperability

  • Accurate: use the full expressions for computing the scale denominator against geographic

    data, taking into account the ellipsoidal shape of Earth

The two methods tend to return values rather close to each other near the equator, but they do diverge to larger differences as the latitude approaches the poles.

interpolations

The interpolations parameter allows choosing a specific resampling (interpolation) method. It can be used in the GetMap operation.

If more than one layer is specified in the layers parameter, then a separate interpolation method can be specified for each layer, separated by commas. The syntax is:

interpolations=method1,method2,...

method values can be one of the following:

  • nearest neighbor
  • bilinear
  • bicubic

or empty if the default method has to be used for the related layer.

The parameter allows to override the global WMS Raster Rendering Options setting (see WMS Settings for more info), as well as the layer specific Default Interpolation Method publishing parameter (see Layers for more info), on a layer by layer basis.

clip

The clip parameter can be used to clip WMS response using a Polygon mask represented by a valid WKT String.

Here are two examples, the first one using WKT, the second using EWKT:

clip=POLYGON((-14.50804652396198 55.579454354599356,34.53492222603802 55.579454354599356,34.53492222603802 32.400173313532584,-14.50804652396198 32.400173313532584,-14.50804652396198 55.579454354599356))
clip=srid=900913;POLYGON ((-1615028.3514525702 7475148.401208023, 3844409.956787858 7475148.401208023, 3844409.956787858 3815954.983140064, -1615028.3514525702 3815954.983140064, -1615028.3514525702 7475148.401208023))

Note

The Axis order of WKT must be East/North regardless of WMS version. Currently this parameter is ignored for layers with Complex features.