Google Maps Platform: TimeMap: Helping you add the 4th dimension to your maps

Maps Platform

Product updates, customer stories, and tips and tricks on Google Maps Platform

TimeMap: Helping you add the 4th dimension to your maps

Thursday, January 29, 2009

Posted by Nick Rabinowitz, UC Berkeley
Hi, I'm Nick Rabinowitz, guest poster. I'm a grad student at the UC Berkeley School of Information and the creator of TimeMap, a Javascript library that helps the Google Maps API play nicely with the SIMILE Timeline API to create maps and timelines that work together. Readers of the Google LatLong blog may have seen TimeMap in action already, in the Maps API's 3rd birthday post. That post promised an eventual technical explanation of how to make such map-timeline mashups. Well, exhale your bated breath: Here it is!
TimeMap in Theory:
The basic idea of TimeMap is to wrap both the Google Maps API and SIMILE Timeline in a third API in order to control interactions between a map and a timeline on the page. The "wrapping" happens via a set of Javascript objects that hold references:

TimeMap: The TimeMap object has references to the GMap2 object (as "map") and the Timeline object (as "timeline"), which you can access directly (e.g. myTimeMap.map.zoomIn()). It also has an array of TimeMapDataset objects.

TimeMapDataset: A TimeMapDataset object holds an array of TimeMapItems.

TimeMapItem: A TimeMapItem has references to a placemark (on the map) and an event (on the timeline). Calling methods on the item allows it to control the placemark and event so they work in sync.

This tiered structure of references means we can set functions or event listeners on one object that make things happen in another - e.g. hiding placemarks on the map when their associated event scrolls out of view on the timeline, or opening a map info window when the corresponding timeline item is clicked. It also means that you can set cascading options on the whole TimeMap, a single dataset, or a single item - for example, you can set a theme on a dataset so that all its items display the same way.

The other big thing the library does is handle initialization. The timemapInit() function lets you create your TimeMap and load your data in a single function call, setting all the parameters in JSON. To make this really flexible, it supports a bunch of pluggable function hooks. For example, there's a default openInfoWindow() function called when you click the placemark or the event - but you can write your own function (e.g. to use ExtInfoWindow) and set it on a per-dataset or per-item basis.
TimeMap in Action:
The library includes a lot of helper functions to help you set up your own TimeMap. You can load data as inline JSON, remote JSON, or KML (with TimeStamp and TimeSpan elements). Click the screenshots below for examples of each of those: