My favorites ▼ | English ▼ | Sign in

Google Earth API

Google Earth API Developer's Guide

  1. Introduction
  2. Audience
  3. Installing the Google Earth Plugin
  4. Using the Google Earth API
  5. Troubleshooting
  6. Additional Resources

Introduction

Welcome to the developer documentation for the Google Earth API. The Google Earth Plugin 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 modelled after KML, so you should also consult Google's KML documentation.

The Google Earth Plugin

The Google Earth Plugin is currently supported on the following platforms:

  • Microsoft Windows (XP, and Vista)
    • Google Chrome 5.0+
    • Internet Explorer 7.0+
    • Firefox 3.0+
    • Flock 1.0+
  • Apple Mac OS X 10.5 and higher (Intel)
    • Google Chrome 5.0+
    • Safari 3.1+
    • Firefox 3.0+

Although the plugin 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 Plugin, browse to any page in which the plugin is included (e.g. http://code.google.com/apis/earth). Your browser will likely ask for permission before installing the plugin - click through to allow installation. Once the plugin is installed, you may need to refresh the page before the plugin 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 Plugin in your web page, you need to:

  1. Load the Google Earth API.
  2. Create a DIV element to hold the plugin.
  3. Create functions to initialize the plugin.
  4. Call the initialization functions once the page has loaded.

These steps are explained below.

Note: If you intend to use the Google Earth API under your Google Maps API for Business license, please refer to the Google Maps API for Business Developer's Guide for additional information.

Loading the Google Earth API

Place the following tag in the <head> of your HTML page, replacing ABCDEF with your own key (available from http://code.google.com/apis/maps/signup.html):

<script type="text/javascript" src="https://www.google.com/jsapi?key=ABCDEF"></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");

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".

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

Creating a container for the plugin

The Google Earth Plugin 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 plugin.

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 plugin
  • be called when the plugin 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 plugin instance is loaded in the browser. This function must contain the GEWindow.setVisibility method, setting the window visibility to true, so that the plugin 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 plugin 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 intialization 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 plugin 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?key=ABCDEFG"> </script>
   <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);
      }

      function failureCB(errorCode) {
      }

      google.setOnLoadCallback(init);
   </script>

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

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.
  • Make sure your API key is valid.
  • 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:

Developer channel

A developer channel plugin is available from http://earth.google.com/plugin/download-dev-plugin.html. This version of the plugin receives new features before they're released to the regular channel; it may however be less stable, and features launched only to the developer channel can be removed at any time.