Mapnificent API Documentation

About

Mapnificent provides dynamic public transport travel time maps for many cities in the US and some world wide. You can use the Mapnificent API to augment your Google Maps application (using the Google Maps API v3) with public transport travel time overlays. Please notice and adhere to the API Terms of Use.

Overview

If you want to jump right in, checkout the API example and its commented source code.

The Mapnificent API is a pure JavaScript API. You include a script, create a Mapnificent instance, connect it to your map, control it via method calls and get notified via events.

The jQuery object must be present on your site for Mapnificent to work. If you don't already use jQuery, you must include it before Mapnificent. You can use the "no conflict" mode of jQuery to avoid name clashes with $.

Note: Mapnificent will create multiple script tags for loading data and a hidden iframe on your page. This is because Web Workers cannot be called across domains. Your site must therefore communicate with the iframe via cross domain message passing and the iframe will handle the worker. This is transparent to the user.

The next section will describe the method calls, events and options of the Mapnificent API.

API Details

All geo coordinates in Mapnificent are given and expected as follows:

{"lat": LAT_VALUE, "lng": LNG_VALUE}

To get started insert the following script tag in your code:

<script src="http://www.mapnificent.net/media/api/1/mapnificent.js" type="text/javascript" charset="utf-8"></script>

Mapnificent Static Methods

This will create the Mapnificent function in your global namespace. The Mapnificent function has the following methods:

Mapnificent.isBrowserSupported() returns boolean indicating if current browser is supported. Check is very naive.
Mapnificent.forCoordinates(coordinates, callback) Checks if there is a Mapnificent map for the coordinates. The callback function is called with one parameter. If the parameter is null, there is no Mapnificent map. Otherwise the parameter represents an options object with which a Mapnificent object can be created.
Mapnificent(options) You can call the function with an options object and will return a Mapnificent instance object.

Mapnificent Object Methods

When you have created a mapnificent object, you can add it to a map. The following methods are available:

addToMap(mapObject) adds the object to the Google Map identified by the mapObject. This creates an overlay inside the map.
destroy() removes the overlay from the map and destroys all layers.
hide() hide the map overlay
show() show the map overlay
addLayer(identifier, uiFunc) adds the layer identified by identifier together with the UI function to this mapnificent object. The layer will be setup and the UI function will be called in addToMap, so this must be done before.
getCanvasXY(pos) return the pixel coordinates of the Canvas Overlay that correspond to the given geo point.
getDivXY(pos) return the pixel coordinates of the Map Div that correspond to the given geo point.
getLatLngFromWindowXY(x,y) return the geo point for the browser window coordinate.
getLatLngFromCanvasXY(x,y) return the geo point for the canvas pixel coordinate.
getLayer(identifier) return layer object for this identifier (e.g. "urbanDistance").
trigger(eventName, [object]) calls all functions connected with that event giving them the optional second argument.
bind(eventName, func) binds the function to the event identified by eventName.
getDistanceInKm(pos1, pos2) returns the distance in kilometers between two geo points

Mapnificent Object Events

Additionally the following events are triggered and can be bound to:

"redraw" must be triggered when a redraw is needed, mapnificent's redraw function is bound to this event by default.
"initDone" triggered after initialization of the map is done, layers may not have loaded data yet.
"zoom" The Google Map was zoomed.
"resize" The window was resized.
"idleAfterRedrawing" Triggered after 500 milliseconds of idle time after a redraw. Good for refreshing stuff after a redraw without doing it every time in a sequence of multiple redraws.

Layer UI Function

The UI function that can be given to the addLayer method receives the following arguments:

var YourUiFunc = function(mapnificent, layer, $, window, undefined){ ... }

layer is the layer object, $ is a reference to jQuery, window to window and undefined is not passed and therefore truly undefined.

Urban Distance Layer Methods

The UrbanDistance layer has the following methods:

addPosition(pos, [time]) returns a Position object located at the geo point pos, initialized with the optional argument time (if not given, there is a default value of 15 minutes).
inRange(pos) returns a boolean indicating whether the given geo point is inside the area covered by this public transport layer.
getCalculationsInProgress() returns a number indicating how many positions are currently being calculated.
getOption(name) returns the value of option name, undefined if not found.
setOption(name, value) set the option name to value.
setOptions(optionMap) Extends the options with the contents of optionMap.
getDefaultOption(name) returns the default value with that name, might not reflect current value.
hasOptionChanged(name) compares current option value of name with default option value of name.
getImageData() returns the canvas image data that is cached between redraws, getting it directly from the drawing context hurts performance.
isHighlighted(x,y) Checks whether the pixel at x,y is reachable.
numberOfPixelsToSqkm(number) approximates the given number of pixels given to an area in square kilometers.
removePosition(index) remove Position object identified by its index.
trigger(eventName, [object]) calls all functions connected with that event giving them the optional second argument.
bind(eventName, func) binds the function to the event identified by eventName.
search.detectBlobs() returns an array of blobs, distinct areas of the Mapnificent rendering, with their bounds and midpoint in canvas pixel coordinates and midpoint in geo coordinates and some other information.

Urban Distance Layer Events

The following events of the urban distance layer are triggered and can be bound to:

"setup" Setup of the layer is done, the bound function receives the layer as an argument.
"loadProgress" Progress report of the data loading, the bound function receives a percentage as an argument.
"dataLoaded" All data finished loading, the layer is ready to calculate and has already started calculating pending calculations.
"positionMoved" A Position moved (its move function was called), the bound function receives the position as an argument.
"positionRemoved" A Position was removed, the bound function receives the position's index as an argument.
"calculationStarted" A Position calculation was started, the bound function receives the position as an argument.
"calculationUpdated" A Position reports progress of calculation, the bound function receives the position as an argument.
"calculationDone" A Position finished its calculation, the bound function receives the position as an argument.

Position object methods

The position object that is returned from the layer's addPosition method has also a couple of fields and methods:

setTime(time) Sets the time in seconds of the position.
getTime() returns the time in seconds of the position.
latlng access the current geo point of the position.
index An index uniquely identifying this position.
calculationProgress The number of iterations the calculation of this position as needed so far.
startCalculation(doneCallback, updateCallback) Starts the calculation of this position. The callback arguments can be skipped. Subscribing to the related events is recommended.
move(pos, notify) Move the position to the geo point, if notify is true, the positionMoved event will be triggered.
killWorker Terminates the current calculation for this position.

Options

The following options are available for the urban distance layer. You can change them with getOption and setOption or set them in the constructor options object under options.layerSettings.urbanDistance.

{ "secondsPerKmWalking": 13*60 // default walking speed
, "secondsPerKmBiking": 6*60  // default biking speed
, "colorMaxAcceptableTime": 120  // parameter for coloring
, "colorBaseGradientColor": 120 // parameter for coloring
, "colorMaxGradientColor": 240 // parameter for coloring
, "maxWalkTime": 15*60 // default max walking time to a stop
, "maxWalkTravelTime": 180 // default max travel time
, "intervalKey": "m1" // current day time: monday(m), saturday(a), sunday(u) + 0-4 (time of day)
, "animateAreaGrowth": false // animate drawing of area
, "animatedAreaOpacity": false //animate drawing of area
, "darkOverlayColor": "rgba(50,50,50,0.4)" // default overlay color
, "drawColor": "rgba(0,0,0,1)" // default drawing color
, "estimatedMaxCalculateCalls": 50000 // default estimated number of calculation iterations
, "cityData": "berlin-1" // default dataset id
, "calculateOnDrag": false // calculating on drag, possible for small data sets (Berlin, Sacramento)
, "dataUrlPrefix": mapnificent.env["dataUrlPrefix"] // load data from here
, "intersection": false // intersection option
, "color": false // color option
}

API Terms

The Mapnificent API is provided "AS IS", no warranty for availability or correct functionality. Your code should be written in a way that if Mapnificent fails in any way, your application degrades gracefully.

The Mapnificent API shall only be used to add an additional feature to your application, it must not be the only feature (that is what www.mapnificent.net is for).

The API is currently in beta phase and free of charge. This may change in the future for commercial usage of the API (commercial meaning: you make somehow money with the application that includes Mapnificent).

When you use the API you are obliged to follow the Terms of Use of the respective public transport data providers and display their data copyright notice if their license deems it necessary.

You are also obliged to display a link to Mapnificent . If you want to use the Mapnificent logo for a link to Mapnificent, you may do so.