Google Earth API

Touring

  1. Introduction
  2. Importing a tour
  3. Defining the active tour
  4. Controlling tour playback
  5. Querying tour playback information
  6. Complete tour playback sample

Introduction

The Google Earth Plugin can play tours authored in KML, allowing viewers to interact with the Earth environment while viewing scripted, controlled tours. The plugin currently exposes tour playback methods; tour authoring is not supported in the plugin.

Importing a tour

Simple tour

Simple tours, with the <gx:Tour> feature as the root-level feature of the KML, can be fetched and passed directly to GETourPlayer. The tour must be the only feature in the KML file. If your KML doesn't meet these requirements, refer to the Complex tour example below.

<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);
 
   var href = 'http://developers.google.com/kml/documentation/kmlfiles/bounce_example.kml';
   google.earth.fetchKml(ge, href, kmlFinishedLoading);
}

function kmlFinishedLoading(object) {
   ge.getTourPlayer().setTour(object);
   ge.getTourPlayer().play();
}

function failureCB(errorCode) {
}

google.setOnLoadCallback(init);
</script>

Complex tour

If your tour is contained within a KMZ file, or if your KML file contains more than just a tour, or if the tour is nested within a container (such as <Document> or <Folder>), you'll need to manually look for the <gx:Tour> feature within the file. One way is to 'walk' through the file's DOM until the KMLTour feature is found. You can use the kmldomwalk.js utility script to do this.

In the example below, the KML file includes some placemarks and features, which need to be loaded into Earth as well.

First, reference the kmldomwalk.js file from your page's <head>:

<script src="http://earth-api-samples.googlecode.com/svn/trunk/lib/kmldomwalk.js" type="text/javascript"></script>

Then:

<script type="text/javascript">

  var ge;
  var tour;
  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);

    var href = 'http://developers.google.com/kml/documentation/kmlfiles/complete_tour_example.kml';
    google.earth.fetchKml(ge, href, fetchCallback);
  }

  function fetchCallback(fetchedKml) {
    // Alert if no KML was found at the specified URL.
    if (!fetchedKml) {
      setTimeout(function() {
        alert('Bad or null KML');
      }, 0);
      return;
    }

    // Add the fetched KML into this Earth instance.
    ge.getFeatures().appendChild(fetchedKml);

    // Walk through the KML to find the tour object; 
    // assign to variable 'tour'.
    walkKmlDom(fetchedKml, function() {
      if (this.getType() == 'KmlTour') {
        tour = this;
        return false;
      }
    });
  }

  function failureCB(errorCode) {
  }

  google.setOnLoadCallback(init);

</script>

The preceding code simply loads the fetched tour into the Earth plugin. It doesn't include controls for setting the fetched tour as active, or for controlling playback. Refer to Defining the active tour and Controlling tour playback for more information. The entire tour with controls is included in the Sample tour section.

Defining the active tour

Any number of tour objects can be loaded into the plugin, but only one can be set as the currently active tour. Once a tour is set as active, the tour controls appear on the screen:

ge.getTourPlayer().setTour(tour);

Use setTour(null) to exit the currently active tour and to restore normal globe navigation:

ge.getTourPlayer().setTour(null);

Controlling tour playback

The Earth API supports the following calls to control tour playback:

Function Description
ge.getTourPlayer().play() Plays the currently active tour
ge.getTourPlayer().pause() Pauses the currently active tour
ge.getTourPlayer().reset() Stops playback of the currently active tour and jumps to the beginning of the tour
ge.getTourPlayer().setCurrentTime(time) Sets playback to the specified point on the tour's timeline, in seconds.

Querying tour playback information

The Earth API supports the following calls to query for current tour playback information:

Function Description
ge.getTourPlayer().getCurrentTime() Retrieves the current elapsed playing time of the tour, in seconds.
ge.getTourPlayer().getDuration() Retrieves the total duration of the active tour, in seconds.

Complete tour playback sample

Source: http://developers.google.com/earth/documentation/samples/tour_example.html

<html>
   <head>
      <title>Sample tour in the Google Earth Plugin</title>
      <script src="https://www.google.com/jsapi"> </script> 
      <script src="http://earth-api-samples.googlecode.com/svn/trunk/lib/kmldomwalk.js" type="text/javascript"> </script>
      <script type="text/javascript">

         var ge;
         var tour;
         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);

            var href = 'http://developers.google.com/kml/documentation/kmlfiles/complete_tour_example.kml';
            google.earth.fetchKml(ge, href, fetchCallback);

            function fetchCallback(fetchedKml) {
               // Alert if no KML was found at the specified URL.
               if (!fetchedKml) {
                  setTimeout(function() {
                     alert('Bad or null KML');
                  }, 0);
                  return;
               }

               // Add the fetched KML into this Earth instance.
               ge.getFeatures().appendChild(fetchedKml);

               // Walk through the KML to find the tour object; assign to variable 'tour.'
               walkKmlDom(fetchedKml, function() {
                  if (this.getType() == 'KmlTour') {
                     tour = this;
                     return false;
                  }
               });
            }
         }

         function failureCB(errorCode) {
         }

         // Tour control functions.
         function enterTour() {
            if (!tour) {
               alert('No tour found!');
               return;
            }
            ge.getTourPlayer().setTour(tour);
         }
         function playTour() {
            ge.getTourPlayer().play();
         }
         function pauseTour() {
            ge.getTourPlayer().pause();
         }
         function resetTour() {
            ge.getTourPlayer().reset();
         }
         function exitTour() {
            ge.getTourPlayer().setTour(null);
         }

         google.setOnLoadCallback(init);
      </script>
   </head>
   <body>

      <div id="map3d" style="height: 400px; width: 600px;"></div>
      <div id ="controls">
         <input type="button" onclick="enterTour()" value="Enter Tour"/>
         <input type="button" onclick="playTour()" value="Play Tour"/>
         <input type="button" onclick="pauseTour()" value="Pause Tour"/>
         <input type="button" onclick="resetTour()" value="Stop/Reset Tour"/>
         <input type="button" onclick="exitTour()" value="Exit Tour"/>
      </div>

   </body>
</html>

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.