KML Advanced Features: Network Links & Overlays

KML (Keyhole Markup Language) is often associated with simple placemarks and polygons, but the OGC KML 2.3 specification includes a rich set of advanced features that enable dynamic data loading, image overlays, time-based animations, virtual tours, and custom styling. These capabilities make KML far more powerful than a static marker format. This guide covers the most useful advanced KML elements — NetworkLink, GroundOverlay, ScreenOverlay, TimeSpan, Tours, camera controls, and BalloonStyle — with practical XML examples you can adapt for your own projects.

NetworkLink

A NetworkLink loads KML content from a remote URL, enabling dynamic, server-driven maps. Instead of embedding all data in a single file, you can point to an endpoint that returns fresh KML on each request. This is essential for live tracking, real-time sensor feeds, and datasets that change frequently.

<NetworkLink>
  <name>Live Earthquake Feed</name>
  <Link>
    <href>https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_day.kml</href>
    <refreshMode>onInterval</refreshMode>
    <refreshInterval>300</refreshInterval>
  </Link>
</NetworkLink>

Key properties of NetworkLink:

• refreshMode — onInterval reloads at a fixed interval (in seconds). onExpire reloads when the server-specified expiry time is reached. onChange reloads when the link parameters change.
• viewRefreshMode — onStop reloads when the user stops panning, sending the current bounding box as query parameters. This enables view-dependent data loading, similar to WFS bounding-box queries.
• flyToView — When set to 1, the camera flies to the view defined in the loaded KML.

NetworkLinks can be nested, creating hierarchical data structures where a top-level KML links to region-specific files that load on demand.

GroundOverlay

A GroundOverlay drapes a raster image (PNG, JPEG) onto the terrain surface. Use it to display historical maps, satellite imagery, custom raster layers, or analysis outputs on top of Google Earth's 3D terrain.

<GroundOverlay>
  <name>Historical Map 1890</name>
  <Icon>
    <href>https://example.com/maps/city-1890.png</href>
  </Icon>
  <LatLonBox>
    <north>40.78</north>
    <south>40.70</south>
    <east>-73.94</east>
    <west>-74.02</west>
    <rotation>-2.5</rotation>
  </LatLonBox>
  <color>aaffffff</color>
</GroundOverlay>

The LatLonBox defines the geographic extent where the image is placed. The optional rotation element rotates the image around its center, useful for aligning scanned maps that are not axis-aligned. The color element controls opacity — aa in the alpha channel (hex) sets approximately 67% opacity, making the overlay semi-transparent over the base terrain.

ScreenOverlay

A ScreenOverlay places an image at a fixed position on the screen, regardless of the camera view. Common uses include logos, legends, compass roses, and watermarks.

<ScreenOverlay>
  <name>Company Logo</name>
  <Icon>
    <href>https://example.com/logo.png</href>
  </Icon>
  <overlayXY x="0" y="1" xunits="fraction" yunits="fraction"/>
  <screenXY x="0.02" y="0.98" xunits="fraction" yunits="fraction"/>
  <size x="150" y="50" xunits="pixels" yunits="pixels"/>
</ScreenOverlay>

The overlayXY defines the anchor point on the image; screenXY defines where on the screen that anchor is placed. Fractional units (0 to 1) make the positioning responsive to different screen sizes.

TimeSpan and TimeStamp

KML supports temporal data through two elements: TimeSpan (a date range) and TimeStamp (a single moment). When features have time information, Google Earth displays a time slider that lets users scrub through history — perfect for showing change over time.

<Placemark>
  <name>Construction Zone</name>
  <TimeSpan>
    <begin>2025-03-01</begin>
    <end>2025-09-30</end>
  </TimeSpan>
  <Point>
    <coordinates>-73.98,40.75,0</coordinates>
  </Point>
</Placemark>

<Placemark>
  <name>Sensor Reading</name>
  <TimeStamp>
    <when>2025-06-15T14:30:00Z</when>
  </TimeStamp>
  <Point>
    <coordinates>-118.24,34.05,0</coordinates>
  </Point>
</Placemark>

Use cases include tracking vehicle routes over time, visualizing urban expansion across decades, animating weather patterns, and showing the temporal extent of field survey data.

Tours

KML Tours automate camera movements to create guided flyovers and presentations. A Tour consists of a playlist of FlyTo, Wait, and AnimatedUpdate elements.

<gx:Tour>
  <name>City Flyover</name>
  <gx:Playlist>
    <gx:FlyTo>
      <gx:duration>5</gx:duration>
      <gx:flyToMode>smooth</gx:flyToMode>
      <LookAt>
        <longitude>-73.985</longitude>
        <latitude>40.748</latitude>
        <altitude>0</altitude>
        <range>5000</range>
        <tilt>60</tilt>
        <heading>45</heading>
      </LookAt>
    </gx:FlyTo>
    <gx:Wait>
      <gx:duration>3</gx:duration>
    </gx:Wait>
    <gx:FlyTo>
      <gx:duration>5</gx:duration>
      <LookAt>
        <longitude>-73.968</longitude>
        <latitude>40.785</latitude>
        <altitude>0</altitude>
        <range>3000</range>
        <tilt>70</tilt>
        <heading>0</heading>
      </LookAt>
    </gx:FlyTo>
  </gx:Playlist>
</gx:Tour>

Tours are widely used for real estate presentations, tourism marketing, environmental impact demonstrations, and educational content. The gx: prefix indicates Google extension elements that are supported in Google Earth but are not part of the OGC standard.

LookAt and Camera

KML provides two ways to define a viewpoint. LookAt defines a point the camera looks at, with range, tilt, and heading parameters. Camera defines the exact position and orientation of the camera itself, offering more precise control for oblique and aerial views.

Element	Defines	Best For
LookAt	Target point + distance	Orbiting around a landmark
Camera	Camera position + orientation	Precise aerial viewpoints

Use LookAt when you want the user to orbit around a point of interest. Use Camera when you need exact positioning, such as matching a photograph's viewpoint or creating a virtual drone flight path.

BalloonStyle

BalloonStyle controls the pop-up balloon that appears when a user clicks a placemark. You can embed HTML, substitute data fields, and apply CSS-like styling to create rich, branded information panels.

<Style id="customBalloon">
  <BalloonStyle>
    <text><![CDATA[
      <h3>$[name]</h3>
      <p>Population: $[population]</p>
      <p>Elevation: $[elevation] m</p>
      <img src="$[imageUrl]" width="200"/>
    ]]></text>
    <bgColor>ffffffee</bgColor>
  </BalloonStyle>
</Style>

The $[fieldName] syntax substitutes values from the placemark's ExtendedData. This lets you create template-driven balloons that automatically populate with feature-specific information. Wrap the HTML in a CDATA section to avoid XML escaping issues.

Practical Use Cases

These advanced KML features combine to enable powerful applications:

• Real-time asset tracking — Use NetworkLink with interval refresh to display live GPS positions of vehicles, vessels, or aircraft.
• Historical map comparison — Stack GroundOverlays of maps from different eras with opacity sliders and TimeSpan elements.
• Environmental monitoring — Combine TimeStamp placemarks with BalloonStyle to show sensor readings over time with rich pop-ups.
• Tourism and real estate — Create Tours that fly viewers through properties or scenic routes with narrated waypoints.
• Emergency management — Use NetworkLink with viewRefreshMode to load evacuation zones, shelter locations, and hazard boundaries dynamically as responders pan the map.

To convert KML data to GeoJSON for use in web applications, or to inspect complex KML files feature by feature, use the KML-to-GeoJSON converter in GeoDataTools. For a side-by-side comparison of what each format supports, see the GeoJSON vs KML comparison.

FAQ

Do all KML viewers support NetworkLink and Tours?

Google Earth Pro and Google Earth for Web support the full KML specification including NetworkLink, Tours, and the gx: extensions. Other viewers — such as Google Maps, QGIS, and ArcGIS — support a subset. NetworkLink is widely supported; Tours and gx: extensions are primarily Google Earth features. Always test your KML in the target viewer.

Can I use NetworkLink to load data from my own API?

Yes. Point the NetworkLink href to any URL that returns valid KML. Your server can generate KML dynamically from a database, apply filters based on query parameters, and return only the features relevant to the current view when using viewRefreshMode. Ensure your server sets appropriate CORS headers if the KML is loaded from a different domain.

How do I make a GroundOverlay transparent?

Set the color element on the GroundOverlay to a value with a reduced alpha channel. KML uses AABBGGRR hex format (not RRGGBBAA). For 50% transparent white, use 80ffffff. The alpha value 80 (hex) equals 128/255, or approximately 50% opacity. Use 00ffffff for fully transparent and ffffffff for fully opaque.