Maps are the central element of the Javascript API - the map object manages tile layers, contains UI elements, and provides many types of interactivity.
Create a map on the current page.
Arguments:
elementmust be theidof an element on the page, or an element itself. Typically maps are created within<div>elements. This element should have a size: whether specified with external CSS or an inline style likestyle="width:600px;height:400px"layerscan be a layer created withmapbox.layer(), an array of such layers, or omitteddimensionscan be an object withxandyattributes representing the width and height in pixelseventHandlerscan be an array of event handlers, including any of the following:easey_handlers.DragHandler()easey_handlers.DoubleClickHandler()easey_handlers.MouseWheelHandler()easey_handlers.TouchHandler()MM.DragHandler()MM.DoubleClickHandler()MM.MouseWheelHandler()MM.TouchHandler()
Returns a map object, which has the following methods:
Example:
// for this to work, you'll need an element like
// <div id="map"></div> on your page
var map = mapbox.map('map');
Enable or disable inertial panning on maps. By default, maps smoothly pan and zoom with inertia.
Arguments:
valuemust betrueorfalseto set whether the map uses inertia.
Returns the map object.
Example:
map.smooth(false); // disable inertial panning
Center the map on a geographical location, or get its current center.
Arguments:
centerpointcan be an object withlatandlonvalues, like{ lat: 10, lon: -88 }, or ommitted to get the map's current locationanimatecan betrueto animate the map's movement, or omitted to move immediately
Returns the map object if arguments are given, the map's center location (in the same form as
specified in centerpoint) otherwise.
Example:
// center the map on Manhattan
map.center({ lat: 40.74, lon: -73.98);
Set the map's zoom level, or get its current zoom level.
Arguments:
zoomcan be zoom level in the range supported by the map's layers (an integer from 0-20, typically), or omitted to get the current zoom level..animatecan betrueto animate the map's movement, or omitted to move immediately.
Returns the map object if arguments are given, the map's current zoom level otherwise.
Example:
// zoom to z10 and animate the transition
map.zoom(10, true);
Set the map's zoom level and centerpoint simultaneously. Especially with the third argument, animate,
set to true, this allows for a better animation effect.
Arguments:
centerpointcan be an object withlatandlonvalues, like{ lat: 10, lon: -88 }zoommust be zoom level in the range supported by the map's layers (an integer from 0-20, typically)animatecan betrueto animate the map's movement, or omitted to move immediately.
Returns the map object.
Example:
// Center the map on Washington, DC, at zoom level 5
map.centerzoom({ lat: 38.9, lon: -77.03 }, 5);
Get the extent of the currently visible area.
Returns an instance of MM.Extent.
Modify the center and zoom of the map so that the provided extent is visible. This can be useful because extents - the corners of the map - can implicitly cause the map to 'show the whole world' regardless of screen size.
Arguments:
extentcan be an instance ofMM.Extent, or an array of two locations.precisecab betrueorfalse. If true, resulting zoom levels may be fractional. (By default, the map's zoom level is rounded down to keep tile images from blurring.)
Returns the map object.
Example:
// using an extent object:
map.setExtent(new MM.Extent(80, -170, -70, 170));
// this call can also be expressed as:
map.setExtent([{ lat: 80, lon: -170 }, { lat: -70, lon: 170 }]);
Set the map's minimum and maximum zoom levels.
Arguments:
minZoomis the minimum zoom levelmaxZoomis the maximum zoom level
Returns the map object.
Example:
map.setZoomRange(3, 17);
Set the map's panning limits.
Arguments:
locationsmust be either an instance of MM.Extent or an array of two locations in{ lat: 0, lon: 0 }form. The order of locations doesn't matter - they're sorted internally.
Returns the map object.
Example:
map.setPanLimits([{ lat: -20, lon: 0 }, { lat: 0, lon: 20 }]);
// or with an Extent object
map.setPanLimits(new MM.Extent(0, -20, -20, 0));
Set the map's dimensions. This sets map.autoSize to false to prevent further automatic resizing.
Arguments:
dimensionsis an object withxandyproperties representing the map's new dimensions in pixels.
Returns the map object.
Change zoom level by the provided offset.
Arguments:
zoomOffsetis the amount to zoom by. Positive offsets zoom in. Negative offsets zoom out.
Returns the map object.
Example:
// zoom in by one zoom level
map.zoomBy(1);
// zoom out by two zoom levels
map.zoomBy(-2);
Change the zoom level by the provided offset, while maintaining the same location at the provided point. This is used by MM.DoubleClickHandler.
zoomOffsetis the amount to zoom by. Positive offsets zoom in. Negative offsets zoom out.pointis the point on the map that maintains its current location.
Returns the map object.
Pan by the specified distances.
Arguments:
xthe distance to pan horizontally. Positive values pan right, negative values pan left.ythe distance to pan vertically. Positive values pan down, negative values pan up.
Returns the map object.
Example:
// pan right and down by one pixel
map.panBy(1, 1);
Redraw the map and its layers. First, the map enforces its coordLimits on its center and zoom. If autoSize is true, the map's dimensions are recalculated from its parent. Lastly, each of the map's layers is drawn.
Request a "lazy" call to draw in 1 second. This is useful if you're responding to lots of user input and know that you'll need to redraw the map eventually, but not immediately.
Refreshes map.ui and map.interaction to reflect any layer changes.
The map's current center coordinate.
An object with x and y attributes expressing the dimensions of the map in pixels.
The DOM element containing the map.
Convert a screen point to a location (longitude and latitude).
Arguments:
pointis an instance ofMM.Pointor an object withxandyproperties.
Returns an object with lat and lon properties indicating the latitude
and longitude of the point on the globe.
Example:
// get the geographical location of the top-left corner of the map
var top_left = map.pointLocation({ x: 0, y: 0});
Convert a screen point to a tile coordinate.
Arguments:
pointis an instance ofMM.Pointor an object withxandyproperties.
Returns an instance of MM.Coordinate - an object with column, row,
and zoom properties indicating the coordinate of the point. The zoom of
the point will be same as the current zoom level of the map.
Example:
// get the coordinate location of the top-left corner of the map
var top_left = map.coordinateLocation({ x: 0, y: 0});
Convert a location to a screen point.
Arguments:
locationis an instance ofMM.Locationor an object withlatandlonproperties.
Returns an instance of MM.Point.
Convert a location to a tile coordinate.
Arguments:
locationis an instance ofMM.Locationor an object withlatandlonproperties.
Returns an instance of MM.Coordinate.
Convert a tile coordinate to a screen point.
Arguments:
coordinateis an instance ofMM.Coordinate.
Returns an instance of MM.Point.
Convert a tile coordinate to a location (longitude and latitude).
Arguments:
coordinateis an instance ofMM.Coordinate.
Returns and instance of MM.Location.
Add a layer to the map, above other layers.
Arguments:
layeris a layer object, such as an instance ofmapbox.layer()ormapbox.markers.layer().
Returns the map object.
Example:
// add a layer to the map
map.addLayer(mapbox.layer().id('examples.map-dg7cqh4z'));
Add a tile layer to the map, below any marker layers to prevent them from being covered up.
layeris a layer object, such as an instance ofmapbox.layer().
Returns the map object.
Remove the provided layer from the map.
Arguments:
layeris a layer, or the name of a layer, currently added to the map.
Returns the map object.
Remove the layer at the provided index.
indexis a non-negative integer.
Returns the map object.
Disable a layer. Disabled layers maintain their position, but do not get drawn.
Arguments:
layeris the name of a layer currently added to the map.
Returns the map object.
Disable a layer at the provided index. Disabled layers maintain their position, but do not get drawn.
Arguments:
indexis a non-negative integer representing the position of the layer.
Returns the map object.
Example:
// disable the topmost layer in the map
map.disableLayerAt(0);
Enable a previously disabled layer.
Arguments:
layeris the name of a layer currently added to the map.
Returns the map object.
Enable the layer at the provided index.
Arguments:
indexis a non-negative integer representing the position of the layer to be enabled.
Returns the map object.
Get a layer by name.
Arguments:
nameis the name of a layer.
Returns the layer object.
Returns a list the map's layers.
Get the layer at the provided index.
Arguments
indexcan be a non-negative integer.
Returns a layer.
This is an instance of mapbox.ease attached to the map for convenience. For full documentation take a look at mapbox.ease.
Example:
map.ease.location({ lat: 10, lon: -88 }).zoom(5).optimal();
The API provides a set of UI elements that can be freely mixed & matched, as well as styled
beyond the default (provided in the mapbox.css stylesheet).
Maps created with mapbox.map have an array of pre-initialized UI elements at .ui.
All UI elements support the simple operations .add() and .remove() to add &
remove them from the map.
Add the UI element to the map. Add the HTML elements that the UI element manages (if any) to the map element, and bind any events.
Example:
// enable the zoomer control. adds + and - buttons to the map
map.ui.zoomer.add();
Remove the UI element from the map. Removes the HTML elements from the map, if any, and removes listeners, if any.
// remove the fullscreen control from the map visually and functionally
map.ui.fullscreen.remove();
For applicable elements (zoomer, attribution, legend, fullscreen), returns the DOM element this control exposes.
Add a link that can maximize and minimize the map on the browser page
DOM Structure:
<a class="map-fullscreen" href="#fullscreen">fullscreen</a>
Add the map's changing position to the URL, making map locations linkable
Add the ability to zoom into the map by shift-clicking and dragging a box, to which the map zooms
Add zoom in and zoom out buttons to map
DOM Structure:
<!-- when a zoom control is inactive, .zoomdisable is added to it -->
<a href="#" class="zoomer zoomin">+</a>
<a href="#" class="zoomer zoomout">-</a>
Add an element with attribution information to the map
DOM Structure:
<div class="map-attribution map-mm"></div>
Add an element with legend information to map
DOM Structure:
<div class="map-legends">
<div class="map-legend">
<!-- Legend content -->
</div>
</div>
Allow simple location selection on the map: clicking without dragging will select a point, and notify listeners with the new list of points.
Adds a callback that is called on changes to the pointselector contents.
Arguments:
eventis a string of the event you want to bind the callback tocallbackis a function that is called on the event specified byevent
Event should be a String which is one of the following:
change: whenever points are added or removed
Callback is a Function that is called with arguments depending on what event is bound:
drawn: the layer objectlocations: a list of locations currently selected
Returns the pointselector
Remove a callback bound by .addCallback(event, callback).
Arguments:
-
eventis a string of the event you want to bind the callback to This must be the same string that was given inaddCallback -
callbackis a function that is called on the event specified byevent. This must be the same function as was given inaddCallback.
Returns the pointselector
Allow extents to be selected on the map.
Adds a callback that is called on changes to the boxselector contents.
Arguments:
eventis a string of the event you want to bind the callback tocallbackis a function that is called on the event specified byevent
Event should be a String which is one of the following:
change: whenever an extent is selected
Callback is a Function that is called with arguments depending on what event is bound:
drawn: the layer objectextent: the currently selected extent
Returns the boxselector
Remove a callback bound by .addCallback(event, callback).
Arguments:
-
eventis a string of the event you want to bind the callback to This must be the same string that was given inaddCallback -
callbackis a function that is called on the event specified byevent. This must be the same function as was given inaddCallback.
Returns the boxselector
Refresh legend and attribution to reflect layer changes, merging and displaying legends and attribution for all enabled layers.
Returns the ui object.
Interaction is what we call interactive parts of maps that are created with the powerful tooltips & regions system in TileMill. Under the hood, it's powered by the open UTFGrid specification.
Enable default settings - animated tooltips - for interaction with the map.
This internally calls interaction.refresh() to set the interactivity for the top layer.
Returns the interaction control
Example:
var interaction = mapbox.interaction()
.map(map)
.auto();
DOM Structure (tooltips):
<div class="map-tooltip map-tooltip-0">
<!-- Tooltip content -->
</div>
Refresh interactivity control to reflect any layer changes.
If auto has not been called, this function will not change anything.
Returns the interaction control
Add a callback for a specific event type. Event types are listed further down.
Arguments:
eventis a string such as "zoomed" or "drawn".callbackis function that gets called when the event is triggered.
Returns the map object.
Remove a previously added callback.
Arguments:
eventis the event type to remove the callback for.callbackis the callback to be removed.
Returns the map object.
Fires when the map's zoom level changes. Callbacks receive two arguments:
mapis the map object.zoomOffsetis the difference between zoom levels. Get the current zoom withmap.zoom().
Example:
map.addCallback("zoomed", function(map, zoomOffset) {
console.log("Map zoomed by", zoomOffset);
});
Fires when the map has been panned. Callbacks receive two arguments:
mapis the map object.panOffsetis a two-element array in the form of[dx, dy].
Example:
map.addCallback("panned", function(map, panOffset) {
console.log("map panned by x:", panOffset[0], "y:", panOffset[1]);
});
Fires when the map has been resized. Callbacks receive two arguments:
mapis the map object.dimensionsis a newMM.Pointwith the map's new dimensions.
Example:
map.addCallback("resized", function(map, dimensions) {
console.log("map dimensions:", dimensions.x, "y:", dimensions.y);
});
Fires when the map's extent is set. Callbacks receive two arguments:
mapis the map object.extentis an instance ofMM.Extent.
Example:
map.addCallback("extentset", function(map, extent) {
console.log("Map's extent set to:", extent);
});
Fires when the map is redrawn. Callbacks receive one argument:
mapis the map object.
Example:
map.addCallback("drawn", function(map) {
console.log("map drawn!");
});
To load information about a certain map you've created on MapBox, we provide mapbox.load and
mapbox.auto, which pull the TileJSON file from a server and
auto-instantiate many of its features.
Load layer definitions and other map information from MapBox Hosting.
Arguments:
-
urlcan be either be a full URL to a TileJSON file, likehttp://a.tiles.mapbox.com/v3/tmcw.map-hehqnmda.jsonp, or a bare id, liketmcw.map-hehqnmda, which will get expanded to the former. This can also accept an array of urls in the same format. -
callbackmust be a function that receives either a single object with details or an array of objects if an array of map ids was given as the first argument.{ zoom: ZOOM_LEVEL, center: CENTER,
// like you could create with mapbox.layer() layer: TILE_LAYER, // if present, like you would create with mapbox.markers() markers: MARKERS_LAYER}
Example:
<div id='map' style='width:500px;height:400px;'></div>
<script>
mapbox.load('tmcw.map-hehqnmda', function(o) {
var map = mapbox.map('map');
map.addLayer(o.layer);
});
</script>
Load and create a map with sensible defaults.
Arguments:
elementmust be theidof an element on the page, or an element itself. Typically maps are created within<div>elementsurlmust be a TileJSON URL, the id of a MapBox map, multiple IDs and URLs in an array.callbackif specified, receives the map as its first argument, and the same object asmapbox.loadas the second argument. It is called after all resources have been loaded and the map is complete.
Returns undefined: this is an asynchronous function without a useful return value.
Example:
<div id='map' style='width:500px;height:400px;'></div>
<script>
mapbox.auto('map', 'http://a.tiles.mapbox.com/v3/tmcw.map-hehqnmda.jsonp');
</script>
mapbox.layer is a fast way to add layers to your map without having to deal with complex configuration.
You can add a tiled layer to your map with mapbox.layer(), a simple interface to
layers from MapBox Hosting and elsewhere.
Returns a layer object, which has the following methods:
Get or set the layer ID, which corresponds to a MapBox map.
Arguments:
idcan be the id of a MapBox map, or omitted to get the currentidvalue. This also calls layer.named() setting the name to be the same as the id - callnamed()to reset it. For instance, if you were trying to add the map athttps://tiles.mapbox.com/tmcw/map/map-hehqnmda, you could create this layer like so:callback, if provided, is called after the layer has been asynchronously loaded from MapBox. It is called with on argument, the layer object.
Returns the layer object if arguments are given, the layer's id otherwise.
Example:
var layer = mapbox.layer().id('map-hehqnmda');
Get or set the name of the layer, as referred to by the map.
Arguments:
namecan be a new name to call this layer
Returns the layer object if arguments are given, the layer's name otherwise.
Pull a layer from a server besides MapBox Hosting that supports TileJSON, like a self-hosted TileStream.
Arguments:
urlcan be a string value that is a fully-formed URL, or omitted to get the URL from which this layer was sourced.callback, if provided, is called with one argument, the layer object, after the TileJSON information has been asynchronously loaded.
Returns the layer object if arguments are given, the pulled URL otherwise.
Example:
var layer = mapbox.layer().url('http://a.tiles.mapbox.com/v3/tmcw.map-hehqnmda.jsonp');
Set layer options directly from a TileJSON object.
Arguments:
tilejsonmust be a TileJSON object as a Javascript object.
Returns the layer object if arguments are given, the layer's TileJSON settings otherwise.
Enable or disable compositing layers together on MapBox hosting. Compositing combines multiple tile images into one layer of blended images, increasing map performance and reducing the number of requests the browser needs to make.
enabledmust be either true or false.
Returns the layer object.
The layer's parent DOM element.