Google Earth API

Google Earth API FAQ


What is the Google Earth Browser Plug-in?

The Google Earth Browser Plug-in is a web browser plugin that allows users to navigate and explore geographic data on a 3D globe. The look and feel of the plugin is similar to the Google Earth application, thereby providing a similar user experience.

What is the Google Earth API?

The Google Earth API is a JavaScript library that allows developers to add Earth plug-in objects to their sites. The API also provides programmatic access to the plug-in objects and the features inside of them. Web site developers can use the API to facilitate interaction between standard HTML elements and Earth plug-in instances.

Using the API you can draw markers and lines, drape images over the terrain, add 3D models, or load KML files, allowing you to build sophisticated 3D map applications. To see demonstrations of what the API and plug-in are capable of, visit the Earth API Examples section.

How do I start using the Google Earth API on my site?

To use the Google Earth API on your site, you will first need an API key from the Google APIs console. You may want to learn more about Maps API keys if you are unfamiliar with this system. You can then try out the Hello, Earth code sample or go straight to the Earth API Documentation section.

How can I be notified when there are changes to the Google Earth API?

Subscribe to the Google Geo Developers Blog to get news about Google's various geo developer offerings.

To be notified when there are changes in the Earth API, please subscribe to the Google Earth API Notify group.


Which operating systems does the Google Earth Plug-in support?

The Google Earth Plug-in currently supports the following operating systems:

  • Microsoft Windows 2000, XP and Microsoft Windows Vista
  • Apple Mac OS X 10.4 and higher (Intel and PowerPC)
Which web browsers does the Google Earth Plug-in support?

The Google Earth Plug-in is currently available for the following web browsers:

  • Microsoft Windows (2000, XP, and Vista)
    • Google Chrome 1.0+
    • Internet Explorer 6+
    • Firefox 3.0+
    • Flock 1.0+
  • Apple Mac OS X 10.4 and higher (Intel and PowerPC)
    • Google Chrome 1.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.

What are the other system requirements for the Google Earth Plug-in?

The system requirements for the Google Earth Plug-in are the same as the system requirements for Google Earth.


How do I ensure that my site runs the latest version of the API?

Because the API is dynamically loaded via the Google AJAX API loader interface (google.load), your site will automatically use the latest revision for the requested major API version (currently version 1).

How do I ensure that my users have the the latest version of the plug-in installed?

After installing the plug-in, users will receive updates automatically and without interruption as they become available.

How can I show my existing KML files on the web using the Google Earth API?

First, see the instructions on getting started with the Earth API above.

Once you have the Earth plugin working on your site, you can use the google.earth.fetchKml function to load any publicly accessible KML file. For examples on how to use fetchKml, see below:

View example (kml-fetch-good.html)

View example (kml-fetch-checkboxes.html)

How can I use the Google Earth API on my existing Google Maps API site?

To 3D-enable your existing Maps API page, simply add the following line to your map initialization code.

map.addMapType(G_SATELLITE_3D_MAP);

This assumes that the map variable is an instance of the google.maps.Map2 (GMap2) class. You should also ensure that a google.maps.MapTypeControl (GMapTypeControl) has been added to the map object so that users can switch to the 3D view.

View example (maps-integration.html)


What are the Terms of Service for the Google Earth API?

The Terms of Service for the Google Earth API are the same as the Terms of Service for the Google Maps API.

What information must I report to the Google Earth API?

Per Section 9.2 of the Terms of Service, developers must report whether their Earth API implementation uses a sensor to locate the user's device and show the location in Earth. An example of a sensor is the Geolocation module in Gears, which provides a latitude/longitude for a user based on their WIFI/GPS/Cell ID information.

To report whether or not your web site uses such a sensor, you can pass a parameter to google.load as follows:

If your web site does use a sensor, use this call:

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

Otherwise, use this call:

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

Note that since the sensor parameter was only recently introduced, pre-existing sites will not be disabled for failing to define the parameter. Developers are required to start reporting the parameter as soon as possible, however.


I'm having trouble installing the plug-in on Mac OS X. How else can I install the plug-in?

If you receive an installation error that reads:

The Installer encountered an unknown error that failed the install. Contact the software manufacturer for assistance.

you can try installing the plug-in via the Mac OS X terminal (command line interface) by following the steps below:

  1. Download and open the Google Earth Browser Plug-in installer file (the GoogleEarth-Mac-Plugin-<version>.dmg file).
  2. Ensure that the installer correctly mounted by opening Finder and looking for the GoogleEarth-Mac-Plugin item under the Devices section in Finder's left pane. If you don't see this item in Finder, try double-clicking the downloaded file again or see below on how to get more help.
  3. Quit all open browsers by choosing Safari > Quit Safari in Safari and Firefox > Quit Firefox in Firefox.
  4. Open the Terminal application by going to Applications > Utilities > Terminal in Finder.
  5. Enter the following command in the Terminal window and press the return key:
    sudo /usr/sbin/installer -pkg /Volumes/GoogleEarth-Mac-Plugin/GoogleEarthPlugin.mpkg -target /
    You may be asked for a password upon entering this command. If this is the case, type your Mac OS X password and press the return key.

    Note: Your password will not be shown on the screen. If you make a mistake while typing your password, you can quit the Terminal application and start again.

  6. Once the installation is completed, there will be a notice in the Terminal window indicating whether or not the installation succeeded.
    • If the installation succeeded, you can close the Terminal application and start using the plug-in by opening a supported browser.
    • If there was an error, you can get more help below.
How do I uninstall the plug-in on Mac OS X?

To uninstall the plugin on Mac OS X, delete the following folder before restarting your browser:

/Library/Internet Plug-ins/Google Earth Web Plug-in.plugin

Where can I submit plug-in and API feature requests?

We maintain a list of feature requests at our public issue tracking page.

Before submitting a new feature request, search the list to see if someone has already submitted something similar. If so, you can 'vote' for the feature by clicking the star icon next to the feature summary. You will receive e-mail updates whenever any of your starred feature requests are updated.

To submit a new feature request, click the 'New Issue' link at the top of the issue list and choose 'Feature Request' as the Template.

I think I've found a bug in the Earth API and/or plug-in. Where can I report it?

Before reporting a bug, please post your findings at the Google Earth API discussion group. Unexpected behavior seemingly due to a bug is oftentimes actually a result of incorrect JavaScript syntax or API usage.

We maintain a list of bugs at our public issue tracking page.

To report a bug that isn't already filed, click the 'New Issue' link at the top of the issue list and choose 'Bug' as the Template.

I have a different question/problem. Who should I contact?

Please post your question in the Google Earth API discussion group to get help from the Google Earth API developer community and the Earth API team.

For best results when requesting help, please keep the following in mind:

  • Search the current discussions. Chances are someone else has experienced a similar issue and found a fix.
  • Submit a link to your site if possible. Only post code snippets if the code is not easily viewable online.
  • Provide all relevant information including browser versions, errors, and all other facts that may be useful in troubleshooting this problem.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.