KML is an XML-based file format used to represent geographic features in applications such as ArcGIS Earth and Google Earth. KML allows you to draw points, lines, and polygons on maps and globes and share them with others. Using KML, you can also designate text, pictures, movies, or links to other GIS services that appear when the user clicks the feature. Many KML client applications, including Map Viewer and Map Viewer Classic, are free and provide a familiar, user-friendly browsing experience.

Share your KML

You can add an uncompressed .kml or a compressed .kmz file as an item. You can also add the KML as an item by referencing the URL of a .kml or .kmz on the web.

Once you add the KML as an item, you can share it. When others discover the KML item, they can open it in Map Viewer or Map Viewer Classic or download the file to their computer.

Add KML layer to a map

If you know a specific KML document on the web that you want to display on a map, you can add it as a layer on the web in Map Viewer or in Map Viewer Classic.

Considerations for using KML in a map

KML was originally created to view features in three-dimensional Earth browsers such as ArcGIS Earth. KML is now supported in a number of two-dimensional web browser clients, including Map Viewer and Map Viewer Classic. There are some aspects of KML that do not work well on 2D screens and some limitations to what web browser clients can support.

Supported functionality

Map Viewer and Map Viewer Classic support a subset of KML elements and functionality. The following list will expand as Esri continues to develop support for KML:

  • Placemarks
  • Network links to import data dynamically
  • Ground overlays
  • Folders
  • Polylines and polygons
  • Styles of polylines and polygons, including color, fill, and opacity
  • Print KML layer
  • Icons
  • Descriptive HTML
  • KMZ (compressed KML, including attached images)
  • Embed KML layer in website
  • ExtendedData in pop-up descriptions
  • Network links with refresh parameters
  • KML icons with hotSpot nodes


The current limitations of using KML layers in Map Viewer and Map Viewer Classic are as follows:

  • The following elements do not display in a map: regionated KML, view-based and time-based refresh parameters, regions inside network links, and screen overlays.
  • Ground overlays and network links without refresh properties do not print.
  • Image overlays that cover large areas may appear distorted.
  • By default, there is a 30-minute cache delay in displaying updates to the KML layer. If the layer contains refresh parameters of less than 30 minutes, the refresh interval is honored. The minimum refresh value is 30 seconds.
  • KML layers cannot be used as a basemap.
  • You can set the visible range for KML layers in Map Viewer, but you cannot set the visible range for KML layers in Map Viewer Classic.
  • KML layers cannot be reordered in the map contents.
  • Internal KML layers are not supported.
  • Configuring pop-ups is not supported in KML layers. Any feature data in the layer is automatically displayed in pop-ups; you cannot configure or disable them.
  • Inline styles are not supported when displaying pop-ups in KML layers.
  • KML layers larger than 10 MB cannot be added to maps.