Poly9 FreeEarth API
We are releasing this API in its quite experimental state, so there might be bugs and missing functionalities that are common to other APIs.
Here's a simple example displaying a map centered on Quebec City, Canada
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function onMapLoad() {
this.setTargetLatLng(new FE.LatLng(46.813689,-71.216812));
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 800px; height: 600px"></div>
</body>
</html>
As with many JavaScript APIs, you need to include a JavaScript file in your page (located at http://freeearth.poly9.com/api.js ). There is no API key for the moment.
The JavaScript class that represents a map is FE.Map. This class represents a single map on the page. Its constructor needs a container id (or the container itself) so that the map can be embedded in the DOM. Once the class object is instantiated, preferably in the onload event of your page, you must call its load() method. You may override the object's onLoad method so provide custom behavior once the map is fully initialized.
FreeEarth requires Adobe Flash Player 9, preferably the latest version (9,0,45,0 as of this writing).
If an earlier version is detected, an upgrade is suggested to the user. The upgrade procedure is seamless.
The following example displays a map and pans to a random point.
The panTo(location, time, transition) method centers the map at a given location. The time parameter is
optional (defaults to 1) and specify the length of the panning animation in seconds. The transition is an optional (lowercase) string that
specifies the easing effect to use. Visit Robert Penner's website to experiment with various easing functions.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
var map;
var easeFunctions = ['easenone', 'easeinquad', 'easeincubic', 'easeinexpo', 'easeoutelastic'];
function randomMapPan() {
var ll = map.getTargetLatLng();
ll.lat += (Math.random() * 10) - 10;
ll.lng += (Math.random() * 360) - 180;
var delay = Math.random() * 2000;
delay += 500;
map.panTo(ll, delay/1000, easeFunctions[Math.floor(Math.random() * easeFunctions.length)]);
_timeout = setTimeout(randomMapPan, delay + 500);
}
function onMapLoad() {
this.toggleAtmosphere();
setTimeout(randomMapPan, 0);
}
function load() {
map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 500px; height: 300px"></div>
</body>
</html>
The following example creates a map and displays flags for a number of countries in the world. The icons are from famfamfam and were geocoded using the Yahoo geocoding API
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript" src="http://freeearth.poly9.com/countries.js"></script>
<script type="text/javascript">
//<![CDATA[
function createOnClick(country) {
return function(marker) {
marker.openInfoWindowHtml('Hello from ' + country + '!', 200, 32);
}
}
function onMapLoad() {
// The countries variable is defined in countries.js
for(var i=0; i<countries.length && i < 10; ++i) {
var code = countries[i][0];
var icon = new FE.Icon('http://s3.amazonaws.com/freeearth/' + code + '.png');
var marker = new FE.Pushpin(new FE.LatLng(countries[i][1], countries[i][2]), icon);
FE.Event.addListener(marker, 'click', createOnClick(countries[i][3]));
this.addOverlay(marker);
}
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 500px; height: 300px"></div>
</body>
</html>
View example (world_flags.php)
This one displays a pushpin on Quebec city with a camera icon and plays a video in the infowindow
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function onCameraClick(marker) {
var url = 'http://s3.amazonaws.com/freeearth/moon.flv';
var window = marker.openInfoWindowFlv(url, 213, 160);
window.startFLV();
}
function onMapLoad() {
var cameraIcon = new FE.Icon('http://freeearth.poly9.com/images/camera.png');
var qc = new FE.LatLng(46.82614,-71.289597);
this.panTo(qc, 3, 'easeoutelastic');
var marker = new FE.Pushpin(qc, cameraIcon);
FE.Event.addListener(marker, 'click', onCameraClick);
this.addOverlay(marker);
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 500px; height: 300px"></div>
</body>
</html>
Here is how we display a GeoRSS feed from Flickr on FreeEarth. It's also possible to customize the behavior by overriding the FE.GeoRSS.itemHandler method.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function onMapLoad() {
var rss = new FE.GeoRSS('http://api.flickr.com/services/feeds/groups_pool.gne?id=322338@N20&format=rss_200&georss=1');
this.addOverlay(rss);
this.panTo(new FE.LatLng(40, -100));
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 800px; height: 600px"></div>
</body>
</html>
View example (mapufacture.php)
The following example will add some labels to show country names
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript" src="http://freeearth.poly9.com/countries.js"></script>
<script type="text/javascript">
//<![CDATA[
function onMapLoad() {
// The countries variable is defined in countries.js
for(var i=0; i<countries.length && i < 50; ++i) {
var code = countries[i][0];
var label = new FE.Label(new FE.LatLng(countries[i][1], countries[i][2]), countries[i][3]);
this.addOverlay(label);
}
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 800px; height: 600px"></div>
</body>
</html>
This example shows a GPS route.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function onMapLoad() {
var km = 1000;
var pts = "12.603442,46.035478,0 12.599182,46.032803,0 12.586162,46.024627,0 12.579764,46.010664,0 12.536251,45.952921,0 12.52834,45.914427,0 12.504606,45.871807,0 12.480872,45.829188,0 12.459116,45.78794400000001,0 12.453182,45.765947,0 12.425492,45.74257500000001,0 12.37209,45.73020200000001,0 12.285065,45.70408,0 12.207929,45.70408,0 12.134749,45.726077,0 12.059591,45.748074,0 12.014101,45.759073,0 11.887519,45.750824,0 11.814339,45.756323,0 11.756981,45.767322,0 11.69369,45.764572,0 11.654133,45.752199,0 11.616554,45.713704,0 11.582931,45.67933300000001,0 11.527551,45.64633800000001,0 11.521618,45.614717,0 11.521618,45.610593,0 11.523595,45.603719,0 11.527551,45.596845,0 11.529529,45.591345,0 11.531507,45.585846,0 11.529152,45.58122000000001,0 11.529529,45.576222,0".split(/\s+/);
var latlngs = [];
for(var i=0; i<pts.length; i++) {
var coords = pts[i].split(',');
latlngs.push(new FE.LatLng(coords[1], coords[0]));
}
var polyline = new FE.Polyline(latlngs, 'yellow');
this.addOverlay(polyline);
this.setTargetLatLng(latlngs[0]);
var lm = this.getLayerManager();
this.setAltitude(335 * km);
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 640px; height: 480px"></div>
</body>
</html>
You may also use polylines to display great circle lines. This example shows a great circle line between the MIA and CDG airports.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function onMapLoad() {
var planeIcon = new FE.Icon('http://freeearth.poly9.com/images/ico_plane.gif');
var start = new FE.LatLng(25.795235,-80.267186);
var end = new FE.LatLng(49.014568,2.565823);
var airline = new FE.Polyline([start, end]);
var opts = new FE.LabelOpts();
opts.fontName = 'Verdana';
opts.setColor('yellow');
opts.fontSize = 16;
var mia = new FE.Label(start, 'MIA', opts);
var cdg = new FE.Label(end, 'CDG', opts);
var plane = new FE.Pushpin(start, planeIcon);
this.addOverlay(plane);
this.addOverlay(mia);
this.addOverlay(cdg);
this.addOverlay(airline);
this.setTargetLatLng(start);
this.panTo(end, 5, "linear");
plane.followPolyline(airline, 5);
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 640px; height: 480px"></div>
</body>
</html>
You can embed custom image overlays using FreeEarth
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
FE.Transport.disableProxy();
function onMapLoad() {
var lm = this.getLayerManager();
var north = 37.91904192681665;
var south = 37.46543388598137;
var east = 15.35832653742206;
var west = 14.60128369746704;
var km = 1000;
var etnaBounds = new FE.LatLngBounds(new FE.LatLng(north, east), new FE.LatLng(south, west));
var etnaLayer = new FE.Layer.Globe('etna', etnaBounds, 'http://freeearth.poly9.com/images/etna.jpg');
lm.addLayer(etnaLayer);
this.setTargetLatLng(etnaBounds.getCenter());
this.zoomTo(150 * km, 5);
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 800px; height: 600px"></div>
</body>
</html>
There are two ways to display a WMS layer in FreeEarth: tiled and untiled. Here is a sample showing a tiled WMS source.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function onMapLoad() {
var lm = this.getLayerManager();
var wms = new FE.Layer.WMS('vmap0', 'http://labs.metacarta.com/wms/vmap0?', ['basic'], {});
lm.addLayer(wms);
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 800px; height: 600px"></div>
</body>
</html>
The following example shows how to use an untiled WMS layer. This is useful to display layers with labels or to reduce the load on the server.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function onMapLoad() {
var lm = this.getLayerManager();
var wms = new FE.Layer.UntiledWMS('vmap0', 'http://labs.metacarta.com/wms/vmap0?', ['basic'], {});
lm.addLayer(wms);
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 800px; height: 600px"></div>
</body>
</html>
View example (untiled-wms.php)
This special layer uses Fourmilab's Earth and Moon Viewer to display the day/night terminator. It is updated every 5 minutes.
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function onMapLoad() {
this.getLayerManager().addLayer(new FE.Layer.DayNight());
this.setTargetLatLng(new FE.LatLng(46.813689,-71.216812));
}
function load() {
var options = { includeBaseLayers : false };
var map = new FE.Map(document.getElementById("map"), options);
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 800px; height: 600px"></div>
</body>
</html>
If you need to display FLV videos in an infowindow, you can use the specialized FE.FLVInfoWindow class like this:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
var flvInfoWindow;
var flvURL = 'http://freeearth.poly9.com/moon.flv';
var qc = new FE.LatLng(46.814511,-71.215096);
function onPlay() {
alert('Video started');
}
function onStop() {
alert('Video stopped');
}
function onMapLoad() {
flvInfoWindow = this.openInfoWindowFlv(qc, flvURL, 320, 200);
flvInfoWindow.setBufferLength(10);
flvInfoWindow.addListener('FLV_PLAY', onPlay);
flvInfoWindow.addListener('FLV_STOP', onStop);
flvInfoWindow.addListener('FLV_RESUME', onPlay);
}
function load() {
var map = new FE.Map(document.getElementById("map"));
map.onLoad = onMapLoad;
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 800px; height: 600px"></div>
<span>
<a href="javascript:;" onclick="flvInfoWindow.startFLV()">start</a>
<a href="javascript:;" onclick="flvInfoWindow.pauseFLV()">pause</a>
<a href="javascript:;" onclick="flvInfoWindow.resumeFLV()">resume</a>
<a href="javascript:;" onclick="flvInfoWindow.seekFLV(10)">seek</a>
</span>
</body>
</html>
Some celestial bodies are available in FreeEarth: Earth's Moon, Mars, Venus, Mercury, Jupiter, Saturn, Uranus, Neptune, Pluto and the Sun. One can summon the sun with the following incantation:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8"/>
<title>FreeEarth Javascript API Example</title>
<script type="text/javascript" src="http://freeearth.poly9.com/api.js"></script>
<script type="text/javascript">
//<![CDATA[
function load() {
var map = new FE.Sun(document.getElementById("map"));
map.load();
}
//]]>
</script>
</head>
<body onload="load()">
<div id="map" style="width: 500px; height: 300px"></div>
</body>
</html>
Q: What to do in order to style text in the info balloon? In particular, to have blue, underlined <a> elements?
A: HTML passed to openInfoWindowHtml can be styled according to this guide. Note that links are not blue nor underlined by default. To display standard looking links, you would use the following snippet:
FreeEarth is now using the browser's HTML rendering engine in the infowindows, so you can embed any HTML tags (even a Flash/Java applet) in your infowindow.