Skip To Content ArcGIS for Developers Sign In Dashboard

Edit KML content

KML, short for Keyhole Markup Language, is a standard that defines an XML-based format for representing geographic features and map visualizations. You can create and edit KML content in your ArcGIS Runtime app. ArcGIS Runtime saves KML version 2.2 to a compressed KML format known as KMZ.

A KML dataset is a container for a hierarchical collection of KML nodes. Some common types of KML nodes include the following:

  • Document—A container for KML features (placemarks, overlays, folders, and so on).
  • Folder—A container that defines a hierarchy for nodes in the tree.
  • Ground overlay—Specifies a local or hosted image file to draw on the surface.
  • Model—Represents an object in 3D coordinate space using a COLLADA file.
  • Network link— Specifies the location of a KML or KMZ resource on a local or remote network.
  • Placemark—Similar to an ArcGIS feature, it represents a geographic location with point, line, or polygon geometry.
  • Screen overlay—Specifies a local or hosted image file to draw on the screen (such as a company logo).
  • Tour—Defines a fly-through experience composed of an ordered list of elements to visit.
  • Track/Multitrack—Describes the geographic position of an object over time.

ArcGIS Runtime SDK supports the creation and editing of documents, folders, placemarks, ground overlays, and network links. You can also edit the properties of KML nodes, including the name, description, snippet, geometries, and style. KML content you create or edit can be saved to a .kmz file.

Some advanced content types or behaviors are currently not supported for editing via ArcGIS Runtime, such as the following:

  • Shared style elements
  • Highlight style
  • Screen overlays

Note:

KML geometry always uses the WGS84 coordinate system.

Create KML content and save it to a KMZ file

You can save any KML node to an output file by calling SaveToFileURL. Doing so writes the KML representation of the node and all of its child nodes to a compressed KML format (.kmz). Only files referenced by absolute URLs are supported for use as icons and links. It's common to save a KML document node since it serves as a top-level container for several related child nodes. The output KMZ archive is shared easily as a single file and can be read into any app that supports KML, such as ArcGIS Earth or an ArcGIS Runtime SDK app. See Display KML content for details.

The following steps describe how to create a KML dataset, add nodes, and save it locally to a new KMZ file.

  1. Create a KML document and use it to create a KML dataset. The document is a top-level container for additional KML nodes.

    // Create a new KML document and set its name property.
    let kmlDocument = AGSKMLDocument()
    kmlDocument.name = "UFO sightings"
    
    // Create a new KML dataset using the KML document.
    let kmlDataset = AGSKMLDataset(rootNode: kmlDocument)

  2. Create a style to represent a placemark. The style defines an icon style that is created with an icon (built with a URL to a local or online image).

    // Create a new icon using a URL to an online image.
    let placemarkIcon = AGSKMLIcon(url: URL(string: "http://static.arcgis.com/images/Symbols/SafetyHealth/esriCrimeMarker_56_Gradient.png")!)
            
    // Create an icon style using the icon, adjust the size using the scale argument.
    let iconStyle = AGSKMLIconStyle(icon: placemarkIcon, scale: 3)
            
    // Create a KML style that uses the icon style.
    let placemarkStyle = AGSKMLStyle()
    placemarkStyle.iconStyle = iconStyle

  3. Create a placemark node with point geometry and set its style to use the icon. Provide a value for the ID, Name, and Description to give more information about the placemark.

    // Create a KML placemark, give it a name and description.
    let mapPoint = AGSPoint(x: -105.243, y: 33.968, z: 0.0, spatialReference: .wgs84())
    
    guard let kmlGeometry = AGSKMLGeometry(geometry: mapPoint, altitudeMode: .clampToGround) else { return }
            
    let kmlPlacemark = AGSKMLPlacemark(geometry: kmlGeometry)
    kmlPlacemark.nodeID = "43a"
    kmlPlacemark.name = "Roswell crash site"
    kmlPlacemark.nodeDescription = "Debris discovered at a ranch in Roswell New Mexico in 1947 is widely believed to be from an alien spacecraft."
    // Apply the icon style to the placemark.
    kmlPlacemark.style = placemarkStyle
            
    // Add the placemark to the KML node collection.
    kmlDocument.addChildNode(kmlPlacemark)

  4. Save the KML document as a .kmz file. You can save any KML node to write its contents (its child nodes, in other words) to a file on disk.

    let documentDirectoryURL = FileManager.default.urls(for: .documentDirectory, in: .userDomainMask).first!
    let fileURL = documentDirectoryURL.appendingPathComponent("myKMZDocument.kmz")
    
    self.kmlDocument.save(toFileURL: fileURL) {[weak self] (error) inn
     if let error = error {
      print(error)
     } else {
      print("The kmz file has been saved")
     }
    )}

  5. Optionally, display the new KML file as a KML layer in your map or scene.

    // Create a new KML layer from the output KMZ file.
    let kmlLayer = AGSKMLLayer(kmlDataset: kmlDataset)
            
    // Add the KML layer to the scene (or map).
    self.sceneView.scene?.operationalLayers.add(kmlLayer)
            
    // Zoom to the extent of the new layer.
    guard let layerExtent = kmlLayer.fullExtent else {return}
    self.sceneView.setViewpoint(AGSViewpoint(targetExtent: layerExtent)

A KML placemark that displays a name and description

Create a KML ground overlay

A ground overlay is a KML element that displays an area on the surface. Like a placemark node, a ground overlay is created with geometry and a symbol. It has name, description, and snippet properties that can be used to display additional information. Geometry for a ground overlay must be of type polygon or envelope. The data the overlay represents comes from an image reference in a KML icon.

The following steps illustrate creating a simple ground overlay and adding it to a KML document's node collection:

  1. Create an icon to display with the ground overlay. The icon is defined using a URL to an online or local image.

    // Create an icon from a image URL to display the ground overlay.
    let icon = AGSKMLIcon(url: URL(string: "http://static.arcgis.com/images/Symbols/Basic/CrossHair.png")!)

  2. Create geometry to use for the ground overlay. The ground overlay geometry must be a polygon or an envelope.

    // Use a polygon builder to create a rectangle polygon (in WGS 84 coordinates).
    let overlayPolyBldr = AGSPolygonBuilder(spatialReference: .wgs84())  
    overlayPolyBldr.addPointWith(x: -115.858, y: 37.204)        
    overlayPolyBldr.addPointWith(x: -115.858, y: 37.326)
    overlayPolyBldr.addPointWith(x: -115.757, y: 37.326)
    overlayPolyBldr.addPointWith(x: -115.757, y: 37.204)
    let overlayPoly = overlayPolyBldr.toGeometry())

  3. Create a KML ground overlay with the geometry and icon to use. Add the new overlay to the KML document's child node collection.

    // Create a new groundOverlay with the polygon and icon.
    let groundOverlay = AGSKMLGroundOverlay(geometry: overlayPoly, icon: icon)
            
    // Provide a name and description.
    groundOverlay.name = "Area 51";
    groundOverlay.nodeDescription = "A highly classified US Air Force facility in the Nevada Test and Training Range."
            
    // Add the ground overlay to the document's child nodes.
    kmlDocument.addChildNode(groundOverlay))

A KML ground overlay