JavaScript API

The easiest way how to embed a 3D globe in any webpage. Simple but still very powerful API. No plugin needed.

To learn how to use WebGL Earth JavaScript API please see a simple example:

The "Hello World"

<!DOCTYPE HTML>
<html>
<head>
<script src="http://www.webglearth.com/api.js"></script>
<script>
  function initialize() {
    var options = { zoom: 3.0, position: [47.19537,8.524404] };
    var earth = new WebGLEarth('earth_div', options);
  }
</script>
</head>
<body onload="initialize()">
  <h1>WebGL Earth API: Hello World</h1>
  <div id="earth_div" style="width:600px;height:400px;border:1px solid gray; padding:2px;"></div>
</body>
</html>

Try the live version: helloworld.html

As you see, first you need to load the WebGL Earth API from http://www.webglearth.com/api.js.
You choose an HTML container (the <div> element typically) - to embed the earth to. Finally you call the initialization of the object WebGLEarth('earth_div') from JavaScript - to display the Earth inside of the provided div element.

Please check the other examples of the JavaScript API on the right side of this page. Feel free to copy&paste any of these and start to create something cool! And let us know at the mailing-list. ;-)

JavaScript API Reference

In this moment the JavaScript API is pretty simple, but it will grow in the future. Review the list of available methods:

WebGLEarth object

Constructor

Constructor Description
WebGLEarth(divId:string, opts?:{...}) Creates a new globe inside of the given HTML element (usually a DIV).
Optionally it accepts object with following parameters:

map - (WebGLEarth.Maps.OSM or WebGLEarth.Maps.MAPQUEST)
zoom : number
position : [lat,lng]
altitude : number
panning : boolean
tilting : boolean
zooming : boolean
atmosphere : boolean
proxyHost : string

Methods

Method Description
setPosition(lat,lng,zoom?) Sets camera to the given latitude / longitude position
getPosition() : [lat,lng] Return the center of in the form of array with two real numbers (latitude and longitude).
 setCenter([lat,lng])  Deprecated, use setPosition()
 getCenter() : [lat,lng]  Deprecated, use getPosition()
 setAltitude(number)  Sets camera altitude to given value (in meters)
 getAltitude() : number  
 setHeading(number)  Sets camera heading (in degrees); 0 - North, 90 - West, 180 - South, ...
 getHeading() : number  
 setTilt(number)  Sets camera tilt (in degrees); 0 - Looking down, 90 - Along the horizon, 180 - Up
 getTilt() : number  
 setRoll(number)  Sets camera roll (in degrees)
 getRoll()  
setZoom(number) Set the zoom level of the Earth in Mercator tiles at given level 
getZoom() : number Return the actual zoom level (real number)
 flyTo(lat:number, lng:number, alt:number?, heading:number?, tilt:number?)  Starts the fly-to animation from current position to the given coordinates.
 flyToFitBounds(minlat:number, maxlat:number, minlon:number, maxlon:number)  Starts the fly-to animation to the position from where the given bounds can be observed.
 initMap(type:WebGLEarth.Maps, args?:{...})  Initializes new map. type can be one of the following:

WebGLEarth.Maps.OSM - OpenStreetMap
WebGLEarth.Maps.MAPQUEST - MapQuest OSM
WebGLEarth.Maps.BING - MS Bing (needs initialization with your own key)
WebGLEarth.Maps.WMS
 WebGLEarth.Maps.CUSTOM

You can find more information about arguments you have to supply in order to properly initialize different Map types in our API examples.
 setMap(type:WebGLEarth.Maps, id?)  Deprecated, use setBaseMap()
setBaseMap(map:WebGLEarth.Map) Sets given map as active base layer.
setOverlayMap(map:WebGLEarth.Map?) Sets given map as active overlay layer. Pass null to disable overlay layer.
 handleResize()  Call this method if you resize the containing div element.
 on(type:string, function(event)) : number?  Registers function to be called when certain event occurs. Passed argument is standard browser event object plus latitude and longitude:

var showInfo = function(e) {
  alert(e.latitude + ', ' + e.longitude);
  alert('at ' + e.screenX + ', ' + e.screenY);
}
app.on('click', showInfo);

This function returns the listen key which can be used to unregister the listener.
 off(type:string, function(event))  Unregister event listener using the same paramaters that were used during registration.
 off(key:number)  Unregister event listener using the listen key.
 offAll(type:string)  Unregister all event listeners of the given type.
 initMarker(lat:number, lng:number, iconUrl:string?, width:number?, height:number?) : WebGLEarth.Marker  Creates new marker at given position. You can also pass Url of custom image and it's dimensions.


WebGLEarth.Map object

This object can be constructed via WebGLEarth.initMap() method.

 setBoundingBox(minlat:number, maxlat:number, minlon:number, maxlon:number)  Sets bounding box of this map. Tiles outside this bounds won't be downloaded.
 setOpacity(number)  Sets opacity of this map. (1 - Fully opaque, 0 - Fully transparent)
 getOpacity() : number  


WebGLEarth.Marker object

This object can be constructed via WebGLEarth.initMarker() method.

 setPosition(lat:number, lng:number)  Sets new position for the marker.
 bindPopup(content:string, maxWidth:number?, closeBtn:boolean?)  Creates new popup attached to this marker with HTML code specified in content. You can also set different maxWidth (default is 300px) and disable close button by passing false as the third argument.
 openPopup()  Opens the popup if not already opened.
 closePopup()  Closes the popup if not already closed.
 on(type:string, function(event)) : number?  Registers function to be called when certain event occurs. Passed argument is standard browser event object plus latitude and longitude of this marker.

var showInfo = function(e) {
  alert('You clicked at ' + e.latitude + ',' + e.longitude);
  alert('Relative coords: ' + e.offsetX + ',' + e.offsetY);
}
marker.on(click, showInfo);
 off(type:string, function(event))  Unregister event listener using the same paramaters that were used during registration.
 off(key:number)  Unregister event listener using the listen key.
 offAll(type:string)  Unregister all event listeners of the given type.

Comments