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:

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:

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:

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):

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.