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.
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 is currently available for the following platforms:
Although the plugin and API may work correctly on other browsers that support NPAPI with npruntime extensions, these browsers are not officially supported.
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.
|
/Library/Internet Plug-ins/Google Earth Web Plug-in.plugin before restarting your browser.To load the Google Earth Plugin in your web page, you need to:
These steps are explained below.
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 src="http://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.
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.
You will create three functions as part of this step. In order, they will:
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) {
}
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);
<html>
<head>
<title>Sample</title>
<script src="http://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>
If your code doesn't seem to be working, here are some approaches that might help you solve your problems:
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:
If you need more information about Google Earth, KML, or Google Maps, refer to the following: