My favorites | English | Sign in

Google Earth API

Time

  1. Introduction
  2. Sun
  3. Features and views
  4. Examples

Introduction

The Google Earth Plugin accepts time data in two ways:

  • from the computer's clock, to display sunlight and shadows when Sun is enabled
  • from time-aware KML, to display time-stamped features and views. More information on time as it relates to features and views can be found in the Time and Animation chapter of the KML Developer's Guide.

Once time has been introduced into a plugin instance through either of the above methods, a time slider is displayed. This slider can be manipulated by the end user to control the point in time, or range of times, being displayed.

There are no time-related functions in the Earth API. Time information (other than enabling the Sun display mode) must be imported from a KML file.

Sun

When sunlight is activated in the plugin, the user's computer clock time is used to display the Sun's correct position and shadows on the terrain. A time slider is added to the plugin window, allowing the user to change the time being displayed.

ge.getSun().setVisibility(true);

The position of the sun can also be controlled by time-tagged KML, as described below.

Features and views

There are two concepts of time that are important with regards to the plugin: a feature's time, and a view's time. Basically:

  • a feature's time defines the times at which that feature should be viewable on the globe
  • a view's time defines the point in time from which the viewer is looking at the globe

Time information is specified with KML; the Earth API does not provide a method of passing time information. The examples in this document display the KML markup only; for information on importing KML into the plugin, refer to the KML chapter of the Developer's Guide. More information about KML is available from the KML documentation.

Features

Time information can be attached to a feature, to define the time or times at which that feature should be viewable on the globe.

For example, a placemark named PM2009+ can be created, containing time information as follows: 

   <Placemark>
     <name>PM2009+</name>
     <TimeSpan>
       <begin>2009-01-01</begin>
     </TimeSpan>
     <Point>
       <coordinates>-122.448425,37.802907,0</coordinates>
     </Point>
   </Placemark>

This TimeSpan contains only a <begin> tag, because it should exist for all dates from January 1st, 2009 onwards. This placemark is visible:

  • from all views for which no time is specified (note that previously-specified times apply to following views -- see Time is sticky below)
  • for all views for which the specified time is January 1st, 2009 or later

Views

Time can be attached to a view (a Camera or a LookAt) to specify the point in time from which the viewer is looking at the globe. The time can be a single point in time (TimeStamp) or a range (TimeSpan). 

<Camera>
  <gx:TimeStamp>
    <when>2009-01-01T17:00:00-08:00</when>
  </gx:TimeStamp>
  <longitude>-122.444633</longitude>
  <latitude>37.801899</latitude>
  <altitude>139.629438</altitude>
  <heading>-70.0</heading>
  <tilt>75</tilt>
</Camera>

This view shows the specified geographic location, with features present at the specified hour on January 1st, 2009. If sun is activated, it is displayed at the correct height in the sky, and shadows are drawn accordingly. The view in this example includes the sample placemark (PM2009+) we looked at earlier.

However, if <Camera> is edited to change the time to January 1st, 2008, placemark PM2009+ is not displayed. 

   <Camera>
     <gx:TimeStamp>
       <when>2008-01-01T17:00:00-08:00</when>
     </gx:TimeStamp>
     <longitude>-122.444633</longitude>
     <latitude>37.801899</latitude>
     <altitude>139.629438</altitude>
     <heading>-70.0</heading>
     <tilt>75</tilt>
   </Camera>

Time is sticky

Once a time has been specified in the KML, that time remains set until another time is specified. There is no way to clear the time selection.

Examples

Source: 

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://www.opengis.net/kml/2.2"
xmlns:gx="http://www.google.com/kml/ext/2.2">

  <Document>
    <Camera>
      <gx:TimeStamp>
        <when>2002-07-09T17:00:00-08:00</when>
      </gx:TimeStamp>
      <longitude>-122.444633</longitude>
      <latitude>37.801899</latitude>
      <altitude>139.629438</altitude>
      <heading>-70.0</heading>
      <tilt>75</tilt>
    </Camera>
    <Placemark>
      <name>PM2009+</name>
      <TimeSpan>
        <begin>2009-01-01</begin>
      </TimeSpan>
      <Point>
        <coordinates>-122.448425,37.802907,0</coordinates>
      </Point>
    </Placemark>
  </Document>
</kml>
<script type="text/javascript">
  var ge;
  google.load("earth", "1");

  function init() {
    google.earth.createInstance('map3d', initCB, failureCB);
  }

  function initCB(instance) {
    ge = instance;
    ge.getWindow().setVisibility(true);
    ge.getNavigationControl().setVisibility(ge.VISIBILITY_SHOW);
    ge.getSun().setVisibility(true);

    addKmlFromUrl('http://code.google.com/apis/earth/documentation/samples/time_example.kml');
  }

  function addKmlFromUrl(kmlUrl) {
    var link = ge.createLink('');
    link.setHref(kmlUrl);

    var networkLink = ge.createNetworkLink('');
    networkLink.setLink(link);
    networkLink.setFlyToView(true);

    ge.getFeatures().appendChild(networkLink);
  }

  function failureCB(errorCode) {
  }

  google.setOnLoadCallback(init);
</script>