Landcarte Reference

See also the brief introduction.

All classes are contained within the at.geo.ggl.* namespace, here referred to as geo.*. The base class representing the map, markers, shapes, data layers and other geoobjects added to the map is geo.Object. Therefore all these objects inherit the methods of this class.

The classes listed below are not to be constructed in an explicit way (much like instances of the jQuery class in jQuery). Ultimately, all class instances come out of the methods of a geo.Map object created on the map container element.

Almost all methods return an instance of the same class, unless stated otherwise. This enables method chaining.

Map instance initialization

A map instance is initialized via a .geoMap([options:Object]) method call on the map container's jQuery object, which returns an instance of geo.Map:

var map = $("#map").geoMap();

The same call can be used to get an already existing map instance and, optionally, to pass attributes to it. The map options are inherited from google.maps.MapOptions, yet a wider range of formats is accepted.

var options = { center: [50, 10], zoom: 3, mapTypeId: "roadmap" };
map = $("#map").geoMap(options);
// equivalent to
map = $("#map").geoMap().attr(options);

geo.Map extends geo.Object

An instance of this class is returned by the .geoMap() method. This class is also an extension of geo.Object.

// an instance of geo.Map:
var map = $("#map").geoMap();
.add(type:String, [options])
adds a geoobject of the given type; the type is a case-insensitive variant of a name of a class from the google.maps namespace; the rest of the arguments are the options accepted by the corresponding constructor as described in the Maps API reference.
// markers
map.add("marker", { position: [50, 10], icon: "m.png" });

// shapes
map.add("polyline", {
    path: [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]],
    strokeColor: "#f00", strokeWeight: 3, strokeStyle: "dotted"
});
map.add("rectangle", {
    bounds: [[50.5, 10.5], [56.5, 15.5]],
    strokeColor: "#0f0", fillColor: "#0f0"
});
map.add("circle", {
    center: [50.5, 10.5], radius: 54321,
    strokeColor: "#0f0", fillColor: "#0f0"
});

// data layers
map.add("bicyclinglayer");
map.add("visualization.heatmaplayer", { data: heatmap });

// info balloons
map.add("infowindow");

// etc.
.add("marker", position:Object|Array)
adds a marker to the map with the given position; a shortcut to .add("marker", { position: position }); see .add(type).
map.add("marker", [50, 10]);
// equivalent to
map.add("marker", { position: [50, 10] });
.add("markers", options:Array<Object|Array>, [sharedOptions:Object])
adds a set of markers to the map; the options can be either an array of marker options (inherited from google.maps.MarkerOptions) or an array of coordinates; all shared marker options can be passed in as a separate sharedOptions argument; a shortcut to the looped .add("marker", options + sharedOptions); see .add(type).
map.add("markers", [[50.5, 15.5], [56.5, 10.5]]);
map.add("markers", [
    { position: [50.5, 15.5], title: "#1" },
    { position: [56.5, 10.5], title: "#2" }
]);
map.add("markers", [
    { position: [50.5, 15.5], icon: "a.png" },
    { position: [56.5, 10.5], icon: "b.png" }
]);
// an icon image as a shared option
map.add("markers", [[50.5, 15.5], [56.5, 10.5]], { icon: "m.png" });
.add("polyline", path:Object|Array)
adds a polyline to the map with the given path; a shortcut to .add("polyline", { path: path }); see .add(type).
map.add("polyline", [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]]);
// equivalent to
map.add("polyline", {
    path: [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]]
});
.add("polygon", paths:Object|Array)
adds a polygon to the map with the given paths; a shortcut to .add("polygon", { paths: paths }); see .add(type).
map.add("polygon", [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]]);
// equivalent to
map.add("polygon", {
   paths: [[48.92, 2.24], [46.19, 6.06], [48.19, 16.35]]
});
.find(selector:String) geo.Collection
returns a collection of geoobjects that match the selector; the selector is a geoobject type, one of the pseudo-classes (:first, :last, :odd, :even, :visible, :invisible), or combined; if the selector contains the :first or :last pseudo-class the method returns a single instance of geo.Object instead of a collection; see geoobject types.
var markers = map.find("marker");
var oddShapes = map.find("shape", function(i) { return i % 2; });
// the latter is also equivalent to
oddShapes = map.find("shape:odd");
.has(type:String) Number
determines whether there are geoobjects of the given type on the map; returns the number of geoobjects of the given type; see geoobject types.
if (map.has("polyline")) map.find("marker").fit();
.fit(bounds:Object|Array|String, [callback:function])
fits the map viewport to the given bounds or region; see also geo.Collection.fit().
.animate(options:Object)
if the options contain a center or bounds property, the map can get animated while the options are set; other properties are set instantly; the options.center can be either a pair of coordinates or can specify a pixelwise shift as {x, y}.
map.animate({ center: [50, 10] });
map.animate({ center: { x: -30, y: 25 } });
.animate(property:String, value)
if the property is "center" or "bounds", the map can get animated while the property is set; other properties are set instantly; the "center" property can be either a pair of coordinates or can specify a pixelwise shift as {x, y}.
map.animate("center", [50, 10]);
map.animate("center", { x: -30, y: 25 });
.remove()
removes the map instance from the container.
map.remove();
.remove(object:String|geo.Object)
removes all geoobjects matching the given object, which can be either a string selector of the objects to be removed or a specific object itself; equivalent to .find(object).remove(); see also geoobject types.
map.remove("marker").remove("shape");

+ the methods inherited from the ancestor geo.Object class

geo.Object

The map (an instance of geo.Map) and almost anything added to the map are extensions of this class, therefore they inherit the methods of this class.

// instances of geo.Object:
var map      = $("#map").geoMap();
var marker   = map.find("marker").eq(0);
var polyline = map.find("polyline").eq(2);
var balloon  = map.find("infowindow:last");
.attr(options:Object)
passes a set of attributes to the geoobject.
marker.attr({ position: [46.5, 8] });
.attr(name:String, value)
passes a single attribute to the geoobject.
map.attr("center", [46.5, 8]);
.attr(name:String) dynamic type
returns an attribute of the geoobject; this method returns a raw value provided by the map engine; see also the .prop() method.
var color = polyline.attr("strokeColor");
var p = marker.attr("position"); // raw internal output
.prop(options:Object)
passes a set of properties to the geoobject.
marker.prop({ position: [46.5, 8] });
.prop(name:String, value)
passes a single property to the geoobject.
map.prop("center", [46.5, 8]);
.prop(name:String) dynamic type
returns a property of the geoobject; this method returns a normalized value which wraps the value provided by the map engine; see also the .attr() method.
var color = polyline.prop("strokeColor");
var p = marker.prop("position"); // normalized output
.show([options])
makes the geoobject visible and passes the options if provided; an "infowindow" geoobject calls its underlying .open() method, where options are applicable as well.
marker.show();
map.find("infowindow:first").show(map, marker);
.hide()
makes the geoobject invisible; an "infowindow" geoobject calls its underlying .close() method.
marker.hide();
.toggle()
switches the geoobject's visibility.
polyline.toggle();
.on(events:String, handler:function(event:Object))
attaches an event handler of one or more events to the geoobject; the events argument is an event type or a space-separated list of event types; the handler function is an event handler; within the scope of the event handler, this keyword refers to the raw geoobject provided by the map engine, and the event.target is its geo.Object counterpart.
marker.on("click", function(event) {
    var marker = event.target, p = marker.prop("position");
    balloon.attr({ content: p.lat + ", " + p.lon }).show(map, marker);
});
.off([events:String], [handler:function])
detaches all event handlers of the given types from the geoobject; the events argument is an event type or a space-separated list of event types; detaches all event handlers from the geoobject if called without arguments.
polyline.off("click");
.trigger(event:String)
calls the handlers of the given event type attached to the geoobject.
polyline.trigger("click");
.bounds() Object
returns the bounding box outlining the geoobject.
.fit()
fits the map viewport to the geoobject.
// fitting to the first polygon on the map
map.find("polygon").eq(0).fit();
.remove()
removes the geoobject; geo.Map overrides this method, see geo.Map.remove().
polyline.remove();
.is(selector:String) boolean
determines whether the geoobject matches the given selector; see also geoobject types.
polyline.type == "shape"; // false, since the type is "polyline"
polyline.is("polyline"); // true
polyline.is("shape"); // true
.core Object
stores a reference to the internal raw geoobject.

geo.Collection

This class represents a collection of geoobjects. Many of its methods are identical to the methods of geo.Object, which makes interaction with a collection of geoobjects almost identical to the interaction with a single geoobject.

var map = $("#map").geoMap();
// instances of geo.Collection:
var markers     = map.find("marker");
var polylines   = map.find("polyline");
var greenShapes = map.find({ fillColor: "green" });
.eq(n:Number) geo.Object
returns a geoobject at the n-th index position in the collection.
.first() geo.Object
returns the first geoobject in the collection.
.last() geo.Object
returns the last geoobject in the collection.
.gt(n:Number) geo.Collection
returns a subset collection of the geoobjects with the index position greater than n.
.lt(n:Number) geo.Collection
returns a subset collection of the geoobjects with the index position less than n.
.get(n:Number) Object
returns the raw geoobject at the n-th index position in the collection.
.each(iterator:function(index:Number, object:geo.Object))
iterates over the collection of geoobjects; within the scope of the iterator function, this keyword refers to the raw geoobject linked to the object passed as an argument.
markers.each(function(i, marker) {
    marker.prop("title", "Marker #" + (i + 1));
});
.attr(options:Object)
passes a set of attributes to the collection of geoobjects.
.attr(name:String, value)
passes a single attribute to the collection of geoobjects.
.attr(name:String) Array
returns an array of attributes from the collection of geoobjects; this method returns raw values provided by the map engine; see also the .prop() method.
.prop(options:Object)
passes a set of properties to the collection of geoobjects.
.prop(name:String, value)
passes a single property to the collection of geoobjects.
.prop(name:String) Array
returns an array of properties from the collection of geoobjects; this method returns normalized values which wrap the values provided by the map engine; see also the .attr() method.
.show()
makes the geoobjects in the collection visible.
.hide()
makes the geoobjects in the collection invisible.
.toggle()
switches the visibility of the geoobjects in the collection.
.on(events:String, handler:function(event:Object))
attaches an event handler of one or more events to the collection of geoobjects; see geo.Object.on().
.off(events:String)
detaches all event handlers of the given types from the collection of geoobjects; see geo.Object.off().
.trigger(event:String)
calls the handlers of the given event type attached to the collection of geoobjects.
.bounds() Object
returns the bounding box outlining the collection of geoobjects.
.fit()
fits the map viewport to the given collection of geoobjects.
// fitting to all markers except for the first three
map.find("marker").gt(2).fit();
.remove()
removes all geoobjects in the collection.
.filter(test:function(index:Number, object:geo.Object))
returns the subset of the collection passing the function test as true; within the scope of the test function this keyword refers to the raw counterpart of the object.
.filter(properties:Object)
returns the subset of the collection matching the given set of properties.
.filter(selector:String)
returns the subset of the collection matching the given selector.
.toArray() Array<geo.Object>
returns the array of the geoobjects in the collection.
.size() Number
returns the number of geoobjects in the collection.
.empty() boolean
determines whether the collection is empty.

Utilities

Geocoding

$.geocode(location:String|Object|Array, [callback:function(data)])
makes a geocoding request for the given location which is either a string address or a pair of coordinates.
$.geocode("Moscow", function(data) {
   if (data.location) map.add("marker", data.location);
});
$.geocode(options:Object, [callback:function])
makes a geocoding request specified by the options.
var query = { address: "Copenhagen" };
$.geocode(query, function(data) { ... });

Route directions

$.route.setup(options:Object)
passes the options to the route renderer.
var sidebar = document.querySelector("#sidebar");
$.route.setup({ map: map, panel: sidebar });
$.route.render(options:Object, [callback:function(data)])
renders a route specified by the options.
$.route.render({
    origin: "Grenoble", destination: "Rheims",
    waypoints: [{ location: "Lyon" }],
    travelMode: google.maps.TravelMode.DRIVING
});
$.route.clear()
clears the rendered route.

Geometry

These utilities are only available with the google.maps.geometry library imported.

$.geometry.distance(loc1, loc2, callback:function) Number
returns the distance between two locations in meters.
var d = $.geometry.distance([48.92, 2.24], [46.19, 6.06]);
// ~417.9 km
$.geometry.area(path, callback:function) Number
returns the area of a closed path.
$.geometry.length(path, callback:function) Number
returns the length of the path.
$.geometry.heading(loc1, loc2, callback:function) Number
returns the heading from one location to another, degrees from the direction to the north clockwise.
$.geometry.interpolate(loc1, loc2, q:Number, callback:function) Object
returns an interpolated location between the two given locations; q is in the range of [0, 1].
$.geometry.contains(loc, polygon, callback:function) boolean
checks whether the location lies within the polygon.
$.geometry.edge(loc, shape, callback:function) boolean
checks whether the location lies on the edge of the shape; the precision can be changed by the $.geometry.tolerance() method.
$.geometry.decode(s:String, callback:function) Array
returns a decoded polyline path.
$.geometry.encode(path, callback:function) String
returns a encoded polyline path.
$.geometry.radius(value:Number)
sets the value of the radius, employed by some $.geometry methods (such as .distance(), .area() and .length()); by default, the radius of the Earth is used.
$.geometry.tolerance(value:Number)
sets the value of the precision, employed by some $.geometry methods (such as .edge()).
$.geometry.convert(locations:Array, callback:function) Array
converts the set of locations to the map's internal format and passes it to the callback.

Geoobject options

The representation of geoobject options is inherited from the Google Maps API v3. Additionally, for some common data types Landcarte supports shortcut formats, natively unsupported by the Google API.

Coordinates are recognized in almost any format, e.g.:

[ 46.233921, 6.052458 ]
{ lat: 46.233921, lon: 6.052458 }
{ latitude: 46.233921, longitude: 6.052458 }

Rectangular bounds are likewise defined by a couple of south–west and north–east points, e.g.:

[ [45, 3], [55, 12] ]
{ sw: [45, 3], ne: [55, 12] }
{ sw: { lat: 45, lon: 3 }, ne: { lat: 55, lon: 12 } }

Types of geoobjects & Selectors

The type of a geoobject is a string corresponding to the name of the respective Maps API class, in lower case.

map.add("marker", [50, 10]);
// adds a google.maps.Marker
map.add("streetviewpanorama");
// adds a google.maps.StreetViewPanorama
map.add("visualization.heatmaplayer", { data: heatmap });
// adds a google.maps.visualization.HeatmapLayer

The filtering methods such as geo.Collection.filter(), geo.Map.find() or geo.Object.is() accept any of these types case-insensitively. Two collective types — "shape" and "layer" — match multiple geoobject types.

polyline.is("polyline"); // true
polyline.is("shape"); // true
map.find("layer").remove();

Selectors can also include one of the pseudo-classes: :first, :last, :odd, :even, :visible, :invisible.

var lastMarker = map.find("marker:last");
var allVisible = map.find(":visible");

Geoobject events

Event handlers are attached to geoobjects via the .on() method and detached via the .off() method. The names of the events are equivalent to those provided by the Google Maps API v3.

var map = $("#map").geoMap();
map.on("click", function(event) {
    map.add("marker", event.location);
});
map.find("shape").off("click");