Google Earth COM API Documentation

List of all members.


Public Types
enum	AppTypeGE { EnterpriseClientGE = 0, ProGE = 1, PlusGE = 2, FreeGE = 5, UnknownGE = 0xFF }
	The application type of Google Earth (EC, Pro, Plus or Free). More...
Public Member Functions
HRESULT	GetCamera ([in] BOOL considerTerrain,[out, retval] ICameraInfoGE **pCamera)
	Returns the current camera view in the running instance of Google Earth.
HRESULT	SetCamera ([in] ICameraInfoGE *camera,[in] double speed)
	Flies to the specified camera view at the specified speed.
HRESULT	SetCameraParams ([in] double lat,[in] double lon,[in] double alt,[in] AltitudeModeGE altMode,[in] double range,[in] double tilt,[in] double azimuth,[in] double speed)
	Flies to the specified camera without requiring an ICameraInfoGE instance.
HRESULT	SaveScreenShot ([in] BSTR fileName,[in] long quality)
	Takes low quality black and white screen shot of the current camera view.
HRESULT	OpenKmlFile ([in] BSTR fileName,[in] BOOL suppressMessages)
	Schedules a KML file to be loaded in Google Earth.
HRESULT	LoadKmlData ([in] BSTR *kmlData)
	Loads KML into Google Earth.
HRESULT	GetFeatureByName ([in] BSTR name,[out, retval] IFeatureGE **pFeature)
	Retrieves a feature matching a given name.
HRESULT	GetFeatureByHref ([in] BSTR href,[out, retval] IFeatureGE **pFeature)
	Returns the feature with a given href.
HRESULT	SetFeatureView ([in] IFeatureGE *feature,[in] double speed)
	Flies to the view of the given feature at the specified speed.
HRESULT	GetPointOnTerrainFromScreenCoords ([in] double screen_x,[in] double screen_y,[out, retval] IPointOnTerrainGE **pPoint)
	Returns point on terrain from screen coordinates.
HRESULT	IsInitialized ([out, retval] BOOL *isInitialized)
	Indicates if Google Earth has logged in or not.
HRESULT	IsOnline ([out, retval] BOOL *isOnline)
	Returns whether the application is connected to the data server or not.
HRESULT	Login ()
	Logs into the default default session if the application is logged out.
HRESULT	Logout ()
	Logs out of the current session if the application is logged in.
HRESULT	ShowDescriptionBalloon ([in] IFeatureGE *feature)
	Displays the description balloon for a given feature.
HRESULT	HideDescriptionBalloons ()
	Hides all visible description balloons.
HRESULT	GetHighlightedFeature ([out, retval] IFeatureGE **pFeature)
	Retrieves currently highlighted feature (i.e. with focus).
HRESULT	GetMyPlaces ([out, retval] IFeatureGE **pMyPlaces)
	Retrieves My Places folder.
HRESULT	GetTemporaryPlaces ([out, retval] IFeatureGE **pTemporaryPlaces)
	Retrieves Temporary Places folder.
HRESULT	GetLayersDatabases ([out, retval] IFeatureCollectionGE **pDatabases)
	Retrieves databases from the layers list.
HRESULT	GetMainHwnd ([out, retval] OLE_HANDLE *hwnd)
	Returns Windows handle for Google Earth's main window.
HRESULT	GetRenderHwnd ([out, retval] OLE_HANDLE *hwnd)
	Returns Windows handle for Google Earth's render window.
Properties
long	StreamingProgressPercentage `[get]`
	Current streaming percentage.
double	AutoPilotSpeed `[get, set]`
	Autopilot speed used for flying to features.
IViewExtentsGE	ViewExtents `[get]`
	Current view extents as an IViewExtentsGE instance.
int	VersionMajor `[get]`
	The application's version major number.
int	VersionMinor `[get]`
	The application's version minor number.
int	VersionBuild `[get]`
	The application's build number.
AppTypeGE	VersionAppType `[get]`
	Google Earth's application type.
double	ElevationExaggeration `[get, set]`
	Terrain elevation exaggeration.
ITourControllerGE	TourController `[get]`
	Tour controller for the application. Contains tour options and controls.
ISearchControllerGE	SearchController `[get]`
	Search controller for the application. Contains search options and controls.
IAnimationControllerGE	AnimationController `[get]`
	Animation controller for the application. Contains animation options and controls.

Detailed Description

This interface can be used to query and control the Google Earth application from an external application.

Member Enumeration Documentation

enum IApplicationGE::AppTypeGE

The application type of Google Earth (EC, Pro, Plus or Free).

See also:: VersionAppType

Enumerator:

EnterpriseClientGE	Google Earth Enterprise Client.
ProGE	Google Earth Pro.
PlusGE	Google Earth Plus.
FreeGE	Google Earth Free.
UnknownGE	Unknown (error).

Member Function Documentation

HRESULT IApplicationGE::GetCamera	(	[in] BOOL	considerTerrain,
		[out, retval] ICameraInfoGE **	pCamera
	)

Returns the current camera view in the running instance of Google Earth.

Note:: After the function returns, pCamera is not updated if the Google Earth camera view changes.

Parameters:

	considerTerrain	Takes terrain into account when computing focus point when no explicit focus point is defined. If `true` and no explicit focus point is defined, then automatically computes focus point by intersecting the terrain in front of the camera. This option is more accurate but is more computationally expensive. If `false` and no explicit focus point is defined, then automatically computes focus point by intersecting a spherical representation of the Earth in front of the camera. This option is less computationally expensive but less accurate.
	pCamera	The returned ICameraInfoGE instance.

Return values:

	S_OK	Successfully retrieved camera.
	E_APPLICATION_UNINITIALIZED	Google Earth is not initialized. See IsInitialized.
	(other)	Appropriate error code (e.g. problems creating camera object).

See also:: SetCamera, ICameraInfoGE

HRESULT IApplicationGE::SetCamera	(	[in] ICameraInfoGE *	camera,
		[in] double	speed
	)

Flies to the specified camera view at the specified speed.

Interpolates the camera position and orientation from the current configuration to the one specified by camera. The camera motion speed is given by speed.

Parameters:

	camera	The camera view to fly to.
	speed	Speed factor to use. Overrides autopilot speed. Value must be greater than `0`. If greater than or equal to `5.0`, the camera will immediately be set without any transition. This mode is called 'teleport'.

Return values:

	S_OK	Successfully set camera.
	S_TELEPORTED	Given Speed is greater than or equal to `5.0`, in which case application's camera was teleported to the destination view.
	E_INVALIDARG	Invalid argument(s) (e.g. speed is not more than zero).
	E_APPLICATION_UNINITIALIZED	Google Earth is not initialized. See IsInitialized.
	(other)	Appropriate error code.

See also:: SetCameraParams, GetCamera, ICameraInfoGE

HRESULT IApplicationGE::SetCameraParams	(	[in] double	lat,
		[in] double	lon,
		[in] double	alt,
		[in] AltitudeModeGE	altMode,
		[in] double	range,
		[in] double	tilt,
		[in] double	azimuth,
		[in] double	speed
	)

Flies to the specified camera without requiring an ICameraInfoGE instance.

This is provided for performance reasons.

This is an optimized way of setting the camera rather than using SetCamera since it requires a much smaller number of COM calls.

Parameters:

	lat	Latitude in degrees. Between `-90` and `90`.
	lon	Longitude in degrees. Between `-180` and `180`.
	alt	Altitude in meters.
	altMode	Altitude mode that defines altitude reference origin.
	range	Distance between focus point and camera in meters.
	tilt	Tilt angle in degrees. Between `0` and `90`.
	azimuth	Azimuth angle in degrees.
	speed	Speed factor to use. Overrides autopilot speed. Value must be greater than `0`. If greater than or equal to `5.0`, the camera will immediately be set without any transition. This mode is called 'teleport'.

Return values:

	S_OK	Successfully set camera.
	S_TELEPORTED	Given speed is grater than or equal to `5.0`, in which case application's camera was teleported to the destination view.
	E_INVALIDARG	invalid argument(s) (e.g. speed is not more than zero).
	E_APPLICATION_UNINITIALIZED	Google Earth is not initialized. See IsInitialized.
	(other)	Appropriate error code.

See also:: SetCamera, ICameraInfoGE

HRESULT IApplicationGE::SaveScreenShot	(	[in] BSTR	fileName,
		[in] long	quality
	)

Takes low quality black and white screen shot of the current camera view.

This image is not meant to be used for rapid capture and degrades in quality if used frequently.

Parameters:

	fileName	Full path JPG filename of output screen shot.
	quality	Quality factor of output image. Lowest quality is `0` and highest quality is `100`. Input quality is always clamped to (`0`, `100`) inclusive.

Return values:

	S_OK	Successfully saved screen shot.
	(other)	Appropriate error code.

HRESULT IApplicationGE::OpenKmlFile	(	[in] BSTR	fileName,
		[in] BOOL	suppressMessages
	)

Schedules a KML file to be loaded in Google Earth.

Parameters:

	fileName	The full path name of the file to be loaded, with forward slashes '/' as the directory delimiter character. If possible, the application will fly to the view of the feature(s) that were created after opening that file.
	suppressMessages	If `true`, ignores all common KML loading dialog boxes warnings and errors, and chooses the default option for each one. For example, this function ignores confirmations to reload a previously loaded KML file and losing unsaved changes. This function will not ignore dialog boxes with critical errors such as when core libraries cannot be loaded.

Return values:

	S_OK	File scheduled to be loaded. If there is a problem with the file data (e.g. corrupted data), this method returns `S_OK` even if the file is not succesfully loaded.
	(other)	Appropriate error code.

See also:: LoadKmlData

HRESULT IApplicationGE::LoadKmlData ( [in] BSTR * kmlData )

Loads KML into Google Earth.

This loads KML data from a string as opposed to loading from a file.

Parameters:

kmlData

String containing KML data. This must contain valid KML data.

Return values:

	S_OK	Successfully loaded KML data.
	(other)	Appropriate error code.

/see OpenKmlFile

HRESULT IApplicationGE::GetFeatureByName	(	[in] BSTR	name,
		[out, retval] IFeatureGE **	pFeature
	)

Retrieves a feature matching a given name.

Returns the first feature with the given name by searching in the "Search Results", "Places", and "Layers" panels and returning it as a IFeatureGE.

Note:: A name is not necessarily unique, so another option is to use GetFeatureByHref, which some features support.

Parameters:

	name	Feature name to be retrieved
	pFeature	Output feature. If there is more than one feature with given name, returns first instance. If no features exist with given name, returns `NULL`.

Return values:

	S_OK	Successfully found zero or more features. Set pFeature to `NULL` or to the first feature.
	(other)	Appropriate error code.

See also:: GetFeatureByHref, IFeatureGE::Name

HRESULT IApplicationGE::GetFeatureByHref	(	[in] BSTR	href,
		[out, retval] IFeatureGE **	pFeature
	)

Returns the feature with a given href.

Searches for feature in the Places and Layers panels and returns it as a IFeatureGE.

href is case sensitive and uses forward slashes '/' as the directory delimiter.

href is in the format: FileName#FeatureID

For example, if you have a KML file C:/simple.kml, with the following placemark:
<Placemark id="SomeID">

then the corresponding href would be:
C:/simple.kml#SomeID

Although not all features have hrefs, an href is a unique identifier (unlike a name).

Parameters:

	href	String that identifies feature as explained above.
	pFeature	Output feature matching given href. If no feature is found matching href, then it is set to `NULL`.

Return values:

	S_OK	Successfully found zero or one feature. Set pFeature to `NULL` or to the appropriate feature.
	(other)	Appropriate error code.

See also:: GetFeatureByName

HRESULT IApplicationGE::SetFeatureView	(	[in] IFeatureGE *	feature,
		[in] double	speed
	)

Flies to the view of the given feature at the specified speed.

This method fails if the specified feature has no view.

See also:: SetCamera, IFeatureGE::HasView

Parameters:

	feature	Destination feature to fly camera.
	speed	Speed factor to use. Overrides autopilot speed. Value must be greater than `0`.

Return values:

	S_OK	Successfully flying camera.
	E_INVALIDARG	Invalid argument(s).
	E_INVALID_OR_DELETED_FEATURE	Feature represents an invalid or deleted feature.
	E_FEATURE_HAS_NO_VIEW	Feature has no view.
	(other)	Appropriate error code.

See also:: SetCamera, IFeatureGE::HasView

HRESULT IApplicationGE::GetPointOnTerrainFromScreenCoords	(	[in] double	screen_x,
		[in] double	screen_y,
		[out, retval] IPointOnTerrainGE **	pPoint
	)

Returns point on terrain from screen coordinates.

This method allows an external application to query the geolocation and terrain altitude of a point in the 3D viewpoint identified by its normalized screen coordinates (screen_x, screen_y), ranging from (-1, -1) to (+1, +1) inclusive.
Here are some examples:

(-1, -1) - bottom left hand corner of the screen.
(0,0) - center of the screen.
(1, 1) - top right hand corner of the screen.

To convert from pixel coordinates to these normalized screen coordinates, it may be helpful to use GetRenderHwnd and retrieve the render window's position and dimensions for these computations.

The coordinates of the point on terrain are returned in as a IPointOnTerrainGE.

If the input screen coordinates do not intersect with the globe, then this function returns the projected point on the globe's horizon and with the IPointOnTerrainGE::ProjectedOntoGlobe set to true.

The IPointOnTerrainGE::Altitude is set in the following way:

if ElevationExaggeration is non-zero, then IPointOnTerrainGE::Altitude is set to be the terrain's true altitude and IPointOnTerrainGE::ZeroElevationExaggeration is set to false, or
if ElevationExaggeration is zero, then IPointOnTerrainGE::Altitude is set to zero and IPointOnTerrainGE::ZeroElevationExaggeration is set to true.

Parameters:

	screen_x	Normalized screen position along the x axis. Valid range is from `-1` (left hand side of the screen) to `+1` (right hand side of the screen). Values outside the valid range are clamped.
	screen_y	Normalized screen position along the y axis. Valid range is from -1 (bottom of the screen) to +1 (top of the screen). Values outside the valid range are clamped.
	pPoint	Retrieved point. See details above.

Return values:

	S_OK	Successfully retrieved point.
	(other)	Appropriate error code.

See also:: GetRenderHwnd

HRESULT IApplicationGE::IsInitialized ( [out, retval] BOOL * isInitialized )

Indicates if Google Earth has logged in or not.

When the application is initialized, the user has access to most functionality but may or may not be connected to the data server. To check if the application is connected to the data server, use IsOnline instead.

Parameters:

isInitialized

Output status.

Return values:

	S_OK	Successfully retrieved status.
	(other)	Appropriate error code.

See also:: Online, Login, Logout

HRESULT IApplicationGE::IsOnline ( [out, retval] BOOL * isOnline )

Returns whether the application is connected to the data server or not.

If the application is connected to the server, then Google Earth uses the server's Layers databases. Otherwise, it uses local cached Layers databases.

Parameters:

isOnline

Output status.

Return values:

	S_OK	Successfully retrieved status.
	(other)	Appropriate error code.

See also:: Online, Login, Logout

HRESULT IApplicationGE::Login ( )

Logs into the default default session if the application is logged out.

This function attempts to do two things:

Initializes the application, in which case IsInitialized becomes TRUE.
Attempts to connect to default server, and
- If successful, IsOnline becomes TRUE and application uses server's Layers databases.
- If unsuccessful, IsOnline becomes FALSE and application uses local cached Layer databases.

Note:: Logging in may take a few moments after this function returns.

Return values:

	S_OK	Function tries to log in. Use IsInitialized and IsOnline after a few moments to figure out more detailed results.
	S_FALSE	Application was already logged in.
	E_APPLICATION_UNINITIALIZED	Google Earth Application is not initialized. See IsInitialized.

See also:: Logout, IsInitialized, IsOnline

HRESULT IApplicationGE::Logout ( )

Logs out of the current session if the application is logged in.

This forces both IsInitialized and IsOnline to be FALSE.

Return values:

	S_OK	Successfully logged out.
	E_APPLICATION_UNINITIALIZED	Google Earth Application is not initialized. See IsInitialized.
	(other)	Appropriate error code.

See also:: Login, IsInitialized, IsOnline

HRESULT IApplicationGE::ShowDescriptionBalloon ( [in] IFeatureGE * feature )

Displays the description balloon for a given feature.

Shows the description balloon for a feature that has a view. This method fails if the specified feature has no view.

See also:: IFeatureGE::HasView

Note:: Turning on the description balloon for a feature may turn off the description balloons for other features.

Parameters:

feature

The feature for which the description balloon appears.

Return values:

	S_OK	Successfully turned on description balloon for feature.
	E_INVALID_OR_DELETED_FEATURE	feature represents an invalid or deleted feature.
	E_FEATURE_HAS_NO_VIEW	Feature has no view.
	(other)	Appropriate error code.

See also:: HideDescriptionBalloons

HRESULT IApplicationGE::HideDescriptionBalloons ( )

Hides all visible description balloons.

Turns off any visible description balloons for all features.

Return values:

	S_OK	Successfully hid all description balloons.
	(other)	Appropriate error code.

See also:: ShowDescriptionBalloon

HRESULT IApplicationGE::GetHighlightedFeature ( [out, retval] IFeatureGE ** pFeature )

Retrieves currently highlighted feature (i.e. with focus).

Parameters:

pFeature Output highlighted feature. If no feature is highlighted, this is set to NULL.

Return values:

	S_OK	Successfully set pFeature to highlighted feature or set it to `NULL` if none is higlighted.
	(other)	Appropriate error code.

See also:: IFeatureGE::Highlighted, IFeatureGE::Highlighted

HRESULT IApplicationGE::GetMyPlaces ( [out, retval] IFeatureGE ** pMyPlaces )

Retrieves My Places folder.

Parameters:

pMyPlaces Output feature for My Places folder. If folder is unavailable, this is set to NULL.

Return values:

	S_OK	Successfully set pMyPlaces to My Places folder or set it to `NULL` if My Places is unavailable.
	(other)	Appropriate error code.

See also:: GetTemporaryPlaces, GetLayersDatabases, ISearchControllerGE::GetResults

HRESULT IApplicationGE::GetTemporaryPlaces ( [out, retval] IFeatureGE ** pTemporaryPlaces )

Retrieves Temporary Places folder.

Parameters:

pTemporaryPlaces Output feature for Temporary Places. folder. If folder is unavailable, this is set to NULL.

Return values:

	S_OK	Successfully set pTemporaryPlaces to Temporary Places folder or set it to `NULL` if Temporary Places is unavailable.
	(other)	Appropriate error code.

See also:: GetMyPlaces, GetLayersDatabases, ISearchControllerGE::GetResults

HRESULT IApplicationGE::GetLayersDatabases ( [out, retval] IFeatureCollectionGE ** pDatabases )

Retrieves databases from the layers list.

Returns the layers databases as a collection of features. This allows for traversal of all available layers features.

Parameters:

pDatabases

Output enum of database features.

Return values:

	S_OK	Successfully retrieved databases.
	(other)	Appropriate error code (e.g. problems creating enum object).

See also:: GetMyPlaces, GetTemporaryPlaces, ISearchControllerGE::GetResults

HRESULT IApplicationGE::GetMainHwnd ( [out, retval] OLE_HANDLE * hwnd )

Returns Windows handle for Google Earth's main window.

This is useful for resizing and positioning the Google Earth window.

Parameters:

hwnd

Output window handle for Google Earth.

Return values:

	S_OK	Succesfully retrieved window handle.
	(other)	Appropriate error code.

See also:: GetRenderHwnd

HRESULT IApplicationGE::GetRenderHwnd ( [out, retval] OLE_HANDLE * hwnd )

Returns Windows handle for Google Earth's render window.

This is useful for:

Getting and setting render window dimensions. Needed for converting between pixel coordinates and screen coordinates. Also helpful for resizing the window for screenshots or videos.
Drawing things on top of the render window.
Other things requiring Win32 functions.

Parameters:

hwnd

Output window handle for render window.

Return values:

	S_OK	Succesfully retrieved window handle.
	(other)	Appropriate error code.

See also:: GetMainHwnd

Property Documentation

long IApplicationGE::StreamingProgressPercentage [get]

Current streaming percentage.

Represented as a value between 0 and 100. The value 100 means streaming for the current view is complete.

double IApplicationGE::AutoPilotSpeed [get, set]

Autopilot speed used for flying to features.

This is the speed factor Google Earth uses when automatically flying to features after loading them, or when the user double-clicks on a placemark. Valid values are between 0.0 and 5.0. A value of 1.0 yields quite fast transitions. A value of 5.0 sets the autopilot in teleport mode, which means double clicking on a placemark will immediately fly to that placemark's view, with no transition between the current view and the target view.

The autopilot speed is not taken into account in the SetCamera method and all its other forms (such as SetCameraParams), since all of them take in a speed argument which overrides the default autopilot speed.

See also:: SetCamera, SetCameraParams

IViewExtentsGE IApplicationGE::ViewExtents [get]

Current view extents as an IViewExtentsGE instance.

The latitude/longitude bounding box as a coarse approximation of what is visible in the 3D viewer of Google Earth.

int IApplicationGE::VersionMajor [get]

The application's version major number.

Google Earth versions are in the following format:
major.minor.build appType

In the example 4.0.1693 Free, major is 4.

See also:: VersionMinor, VersionBuild, VersionAppType

int IApplicationGE::VersionMinor [get]

The application's version minor number.

Google Earth versions are in the following format:
major.minor.build appType

In the example 4.0.1693 Free, minor is 0.

See also:: VersionMajor, VersionBuild, VersionAppType

int IApplicationGE::VersionBuild [get]

The application's build number.

Google Earth versions are in the following format:
major.minor.build appType

In the example 4.0.1693 Free, build is 1693.

See also:: VersionMajor, VersionMinor, VersionAppType

AppTypeGE IApplicationGE::VersionAppType [get]

Google Earth's application type.

Google Earth versions are in the following format:
major.minor.build appType

In the example 4.0.1693 Free, AppType is FreeGE.

See also:: VersionMajor, VersionMinor, VersionBuild

double IApplicationGE::ElevationExaggeration [get, set]

Terrain elevation exaggeration.

Valid values are between 0 and 3 inclusive. This amplifies the altitude of the terrain by a given factor.

Note:: If exaggeration is 0, GetPointOnTerrainFromScreenCoords always returns an altitude of 0.

Examples:

a value of 0 displays a flat terrain,
a value of 1 (default) displays the terrain at true altitude, and
a value of 3 displays the terrain at three times the true altitude.

IApplicationGE Interface Reference

Public Types

Public Member Functions

Properties

Detailed Description

Member Enumeration Documentation

Member Function Documentation

Property Documentation