Skip to content

KML Reflector

Standard WMS requests can be quite long and cumbersome. The following is an example of a request for KML output from GeoServer:

http://localhost:8080/geoserver/ows?service=WMS&request=GetMap&version=1.1.1&format=application/vnd.google-earth.kml+XML&width=1024&height=1024&srs=EPSG:4326&layers=topp:states&styles=population&bbox=-180,-90,180,90

GeoServer includes an alternate way of requesting KML, and that is to use the KML reflector. The KML reflector is a simpler URL-encoded request that uses sensible defaults for many of the parameters in a standard WMS request. Using the KML reflector one can shorten the above request to:

http://localhost:8080/geoserver/wms/kml?layers=topp:states

Using the KML reflector

The only mandatory parameter is the layers parameter. The syntax is as follows:

http://GEOSERVER_URL/wms/kml?layers=<layer>

where GEOSERVER_URL is the URL of your GeoServer instance, and <layer> is the name of the featuretype to be served.

The following table lists the default assumptions:
Key Value
request GetMap
service wms
version 1.1.1
srs EPSG:4326
format application/vnd.google-earth.kml+xml
width 2048
height 2048
bbox <layer bounds>
kmattr true
kmplacemark false
kmscore 40
styles [default style for the featuretype]

Any of these defaults can be changed when specifying the request. For instance, to specify a particular style, one can append styles=population to the request:

http://localhost:8080/geoserver/wms/kml?layers=topp:states&styles=population

To specify a different bounding box, append the parameter to the request:

http://localhost:8080/geoserver/wms/kml?layers=topp:states&bbox=-124.73,24.96,-66.97,49.37

Reflector modes

The KML reflector can operate in one of three modes: refresh, superoverlay, and download.

The mode is set by appending the following parameter to the URL:

mode=<mode>

where <mode> is one of the three reflector modes. The details for each mode are as follows:
Mode Description
refresh (default for all versions except 1.7.1 through 1.7.5) Returns dynamic KML that can be refreshed/updated by the Google Earth client. Data is refreshed and new data/imagery is downloaded when zooming/panning stops. This mode can return either vector or raster (placemark or overlay) The decision to return either vector or raster data is determined by the value of kmscore. Please see the section on KML Scoring for more information.
superoverlay (default for versions 1.7.1 through 1.7.5) Returns KML as a super-overlay. A super-overlay is a form of KML in which data is broken up into regions. Please see the section on KML Super-Overlays for more information.
download Returns KML which contains the entire data set. In the case of a vector layer, this will include a series of KML placemarks. With raster layers, this will include a single KML ground overlay. This is the only mode that doesn't dynamically request new data from the server, and thus is self-contained KML.

More about the "superoverlay" mode

When requesting KML using the superoverlay mode, there are four additional submodes available regarding how and when data is requested. These options are set by appending the following parameter to the KML reflector request:

superoverlay_mode=<submode>

where <submode> is one of the following options:
Submode Description
auto (default) Always returns vector features if the original data is in vector form, and returns raster imagery if the original data is in raster form. This can sometimes be less than optimal if the geometry of the features are very complicated, which can slow down Google Earth.
raster Always returns raster imagery, regardless of the original data. This is almost always faster, but all vector information is lost in this view.
overview Displays either vector or raster data depending on the view. At higher zoom levels, raster imagery will be displayed, and at lower zoom levels, vector features will be displayed. The determination for when to switch between vector and raster is made by the regionation parameters set on the server. See the section on KML Regionation for more information.
hybrid Displays both raster and vector data at all times.