bioneural.net

Geo Mashup is one of my favourite WordPress plug-ins (and no, that's not just because it adopted the Geotag Icon). It neatly integrates geographically-relevant blog posts with a custom Google Map displayed within your own site. The Maps API in turn allows those willing to dirty their hands with a little JavaScript the option to pull in geotagged content from external sources, including photos (e.g. from Flickr, Panoramio, Picasa Web Albums), content from other blogs (via GeoRSS feeds), and placemarks from Google Earth (uploaded KML/ KMZ files, even with network links). What follows is an implementation guide, sharing some usage tips and the code used on bioneural.net.

The code given here applies to Geo Mashup 1.1.1 and WordPress 2.6.2.

Geo Mashup 1.2 was released on 19.03.09. Some of the code here may require modification.

Installing the plugin

Download Geo Mashup here, expand the ZIP archive and upload the geo-mashup directory to /wp-content/plugins/ on your web server.

Log in to WordPress as Administrator and activate Geo Mashup from the Plugins tab. Once active there will be a new Geo Mashup tab under Settings, and you'll need to visit this to enter your Google Maps API key (if you don't yet have one, click the Get yours here link). Don't worry about the other options at this stage.

Creating a map page

The tag reference gives you the choice of two types of tag to use with Geo Mashup. Shortcode tags are added to posts or pages on a case-by-case basis. Template tags on the other hand involve adding the tag once to your theme templates, and having the same result output automatically across many pages (depending on where they are used). Either type of tag can accept optional parameters.

I prefer to use template tags because they are more consistent (always appearing in the same place), more flexible in combination with XHTML/ PHP (see below), and allow better integration of plugin output with your theme (e.g. you can do away with the sidebar to allow for displaying a wider map). To this end I created a new file called page-gmap.php in BBEdit based on the default page template for my theme (derived from K2), like so:

<?php /*
	Template Name: Google Maps Mashup 1.0
*/ ?>

<?php get_header(); ?>

<div class="content">
	<div id="primary">
		<div id="notices"></div>

		<div id="current-content" class="hfeed">

			<?php the_post(); ?>

			<div id="post-<?php the_ID(); ?>" class="<?php k2_post_class(); ?>">
				<!--more-->
				<div class="entry-content" style="width: 720px;">
					<?php echo GeoMashup::map('height=500&width=720&add_overview_control=0&add_map_type_control=0&map_type=G_PHYSICAL_MAP&auto_open_info_window=1'); ?>
				</div> <!-- .entry-content -->

			</div> <!-- #post-ID -->

		</div> <!-- #current-content .hfeed -->

		<div id="dynamic-content"></div>
	</div> <!-- #primary -->

</div> <!-- .content -->

<?php get_footer(); ?>

Perhaps it looks scarier than it really is if you're not used to template editing? In any case the only bit that directly pertains to Geo Masup is the one line containing the GeoMashup::map() PHP statement, so focus on that! Here's what the parameters I've chosen dictate:

Parameter	Value
height	Map height set to 500px
width	Map width set to 720px
add_overview_control	Don't show the overview map (0 = false)
add_map_type_control	Don't let users change map type (0 = false)
map_type	G_PHYSICAL_MAP corresponds to the terrain map
auto_open_info_window	Show the info window corresponding to the originating post (1 = true)

Feel free to make your own default choices. Save the file and upload it into your theme directory.

To link a navigation tab to this template, in WP Admin go to Write > Page and enter "Map" (or similar) as the Title. Scroll down to the Page Template section and choose the page template you just made above, then Save. Now when you click the Map tab it should load your custom template rather than the default page template:

Adding coordinates to your posts

When you edit a post there should now be a new Locations section; clicking the disclosure triangle will reveal a Google Map you can use to geotag your post. There are a number of ways you can do this:

• Enter a place name into Find location (e.g. "Wellington, New Zealand" or just "Wellington" if you want to click on the correct one from a selection of results);
• Enter an address as you would in Google Maps into Find location (e.g. "10 downing street, london");
• Enter GPS lat/ long cordinates into Find location (e.g. "58.03,-5.06");
• Click on the map (using the zoom tool and re-clicking or dragging to refine your marker position);
• Choose a previously stored position from Saved locations;
• Upload a Google Earth placemark as a KML attachment (click Add Media—although this won't work for me).

Save the post to publish/ re-publish your geotagged post.

I often get the coordinates for a post from a geotagged photo. In OS X open the image in Preview, open the Inspector and click the Locate button then copy the cooridnates from the info window that opens in Google Maps.

Linking posts to your map page

So you now have a map page and at least one geotagged post—we need to get them hooked up. The following template tag creates a "show on map" link within a geotagged post:

<?php echo GeoMashup::show_on_map_link(); ?>

This tag accepts parameters to change the link text and turn off display of the Geotag Icon. The default output looks like this:

It's easy and effective, and may be all you need. I had three additional requirements:

1. The Geotag Icon should be visible as an image overlay on a category icon;
2. The GPS coordinates used to mark the post location should be displayed in the post footer;
3. The PHP for Geo Mashup should be read only when the plugin is active (to avoid a fatal error when it is inactive).

I use the Geotag Icon as an image overlay on a category icon image as this makes it easier to spot geotagged posts when reading the post title and especially when browsing trimmed archives:

You can get the Category Icons plug-in here (but you don't need it to use the Geotag Icon as an image-only map link). In the loop insert the following code just before the post title (called with the_title()—I can't show you exactly where to put it as your theme is different to mine, so experiment!):

<div class="catimage">
   <?php if (function_exists('get_cat_icon')) get_cat_icon(); ?>
   <span class="geotag-overlay"><?php if (function_exists('geo_mashup_map')) echo GeoMashup::show_on_map_link('text=&show_icon=1'); ?></span>
</div>

The Geotag Icon overlay will only be inserted if the post is geotagged and if the Geo Mashup plug-in is activated (the third requirement); if the plugin is inactive without function_exists you'll get a fatal error (I gather it's considered good practice to ensure your template code holds together if plug-ins are deactivated). The parameter values chosen for show_on_map_link are:

Parameter	Value
text	No value (no text is shown, overriding the default of "Show on map")
show_icon	Show the Geotag Icon (1 = true)

Now, add the following CSS to your stylesheet to move your overlay into position:

.geotag-overlay { margin-left: -16px; }

All being well you should see something like this:

The second requirement was to display the coordinates at the foot of the post. I put them into an "Actions" box so they appear like this:

This feature is created with the following template code in the WordPress loop:

<?php if (function_exists('geo_mashup_map')) $coords = GeoMashup::post_coordinates(); if ($coords) { echo '<span class="geotag">' . GeoMashup::show_on_map_link('text=View&show_icon=0') . ' on map' . ' (geotagged at lat ' . $coords['lat'] . ', lng ' . $coords['lng'] . ')' . '</span>'; } ?>

With the following CSS in your stylesheet:

.geotag { display: block; padding: 2px 0 2px 20px; background: url('geotag-16px.png') left center no-repeat; }

Alternative uses for coordinate values

Although designed to get coordinates to Google Maps, you can harness the power of Geo Mashup to do more creative things with the coordinates attached to each post. For example, you might include an action that creates a waypoint in RouteBuddy (if installed):

<?php if (function_exists('geo_mashup_map')) $coords = GeoMashup::post_coordinates(); if ($coords) { echo '<span class="routebuddy"><a href="rbud://view?&amp;lat=' . $coords['lat'] . '&amp;lon=' . $coords['lng'] . '&amp;zoom=4">Create</a> a waypoint in RouteBuddy' . '</span>'; } ?>

With the following CSS in your stylesheet:

.routebuddy { display: block; padding: 2px 0 2px 20px; background: url('routebuddy-16px.png') left center no-repeat; }

The action should look like this:

Clicking the link will launch RouteBuddy and pre-fill the waypoint editor with the latitude and longitude supplied by Geo Mashup:

Update 23.01.09: See here for instructions on how to find nearby images in CDFinder via your website.

Inherit WordPress styles in your map page

In the current version of Geo Mashup your map sits inside an iFrame, meaning it does not inherit the CSS styles your are using in association with your WordPress theme. It is possible to create a custom stylesheet inside the /plugins/geo-mashup/ directory called map-style.css, containing CSS specific to the info windows for your map. I suggest creating the file, but giving it the following content (making sure the path matches that of your theme stylesheet):

@import url('http://www.mysite.com/wp-content/themes/mytheme/style.css');

This effectively tells Geo Mashup to use the same stylesheet that your blog uses (so it looks better integrated), and keeps all of your CSS in the one place. You can still add CSS specific to Geo Mashup to your theme stylesheet. For example:

.locationinfo { overflow: hidden; height: 100px; width: 220px; text-align: left; } /* Info window */
.locationinfo h2 { font-size: 1.2em; font-weight: bold; background: url('geotag-16px.png') left center no-repeat; text-align: left; padding: 2px 0 2px 20px !important; }
.meta { display: none; }
.storycontent { font-size: 1em; line-height: 1.5em; } /* Info window */

Toggle display of posts by category

Geo Mashup does provide a template tag for showing a map legend:

<?php echo GeoMashup::category_legend(); ?>

However, we can extend the functionality of the legend so that it toggles the display of posts by category, with each category having an appropriate centre and zoom level. For this to work it will be necessary to assign colours to specific categories in Settings > Geo Mashup so that our key matches the marker colour of the displayed category. We can then attach hyperlinks to marker icons that pass several parameters to our map:

Parameter	Value
lat	Centre the map on a given latitude (e.g. "-41.2")
lng	Centre the map on a given longitude (e.g. "174.7")
map_cat	Display posts within a given category (e.g. "15"), or omit to display all and reset the map
zoom	Specify the level of zoom on the map centre (e.g. "7")

For example, you might add the following to page-gmap.php underneath the GeoMashup::map() PHP statement:

<p>Key/toggle: <img src="../images/mm_20_red.png" alt="red" /> <a href="http://www.bioneural.net/map/?lat=-41.2&amp;lng=174.7&amp;map_cat=8&amp;zoom=2">Travel</a>,
<img src="../images/mm_20_silver.png" alt="silver" /> <a href="http://www.bioneural.net/map/?lat=-41.2&amp;lng=174.7&amp;map_cat=10&amp;zoom=7">New Zealand</a>,
<img src="../images/mm_20_yellow.png" alt="yellow" /> <a href="http://www.bioneural.net/map/?lat=-41.2&amp;lng=174.7&amp;map_cat=9&amp;zoom=2">Photography</a>,
<img src="../images/mm_20_green.png" alt="green" /> <a href="http://www.bioneural.net/map/?lat=-41.2&amp;lng=174.7&amp;map_cat=15&amp;zoom=7">Project Koru</a>,
<img src="../images/mm_20_aqua.png" alt="aqua" /> Other.
<a href="http://www.bioneural.net/map/?lat=-41.2&amp;lng=174.7&amp;zoom=2">Reset</a>/show all.</p>

The parameters passed in these links will override the default map centre/ zoom level we defined in the map page template. Our legend will look something like this, and clicking the category name will change our view of the map:

If you want to vary the zoom by category note that this will only work if you have not set a default zoom in your map page template tag or in custom.js (see below) using setCenter.

Overlaying external content

Geo Mashup uses GGeoXml (part of the Google Maps API) to load data from KML/ KMZ or GeoRSS source files (credit to Kristoffer Cannon for this know-how).

Note that if a custom icon is not specified in a feed you intent to overlay, the default big blue placemark icon will be used. You cannot modify this (except by specifying an alternative in the feed—which may be beyond your control), although this is set to change.

The "mash up" potential of GGeoXml can't be overstated. It's worth looking at several examples that demonstrate how to overlay:

• geotagged content from other blogs;
• geodata from uploaded KML/ KMZ files;
• photos from Flickr;
• photos from Picasa Web Albums;
• photos from Panoramio;
• videos from YouTube;
• geographic databases using network links (e.g. Wikipedia articles).

Overlay geotagged content from other blogs

If your friends are already using Geo Mashup (or an alternative, like GeoPress) then they can provide you with a GeoRSS feed (here's mine). For more information about GeoRSS feeds in WordPress see here. To overlay content from a spatially-aware blog on your map (or elsewhere), you first need to create a file called custom.js in plugins/geo-mashup/ (rename and use the template provided as custom-sample.js). The code blocks in the following examples all go inside the customizeGeoMashup() function, as denoted by the following:

function customizeGeoMashup(mashup) {

CODE BLOCK GOES HERE

}

For the first example, the code block creates a variable called geoXmlBioneural, which is used to create an instance of GGeoXml that will load data from the feed URL inside the brackets. We then overlay these data as a new "layer" on our map:

var geoXmlBioneural;
geoXmlBioneural = new GGeoXml("http://www.bioneural.net/tag/geotag/?feed=rss2");
GeoMashup.map.addOverlay(geoXmlBioneural);

Here's how posts from another Geo Mashup user appear (Cyberhobo, the plugin developer):

Overlay geodata from uploaded KML/ KMZ files

You might have a pre-existing file you exported from Google Earth or output from your data logger that you want to upload and display. For example, you could convert a GPX track log to KML and your track will be displayed as a map overlay. Alternatively you could create your own KML file from scratch, specifying a custom icon (full path) and placemark names/ descriptions. For example:

<?xml version="1.0" encoding="UTF-8"?>
<kml xmlns="http://earth.google.com/kml/2.2">
	<Style id="kiwi">
		<IconStyle>
			<scale>1</scale>
			<Icon>
				<href>../kiwi-yellow-32px.png</href>
			</Icon>
		</IconStyle>
	</Style>
	<Placemark>
		<name>Italy</name>
		<description>We visited here in 1996.</description>
		<styleUrl>#kiwi</styleUrl>
		<Point>
			<coordinates>12.482324,41.895466</coordinates>
		</Point>
	</Placemark>
</kml>

Make sure the URL is the full path to the file on your server when you create the code block in custom.js:

var geoXmlVisitedCountries;
geoXmlVisitedCountries = new GGeoXml("http://www.bioneural.net/docs/visited.kml");
GeoMashup.map.addOverlay(geoXmlVisitedCountries);

Here's the output from the above example:

Overlay photos from Flickr

If you use Flickr Map to geotag your photos on Flickr (or upload them with geotags in EXIF or otherwise via the Flickr API) you can use one of several URL syntax's to overlay them on your Google Map. Go to your Photostream and look for the following links:

You can either:

• Append &georss=1 to your user ID using the "Latest" link for GeoRSS format as here (shows a big blue placemark icon);
• Copy the geoFeed link for GeoRSS format as here (shows a big blue placemark icon);
• Copy the KML link for KML format as here (shows image thumbnails).

For example, on my map page this code:

var geoXmlFlickr;
geoXmlFlickr = new GGeoXml("http://api.flickr.com/services/feeds/geo/?id=31017329@N00&lang=en-us&format=rss_200");
GeoMashup.map.addOverlay(geoXmlFlickr);

Will render this:

Overlay photos from Picasa Web Albums

Picasa Web Albums from Google allows you to manually add geotags to your photos, or map them automatically if the data are already present in EXIF (make sure Use Exif location information is checked in Settings). The following example shows how you might embed an album from PWA into custom.js:

var geoXmlPicasa;
geoXmlPicasa = new GGeoXml("http://picasaweb.google.com/data/feed/base/user/your.google.id/albumid/5247382552576513665?alt=rss&kind=photo&authkey=MsfAzUybdRc&hl=en_US");
GeoMashup.map.addOverlay(geoXmlPicasa);

Note that the alt parameter in the example URL above can have one of two values—either rss for RSS or kml for KML format. You'll need to copy the relevant URL from your album page:

If you use RSS your photos will be marked with a big blue placemark icon (as per the Flickr example); if you use KML they will be marked by thumbnail icons on your map:

Overlay photos from Panoramio

Panoramio from Google allows you to manually add geotags to your photos, or map them automatically if the data are already present in EXIF. The following example shows how you might embed an album from PWA into custom.js:

var geoXmlPanoramio;
geoXmlPanoramio = new GGeoXml("http://www.panoramio.com/kml/?user=6319");
GeoMashup.map.addOverlay(geoXmlPanoramio);

In this example you would see geotagged photos by Craig Stanton. Copy the link underneath your Panoramio user name:

KML format is the only choice, and your images will be marked by thumbnails on your map:

Alternatively, you could use this link to overlay a selection of photos popular on Panoramio:

http://www.panoramio.com/kml.php

Overlay videos from YouTube

There's a tutorial on embedding YouTube videos into Google's My Maps and Google Earth here. Following the tutorial, create a placemark in Google Earth and copy the syntax for embedding your YouTube video into the Description field (you can optionally change the placemark icon too). After clicking OK right-click on your new placemark and choose Save Place As to create a KMZ file. Upload this file to your server and enter the full path to it when you define the new GGeoXml:

var geoXmlYouTube;
geoXmlYouTube = new GGeoXml("http://www.bioneural.net/docs/Iguazu.kmz");
GeoMashup.map.addOverlay(geoXmlYouTube);

Unfortunately I could not get the embedded YouTube video to show (it is supposed to work on Mac with GE 4.3+, which I was using):

Other examples using network links

Network links mean that a KML file doesn't have to contain the data, but can fetch it from elsewhere (in fact that's exactly what is happening when you overlay photos from Panoramio, for example). This implies the potential to map all kinds of geographically-relevant information—not just a bunch of photos. Here are a couple of examples that illustrate the type of data you might overlay (your map could get rather busy!). GeoNames collate a huge database of geographical names and features, which you could access like this:

var geoXmlGeonames;
geoXmlGeonames = new GGeoXml("http://www.geonames.org/kml/feature-networklink.kml");
GeoMashup.map.addOverlay(geoXmlGeonames);

Your own markers might get swamped:

If you were interested in just one feature set (e.g. hydrographic features), download the KML and edit out all but the network link of interest, then upload the revised KML file to your server and link to it as per the YouTube example.

What about marking Wikipedia articles on your current map view? No problem:

var geoXmlWikipedia;
geoXmlWikipedia = new GGeoXml("http://toolserver.org/~kolossos/geoworld/WP-world-maps.php?lang=en");
GeoMashup.map.addOverlay(geoXmlWikipedia);

Bear in mind, however, that adding in a large database as in these examples (or data from multiple sources) will slow things down, and zillions of placemarks may take a while to appear on your map:

What we need is a way to actively enable such overlays with the flick of a switch, preventing them from loading by default...

Toggle the display of external content

With the following modifications to our Flickr example above, photos from Flickr will not be created as a map overlay by default:

if (GeoMashup.opts.load_flickr && confirm('Overlay geotagged photos from Bruce\'s Flickr feed?')) {
	var geoXmlFlickr;
	geoXmlFlickr = new GGeoXml("http://api.flickr.com/services/feeds/geo/?id=31017329@N00&lang=en-us&format=rss_200");
	GeoMashup.map.addOverlay(geoXmlFlickr);
}

We also need to create a toggle that tells Geo Mashup that load_flickr is true (i.e. =1), which we can do in our map page template like this:

<img src="../flickr.png" alt="flickr" /> <a href="http://www.bioneural.net/map/?lat=53.2&amp;lng=-1.4&amp;zoom=5&amp;load_flickr=1">Flickr</a> overlay.

When a user clicks on the toggle a JavaScript confirmation alert will open. If they choose Cancel the images from Flickr will not be shown; if they choose OK they will be shown:

Integrating the Google Earth plug-in

Update 04.12.08:

Google announced the release of the Google Earth Browser Plugin for Mac today. Users who have installed the plug-in can view a 3D version of your Google Map with the addition of a new map type to your custom.js Geo Mashup file:

//Add support for Google Earth plug-in
mashup.map.addMapType(G_SATELLITE_3D_MAP);
mashup.map.addControl(new GHierarchicalMapTypeControl());

Note that the second line, the map type control, is required only if you have not specified a map type control via your map template (using add_map_type_control) or via checking Add Map Type Control in the Geo Mashup plug-in options.

Integrating Google Street View

Update 06.12.08:

Google Street View comprises street-level panoramic photographs. Users who have installed the Flash Player plug-in can take virtual tours through your favourite city with the addition of the following example code to your custom.js Geo Mashup file:

//Street View for Wellington
if (GeoMashup.opts.load_svWelly && confirm('Take a virtual street tour of Wellington NZ?\n(Google Street View requires the Flash plugin)')) {
	var streetView = new GLatLng(-41.286,174.776);
	panoramaOptions = { latlng:streetView };
	var svWelly = new GStreetviewPanorama(document.getElementById("geoMashup"), panoramaOptions);
}

We also need to create a toggle that tells Geo Mashup that load_svWelly is true (i.e. =1), which we can do in our map page template like this:

<img src="../street_view.png" alt="Street View" /> <a href="http://www.bioneural.net/map/?lat=-41.286&amp;lng=174.776&amp;zoom=14&amp;load_svWelly=1">Wellington</a> Street View.

When a user clicks on the toggle a JavaScript confirmation alert will open. If they choose Cancel they will see the default map; if they choose OK the map will be replaced by Google Street View:

Update 10.03.09:

You can use Geo Mashup to locate Twitter users within a given radius of your post location (20km in this example):

<?php if (function_exists('geo_mashup_map')) $coords = GeoMashup::post_coordinates(); if ($coords) { echo '<span class="twitter"><a href="http://search.twitter.com/search?q=near%3A' . $coords['lat'] . ',' . $coords['lng'] . '&amp;within=20&amp;units=km">Find</a> nearby people using Twitter' . '</span>'; } ?>

Update 15.03.09:

Even more Twitter + Geo Mashup integration here.