This API documentation covers the MapBox Javascript API, an API for adding MapBox maps to webpages.
In order to use this API, you'll need to understand basic Javascript and mapping concepts. If you'd like to learn Javascript, start with an interactive course, a book or a printed book. If you'd like to learn more about maps, we've provided a helpful article explaining how web maps work.
The Javascript API is implemented as a Leaflet plugin. Leaflet is an open-source library that provides the basic ability to embed a map, like a MapBox map or a map from OpenStreetMap, into a page. The Leaflet API handles much of the fundamental operations of using maps, so this API documentation is meant to be used in conjunction with the Leaflet API reference.
The MapBox API includes Leaflet and makes it easier to integrate Leaflet with MapBox's maps and services.
Here's a simple page that you can set up with MapBox.js:
<html>
<head>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no' />
<link href='//api.tiles.mapbox.com/mapbox.js/v1.4.0/mapbox.css' rel='stylesheet' />
<!--[if lte IE 8]>
<link href='//api.tiles.mapbox.com/mapbox.js/v1.4.0/mapbox.ie.css' rel='stylesheet' />
<![endif]-->
<script src='//api.tiles.mapbox.com/mapbox.js/v1.4.0/mapbox.js'></script>
<style>
#map {
width:600px;
height:400px;
}
</style>
</head>
<body>
<div id='map' class='dark'></div>
<script type='text/javascript'>
var map = L.mapbox.map('map', 'examples.map-y7l23tes')
.setView([37.9, -77], 5);
</script>
</body>
</html>
The necessary Javascript and CSS files for the map are hosted on MapBox's servers, so they're served from a worldwide content-distribution network. There's no API key required to include the Javascript API - you'll identify with MapBox's services simply by using your own custom maps.
This documentation is organized by methods in the Javascript API. Each method
is shown with potential arguments, and their types. For instance, the setFilter
method on L.mapbox.markerLayer
is documented as:
markerLayer.setFilter(filter: function)
The format filter: function
means that the single argument to setFilter
, a filter
function, should be a Javascript function. Other kinds of arguments include
object
, string
, or Element
.
When the API has a Javascript constructor function that returns an object, the constructor
is documented with its full name and the functions on the object are named with just
the type of the object. For instance, L.mapbox.markerLayer
documents a function that
returns a layer for markers. The methods on that object are then documented as
markerLayer.setFilter
, markerLayer.getGeoJSON
, and so on.
Like many other Javascript libraries, some of what the MapBox.js plugin does
is asynchronous - when
you create a layer like L.mapbox.tileLayer('examples.foo')
, the layer
doesn't immediately know which tiles to load and its attribution information.
Instead, it loads this information with an AJAX
call.
For most things you'll write, this isn't a problem, since MapBox.js does a good
job of handling these on-the-fly updates. If you're writing code that needs
to know when layers and other dynamically-loaded objects are ready, you can
use the ready
event to listen for their ready state. For instance:
var layer = L.mapbox.tileLayer('examples.map-0l53fhk2');
layer.on('ready', function() {
// the layer has been fully loaded now, and you can
// call .getTileJSON and investigate its properties
});
Similarly, dynamically-loaded objects produce an `error` event if something goes wrong, like if the map ID you provide is a 404:
var layer = L.mapbox.tileLayer('examples.map-0l53fhk2');
layer.on('error', function(err) {
// for some reason, this layer didn't load.
// you can find out more with the 'err' argument
// passed to this function
});
This library takes advantage of several open specifications, including TileJSON and UTFGrid.
For the purposes of this API, TileJSON is used as a way to describe maps and resources, so it is the configuration format given to layers, maps, and controls. UTFGrid is a fast way to interact with maps with tooltips and customizable behaviors, and is easy to define and produce in TileMill.
The MapBox marker API and the L.mapbox.markers
interface use GeoJSON,
a simple, open standard for geo-data based on JSON
and simple features, like Points and Polygons.
MapBox.js is optimized for mobile devices and small screens by default. There are, however, best practices to make sure your map always looks its best.
Having the ability to use retina tiles when the device supports them is easy.
When creating the map, use the detectRetina
to verify if retina is available
and retinaVersion
to use a tilelayer which is designed for retina screens.
var map = L.mapbox.map('map', 'examples.map-y7l23tes', {
detectRetina: true,
retinaVersion: 'examples.map-zswgei2n'
}).setView([40, -74.50], 9);
Some MapBox maps support switching to retina scale automatically: if you're using one of these maps, you can simply set `detectRetina` and the higher-scale tiles will be used when retina is detected.
var map = L.mapbox.map('map', 'examples.map-y7l23tes', {
detectRetina: true
}).setView([40, -74.50], 9);
MapBox.js aims to be compatible with IE8+, Chrome, Safari, Firefox, Opera, Mobile Safari, and other modern browsers. Browser-specific issues should be reported in the issue tracker.
The fragility of Internet Explorer and programming in general makes it simple to break code with subtle changes. We recommend checking code in jshint as a first-line measure and enabling browser debug tools to obtain precise error reports and debugging information that you should share as part of your debugging.
Modern mobile browsers now support scaling of webpages by leveraging the meta tag viewport
. This enlarges the window making your map look better on a mobile device. Simply include this in the head of your document:
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no' />
If you're planning on having a page that has large amounts of scrolling, try to avoid a large map height. Having a 'tall' map can cause the user to get stuck on the map while scrolling. Another way around this is to disable dragging
for mobile devices: map.dragging.disable();
By default, MapBox.js includes a bundled version of Leaflet that MapBox has ensured is compatible. However, a standalone version of MapBox.js is also available without Leaflet included, which you can use if you would like to supply your own version of Leaflet. You will need to include Leaflet's JavaScript and CSS files, and Leaflet 0.6 or greater is required.
Here's an example of using standalone MapBox.js:
<html>
<head>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no' />
<link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.6/leaflet.css" />
<link href='//api.tiles.mapbox.com/mapbox.js/v1.2.0/mapbox.standalone.css' rel='stylesheet' />
<!--[if lte IE 8]>
<link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.6/leaflet.ie.css" />
<![endif]-->
<script src="http://cdn.leafletjs.com/leaflet-0.6/leaflet.js"></script>
<script src='//api.tiles.mapbox.com/mapbox.js/v1.2.0/mapbox.standalone.js'></script>
<style>
#map {
width:600px;
height:400px;
}
</style>
</head>
<body>
<div id='map' class='dark'></div>
<script type='text/javascript'>
var map = L.mapbox.map('map', 'examples.map-y7l23tes')
.setView([37.9, -77], 5);
</script>
</body>
</html>