Google Earth API Developer's Guide

Introduction

Welcome to the developer documentation for the Google Earth API. The Google Earth Plug-in and its JavaScript API let you embed the full power of Google Earth and its 3D rendering capabilities into your web pages. Just like in the Google Maps API, you can draw markers and lines—but in 3D!

See the Google Earth API developer forum if you have have questions about the API after reading this developer guide.

Audience

This documentation is designed for people familiar with JavaScript programming and object-oriented programming concepts. The Google Earth API is modeled after KML, so you should also consult Google's KML documentation.

The Google Earth Plug-in

The Google Earth Plug-in is currently supported on the following platforms:

Microsoft Windows (Windows XP, Windows Vista, Windows 7, and Windows 8)
- Google Chrome 5.0-39.0^[1] (32-bit)
- Internet Explorer 7-9, and 10-11 with Compatibility View (32-bit)
  (Note that the Windows 8 browsing mode with Internet Explorer does not support plugins.)
- Firefox 11.0-34.0^[2]
  (The plug-in won't install while Firefox is running.)
Apple Mac OS X 10.6 or later (any Intel Mac)
- Google Chrome 5.0-39.0^[1]
- Safari 3.1+
- Firefox 11.0-34.0^[2]
  (The plug-in won't install while Firefox is running.)

[1] From the Chromium Blog: Saying Goodbye to Our Old Friend NPAPI.
[2] From the Mozilla Security Blog: Update on Plugin Activation.

Although the plug-in and API may work correctly on other browsers that support NPAPI with npruntime extensions, these browsers are not officially supported.

Installation

To install the Google Earth Plug-in, browse to any page in which the plug-in is included (e.g. http://code.google.com/apis/ajax/playground/#hello,_earth).

Your browser will likely ask for permission before installing the plug-in - click through to allow installation. Once the plug-in is installed, you may need to refresh the page before the plug-in displays correctly.

Uninstalling

Windows: Select Start > Programs (or All Programs) > Google Earth > Uninstall Google Earth Plug-in.
Mac: Delete /Library/Internet Plug-ins/Google Earth Web Plug-in.plugin before restarting your browser.

Using the Google Earth API

To load the Google Earth Plug-in in your web page, you need to:

Load the Google Earth API.
Create a DIV element to hold the plug-in.
Create functions to initialize the plug-in.
Call the initialization functions once the page has loaded.

These steps are explained below.

Loading the Google Earth API

Place the following tag in the <head> of your HTML page:

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

The tag's src points to a JavaScript file with a single method, google.load, used to load individual Google APIs. Inside a new <script> tag, call:

google.load("earth", "1", {"other_params":"sensor=true_or_false"});

This tells Google to load the earth module into the google.earth namespace, and specifies version 1 (the last stable version of the API). To specify the latest test version of the API, specify "1.x".

The sensor parameter must be included, and indicates whether this application uses a sensor (such as a GPS locator) to determine the user's location. We've left this example as a variable true_or_false to emphasize that you must set this value to either true or false explicitly.

For more information on the loading mechanism, refer to the Google AJAX APIs documentation.

Google Maps for Work customers

If you're using the Google Earth API with a Google Maps for Work license, you must include your client ID when calling the google.load() method. Specify your client ID within the other_params property, as follows:

google.load('earth','1', {'other_params':'client=YOUR_CLIENT_ID'});

Creating a container for the plug-in

The Google Earth Plug-in is loaded into a DIV element with a unique id. Add the DIV to your page's <body> section:

<div id="map3d" style="height: 400px; width: 600px;"></div>

In the example above, the DIV named map3d will become the target element for the plug-in.

Creating initialization functions

You will create three functions as part of this step. In order, they will:

Attempt to create a new instance of the plug-in.
Be called when the plug-in instance is successfully created.
Be called if the instance cannot be created.

The first function looks like this:

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

google.earth.createInstance here shows three options: the DIV element into which the instance should be added, the function to call when success is returned, and the function to call if a failure is returned. In addition to these options, you can specify an alternative database to connect to, in order to display Mars imagery or to connect to an Earth Enterprise database.

The success callback function will contain all of the code required to set up your 'first run' experience - all of the objects and views that will first appear when your plug-in instance is loaded in the browser. This function must contain the GEWindow.setVisibility method, setting the window visibility to true, so that the plug-in is visible inside its DIV:

function initCB(instance) {
   ge = instance;
   ge.getWindow().setVisibility(true);
}

The failure callback can contain any code to deal with a failure to create the plug-in instance. The error code is passed to the callback function, and can be repeated on the page or as an alert, if desired. Throughout this guide, the error callback function is left empty:

function failureCB(errorCode) {
}

Calling the initialization function when the page is loaded

The google namespace includes the setOnLoadCallback() function, which calls the specified function once the HTML page and requested APIs have been loaded. Using this function ensures that the plug-in is not loaded until the page's DOM is completely built out.

google.setOnLoadCallback(init);

Complete example

<html>
<head>
  <title>Sample</title>
  <script type="text/javascript" src="https://www.google.com/jsapi"> </script>
  <script type="text/javascript">
    var ge;
    google.load("earth", "1", {"other_params":"sensor=true_or_false"});

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

    function initCB(instance) {
      ge = instance;
      ge.getWindow().setVisibility(true);
    }

    function failureCB(errorCode) {
    }

    google.setOnLoadCallback(init);
  </script>

</head>
<body>
  <div id="map3d" style="height: 400px; width: 600px;"></div>
</body>
</html>

Loading Additional Databases

You can load your own database to display on the Google Earth globe by specifying that database during initialization, or by calling addSideDatabase() on the Earth object. Loading a database at initialization will load only that database; the standard Google Earth imagery will not be loaded.

To load a database when initializing the plug-in:

function init() {
  google.earth.createInstance('map3d', initCB, failureCB, {
    database: 'http://khmdb.google.com/?db=moon',
    username: '',
    password: '' // If your server requires these.
  });
}

Using addSideDatabase():

google.earth.addSideDatabase(
  ge, 'http://khmdb.google.com/?db=mars',
    sideDatabaseSuccess,
    sideDatabaseFail,
    {
      userName: '',
      password: ''
    }
);

For information about the Mars and Moon databases shown in the examples above, please read the Sky, Mars, and Moon chapter of this guide.

Disconnecting from a side database

To disconnect from a side database, call logout() on the side database object:

sideDB.logout()

Because a pointer to the database needs to exist, the side database must have been added using addSideDatabase():

var sideDB;

google.earth.addSideDatabase(
  ge, 'http://khmdb.google.com/?db=mars',
    sideDatabaseSuccess,
    sideDatabaseFail,
    {
      userName: '',
      password: ''
    }
);

function sideDatabaseSuccess(db) {
  sideDB = db;
}

function sideDatabaseDisconnect() {
  sideDB.logout();
}

Google Maps Engine maps

Note: Google Maps Engine uses the term map to refer to a collection of imagery and vector layers; it is the equivalent of a database in Google Earth Enterprise Fusion Pro. For more information, please refer to the Terminology section of the Tips for users of Google Earth Enterprise support article.

Google Maps Engine maps can be loaded into the plug-in using the methods above. The URL to a specific map is obtained by clicking the Google Earth option in the Published Links section of any published map's Details page.

google.earth.addSideDatabase(
  ge, 'https://earthbuilder.google.com/10446176163891957399-13516001307527776624-4/kh/',
    sideDatabaseSuccess,
    sideDatabaseFail,
    {
      userName: '',
      password: ''
    }
);

View sample: https://developers.google.com/earth/documentation/samples/addSideDatabase_noauth

If your map is public, no additional steps are required. If your map is private, you'll need to provide authentication credentials.

Authentication for Google Maps Engine maps

Users can authenticate to your map using their Google Account, if you've granted them access in Maps Engine. This is done using an OAuth 2.0 token; for information, please refer to the OAuth 2.0 documentation.

An example of loading the Earth API with an OAuth 2.0 token is below. You'll need:

An application ID, obtained from the API Access page of the API Console.
A valid redirect URI, also configured in the API Console. In the example below, it's assumed that the redirect URI is set to the same value as the application's URI (i.e. the authentication process will return the user to the originating page once authentication is complete).

var ge;

// Google Maps API for Work users must specify their client ID when loading
// the Google Earth API.
// var params = {"other_params":"client=YOUR_MAPSFORWORK_CLIENTID&sensor=false"};
var params = {"other_params":"sensor=false"};
google.load("earth", "1", params);

function init() {
  var hash_value = window.location.hash;
  if (!hash_value) {
    var redirect_url = "https://accounts.google.com/o/oauth2/auth";
    // The client_id value below is obtained from the APIs Console.
    // It is not the same as a Google Maps API for Work client ID.
    redirect_url += "?client_id=370755043334.apps.googleusercontent.com";
    redirect_url += "&redirect_uri=" + window.location.href;
    redirect_url += "&scope=https://www.googleapis.com/auth/earthbuilder.readonly"
                  + "%20https://www.googleapis.com/auth/userinfo.email";
    redirect_url += "&response_type=token";
    window.location = redirect_url;
    return;
  }

  if (hash_value[0] == "#") {
    hash_value = hash_value.slice(1);
  }

  var hash_parts = hash_value.split("&");
  for (var i = 0; i < hash_parts.length; ++i) {
    var name_value = hash_parts[i].split("=");
    if (name_value.length == 2) {
      var name = name_value[0];
      var value = name_value[1];
      if (name == "access_token") {
        g_oauth_token_value = value;
      }
    }
  }

  if (!g_oauth_token_value) {
    return;
  }

  var optArgs = {
    oauth2Info : {
      oauthToken: g_oauth_token_value,
      signingUrl: 'https://earthbuilder.google.com/'
    }
  };
  google.earth.createInstance('map3d', initCB, failureCB, optArgs);
}

function initCB(instance) {
  ge = instance;
  ge.getWindow().setVisibility(true);
  ge.getOptions().setStatusBarVisibility(true);
  ge.getNavigationControl().setVisibility(ge.VISIBILITY_AUTO);
  ge.getLayerRoot().enableLayerById(ge.LAYER_BORDERS, true);
  ge.getLayerRoot().enableLayerById(ge.LAYER_ROADS, true);

  var lookAt = ge.createLookAt('');
  lookAt.setLatitude(41.26);
  lookAt.setLongitude(-100.00);
  lookAt.setRange(800000.0);
  ge.getView().setAbstractView(lookAt);

  // Substitute a valid Maps Engine URL below. The URL is obtained
  // by clicking the Google Earth option in the Published Links
  // section of any published map's Details page.
  var earthDb = 'https://earthbuilder.google.com/01234-5678-9/kh/';
  google.earth.addSideDatabase(
    ge, earthDb,
    sideDatabaseSuccess,
    sideDatabaseFail,
    {
      userName: '',
      password: ''
    }
  );
}

function failureCB(errorCode) {
  alert(errorCode);
}

function sideDatabaseSuccess(db) {
  db.setDrawOrder(2);
}

function sideDatabaseFail() {
  alert('Failed to add side database connection.');
}

google.setOnLoadCallback(init);

Troubleshooting

If your code doesn't seem to be working, here are some approaches that might help you solve your problems:

Use a JavaScript debugger. More information, including a list of common applications, is available in the Debugging section of this guide.
Look for typos. Remember that JavaScript is a case-sensitive language.
Search the developer forum. If you can't find a post that answers your question, post your question to the group along with a link to a web page that demonstrates the problem.
See Additional Resources for more developer resources.

Additional Resources

This guide contains a number of working examples, linked from the Source line above the relevant code sample. In addition to the samples in this documentation, the following resources contain a number of examples:

AJAX APIs Playground - an interactive selection of examples that can be edited directly on the page. Your code can be exported and saved as JavaScript or HTML.
Earth API Demo Gallery - a collection of Earth API demos and samples, including community contributions.
Basic Samples - Investigate individual API features with these standalone samples containing full HTML.

If you need more information about Google Earth, KML, or Google Maps, refer to the following: