KML services

ArcGIS applications are now interoperable with clients that read and write Keyhole Markup Language (KML). KML is the Google Earth XML specification that describes geographic features and rasters in three dimensions. The ArcGIS Desktop applications ArcGIS Explorer and ArcGlobe read KML, and ArcGIS Desktop geoprocessing tools and ArcGIS Server GIS Services can output vector features and raster data in KML. This document details the following aspects of working with KML:

• Creating a KML service
• Consuming KML in ArcGIS Desktop applications

For a tutorial of the process of creating a KML service, see Tutorial: Publishing a KML service.

Creating a KML service

Publishing your map document as KML requires two steps:

1. Use ArcMap to add feature classes and layer files to a map document.
2. Publish the map document as a map service with the KML capability enabled.

When you publish the service, an HTTP endpoint is created, which you can use to access the service from clients that support KML or KMZ.

Using ArcGIS Desktop to prepare the map

The first step to creating a KML service is to create a map document that contains the features you want to convert to KML. This involves adding feature classes and layer files to ArcMap as data, symbolizing the map appropriately, and saving the map document.

If you want to publish feature classes with 3D attributes such as z-offsets or extrusion based on attributes, you must first edit the feature class layer properties in ArcGlobe, save them as a layer file, then add the layer file to an ArcMap document. For example, if you have a polygon feature class with a population density field, you can set the extrusion properties for that class in ArcGlobe, save the feature class as a layer file, then add the layer file to an ArcMap document. Follow the steps below to configure elevation and extrusion in your map:

1. Open ArcGlobe
2. Add the feature class that will be elevated or extruded.
3. Right-click the layer and click Properties...
4. In the Properties dialog, use the Elevation and Globe Extrusion tabs to adjust the elevation and extrusion settings. When finished, click OK to close the Properties dialog.
5. Right-click the name of the layer in the Table of Contents and click Save As Layer File... Select a name and location for the layer file and click Save.
6. Close ArcGlobe.
7. Open ArcMap to the map document you will be using for your KML service.
8. Click the Add Data button.
9. Navigate to the layer file you created in ArcGlobe and add it to the map. You won't see any of the elevation or extrusion effects in ArcMap, but they will be visible when you publish the map as a KML service.

Publishing the KML service

Once you've created your map document, you must then publish it as a map service with the KML capability enabled. To do this, follow the steps in Publishing a GIS resource to the server, keeping in mind the following:

• To specify the Resource, browse to the map document which you want to publish as KML
• When specifying capabilities, check the KML box.

When you create the service, an HTTP endpoint is created which client applications such as ArcGIS Explorer can use to access the service. The following section describes how to connect to the service.

Configuring additional properties

After publishing your KML service, you may want to edit its default properties to achieve a desired look and feel. These properties include Operations, Feature Limit, ImageSize, ScreenSize, DPI, PaletteSize, IconSize, NetworkLinkControl, RefreshPeriod, LinkDescription, LinkName, OneTimeMessage:

• Operations define different access modes end users have to the KML service. SingleImage mode only allows clients to request composite images as ground overlays (requests for “Composite=False” or “VectorsToRasters=true” in the URL query string will be ignored). No vectors can be returned. Separate Images mode only allows clients to request a collection of images as ground overlays (one for each layer in the source document). Requests for “Composite=True” or “Composite=False” will be ignored in the URL query string. Vectors mode allows end users to request vector and raster data (requests for “Composite=True” or “VectorsToRasters=True” in the URL query string will be ignored).
• FeatureLimit controls the number of features returned by the GIS Service.
• ImageSize controls the size of any images referenced in the returned KML.
• ScreenSize and DPI define the screen resolution on the KML client and are used to calculate the scale for scale-dependent layers in the mxd document.
• PaletteSize and IconSize determine the resolution of the symbols referenced in the KML.
• NetworkLinkControl allows server side control of client data requests. Minimum Refresh Period is the time interval during which requests to refresh the data from the same client will be ignored. Link Description is the text that will appear when a user clicks the Network Link in a KML client. Link Name is the text that will override whatever the client specifies for the Network Link name. One Time Message is the text that will appear in a pop-up balloon the first time a client accesses the service.

Consuming KML in ArcGIS Desktop applications

Any client that can read KMZ can consume your KML service. The URL format that clients should use to access the service is:
http://<server name>:8399/<instance name>/services/<folder name (if applicable)>/<service name>/mapserver/kmlserver

For example, if you had a KML service named Paris in a folder named France running on a server named Server1 with the default instance name of "arcgis", its URL would look like this:
http://Server1:8399/arcgis/services/France/Paris/mapserver/kmlserver

Viewing a KML service in ArcGIS Explorer

You can add KML data to ArcGIS Explorer maps. This process is currently explained in the ArcGIS Explorer Help.

Viewing a KML service in ArcGlobe

To view a KML service in ArcGlobe, you'll use the KML toolbar. To enable the KML toolbar, navigate to the Main Menu>View>ToolBars>Kml Toolbar. The Add KML Data button allows you to browse to and add a .kmz file to your globe document. The Add KML Network Link button allows you to enter a URL to a KML service (see below “Consuming KML in Google Earth” for a description of the URL to an ArcGIS Server KML service). For additional help, see the topic Displaying KML data in ArcGlobe in the ArcGIS Desktop Help.

Consuming KML in Google Earth

ArcGIS Server KML Services are designed to work with the Google Earth KML 2.0 specification. Any Google Earth client greater than version 3.0 is supported.

Viewing a KML file

You can add KML data created by ArcGIS desktop GP tools as you would any other KML file in Google Earth. This process is currently explained in the Google Earth Help.

Viewing a KML service

It is easy to add an ArcGIS Server KML Service to Google Earth by consuming a Network Link Document created using ArcGIS manager or by using the “Add Network Link” menu option. The base URL format that clients should use to access the service is: http://<server name>/<Manager instance name>/services/<folder name (if applicable)>/<service name>/mapserver/kmlserver. This base URL can be configured to return data from the server as specified by the following query string parameters (a query string is the part of the URL following a “?” after the base URL):

• Composite

  Default = true. Options are “true” (return a single image compositing all data in the source map document) or “false” (return KML representing the rasters and vectors in the source map document).

• VectorsToRasters

  Default = false. Options are “true” (convert vector layers to individual rasters and return all the layers as separate images to the client – “Composite” must also be set to “false”) or “false” (return vectors as vectors).

• LayerIDs

  Default = all layers. Option is to specify specific layers with a comma delimited list beginning with zero. Each group layer is included in the numbering scheme. Only the layers specified will be returned. If a group layer is specified and none of its children all of the children will be selected and returned. If a child node of a group layer is specified, but not its parent group layer, the parent group layer will also be returned.

• FeatureLimit

  Default = 1,000,000. Option is to specify a limit on the number of features to return. It is important to note that this refers to KML primitive geometries, not ESRI features and might have undesired effects if, for example, a large polygon with many vertices is requested. If the limit is reached before all the vertices are retrieved, only part of the polygon would be retrieved.

• ImageSize

  Default = 1024 pixels. Option is to specify the size of the image returned by the KML Service.

• ScreenSize

  Default = 1024 pixels. Option is to specify the size of the client screen to aid in the proper determination of the map scale for a request.

• DPI

  Default = 96. Option is to specify the DPI of the client screen to aid in the proper determination of the map scale for a request.

• PaletteSize

  Default = 256 pixels. Option is to specify the size of the palette of icons returned with requests for vector data.

• IconSize

  Default = 32 pixels. Option is to specify the size of icons in the icon palette returned with requests for vector data.

A completed ArcGIS Server KMLService URL that returns a single image of map layers 0,4 and 32, might look like the following (note that it is not case-sensitive):

http://myServer/ArcGIS/services/France/Paris/MapServer/KmlServer?Composite=True&LayerIDs=0,4,32

Note: If the KMLService is using a cached MapService the cached tiles will only be used if the URL to service is specified exactly as follows: http://<server name>/<Manager instance name>/Services/<folder name (if applicable)>/<service name>/MapServer/KmlServer?Composite=true

Creating a static KML document using ArcGIS geoprocessing tools

ArcGIS provides two geoprocessing (GP) tools, LayerToKML and MapToKML, that export ArcGIS data as KML. These tools can be accessed from the 3DAnalyst > Conversion > To KML toolbox from any ArcGIS Desktop application or the command line.

Layer to KML

LayerToKML converts an ArcGIS Layer file to compressed KML (KMZ). To use this tool you will need to specify an input Layer file (a file with a .lyr extension) and a location and name for the compressed KML (KMZ) output file. You should also choose the scale, ImageSize and DPI for the output document. Additionally, the scale and extent to export must also be supplied. The extent to export defaults to the extent of the layer in the layer file, but can also be specified manually or chosen from the extent of a specified layer file. You may also choose to return a KMZ document filled with KML Placemarks for each feature in the layer document or to only return a single image, a composite of all the features in the layer, in the KMZ document.

Map to KML

MapToKML exports an ArcMap MXD file to KMZ. To use this tool you will need to specify an input Map document (a file with an .mxd extension) and a location and name for the compressed KML (KMZ) output file. You should also choose the scale, ImageSize and DPI for the output document. Additionally, the scale and extent to export must also be supplied. The extent to export defaults to the extent of the map frame of the MXD document, but can also be specified manually or chosen from the extent of a specified layer file. You may also choose to return a KMZ document filled with KML Placemarks for each feature in the MXD document, to return a KMZ document with separate rasters for each layer in the MXD document or to only return a single image, a composite of all the features in all the layers, in the KMZ document.