--- layout: api title: v1.4.0 categories: api version: v1.4.0 navigation: - title: Map nav: - title: L.mapbox.map sub: - title: map.getTileJSON sub: - title: Layers nav: - title: L.mapbox.tileLayer sub: - tileLayer.getTileJSON - tileLayer.setFormat - title: L.mapbox.gridLayer sub: - gridLayer.getTileJSON - gridLayer.getData - title: L.mapbox.markerLayer sub: - markerLayer.loadURL - markerLayer.loadID - markerLayer.setFilter - markerLayer.getFilter - markerLayer.setGeoJSON - markerLayer.getGeoJSON - title: Geocoding nav: - title: L.mapbox.geocoder sub: - geocoder.query - geocoder.reverseQuery - title: Controls nav: - title: L.mapbox.legendControl sub: - legendControl.addLegend - legendControl.removeLegend - title: L.mapbox.gridControl sub: - title: L.mapbox.geocoderControl sub: - geocoderControl.setURL - geocoderControl.setID - geocoderControl.setTileJSON - geocoderControl.on - title: L.mapbox.shareControl sub: - title: Markers nav: - title: L.mapbox.marker.icon sub: - title: L.mapbox.marker.style sub: - title: Utility nav: - title: L.mapbox.sanitize sub: - title: L.mapbox.template sub: - title: Theming nav: --- {% raw %}
Create and automatically configure a map with layers, markers, and interactivity.
Extends: L.Map
Options | Value | Description |
---|---|---|
element (required) | string | Must be the id of an element, or a DOM element reference. |
id or url or tilejson |
|
url can be
|
options | object | If provided, it is the same options as provided to L.Map with the following additions:
|
Example:
// map refers to a <div> element with the ID map
// examples.map-4l7djmvo is the ID of a map on MapBox.com
var map = L.mapbox.map('map', 'examples.map-4l7djmvo');
// map refers to a <div> element with the ID map
// This map will have no layers initially
var map = L.mapbox.map('map');
Returns: a map object
Returns this map's TileJSON object which determines its tile source, zoom bounds and other metadata.
Returns: the TileJSON object
You can add a tiled layer to your map with L.mapbox.tileLayer()
, a simple
interface to layers from MapBox and elsewhere.
Extends: L.TileLayer
Options | Value | Description |
---|---|---|
id or url or tilejson (required) |
|
Value must be
|
options | object | The second argument is optional. If provided, it is the same options as provided to L.TileLayer with one addition:
|
If detectRetina
is set to true and the map in question supports auto-scaling, then a scaled version will automatically be useful if retina is detected and you don't provide an explicit retinaVersion
to be used.
Example:
// the second argument is optional
var layer = L.mapbox.tileLayer('examples.map-20v6611k');
// you can also provide a full url to a tilejson resource
var layer = L.mapbox.tileLayer('http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json');
// if provided,you can support retina tiles
var layer = L.mapbox.tileLayer('examples.map-20v6611k', {
detectRetina: true,
// if retina is detected, this layer is used instead
retinaVersion: 'examples.map-zswgei2n'
});
// if this map supports auto-scaling, `detectRetina` will automatically
// use scaled tiles when retina is detected.
var layer = L.mapbox.tileLayer('examples.map-20v6611k', {
detectRetina: true,
});
Returns a L.mapbox.tileLayer
object.
Returns this layer's TileJSON object which determines its tile source, zoom bounds and other metadata.
Example:
var layer = L.mapbox.tileLayer('examples.map-20v6611k')
// since layers load asynchronously through AJAX, use the
// `.on` function to listen for them to be loaded before
// calling `getTileJSON()`
.on('load', function() {
// get TileJSON data from the loaded layer
var TileJSON = layer.getTileJSON();
});
Returns: the TileJSON object
Set the image format of tiles in this layer. You can use lower-quality tiles in order to load maps faster
Options | Value | Description |
---|---|---|
format | string | string an image format. valid options are: 'png', 'png32', 'png64', 'png128', 'png256', 'jpg70', 'jpg80', 'jpg90' |
Example:
// Downsample tiles for faster loading times on slow
// internet connections
var layer = L.mapbox.tileLayer('examples.map-20v6611k', {
format: 'jpg70'
});
Returns: the layer object
An L.mapbox.gridLayer
loads UTFGrid tiles of
interactivity into your map, which you can easily access with L.mapbox.gridControl
.
Options | Value | Description |
---|---|---|
id or url or tilejson (required) |
|
|
Example:
// the second argument is optional
var layer = L.mapbox.gridLayer('examples.map-20v6611k');
Returns a L.mapbox.gridLayer
object.
Returns this layer's TileJSON object which determines its tile source, zoom bounds and other metadata.
Example:
var layer = L.mapbox.gridLayer('examples.map-20v6611k')
// since layers load asynchronously through AJAX, use the
// `.on` function to listen for them to be loaded before
// calling `getTileJSON()`
.on('load', function() {
// get TileJSON data from the loaded layer
var TileJSON = layer.getTileJSON();
});
Returns: the TileJSON object
Load data for a given latitude, longitude point on the map, and call the callback function with that data, if any.
Options | Value | Description |
---|---|---|
latlng | object | latlng a [http://leafletjs.com/reference.html#latlng](L.LatLng object) |
callback | function | callback a function that is called with the grid data as an argument |
Returns: the L.mapbox.gridLayer object
L.mapbox.markerLayer
provides an easy way to integrate GeoJSON
from MapBox and elsewhere into your map.
Options | Value | Description |
---|---|---|
id or url or tilejson |
|
Must be either
|
options | object | If provided, it is the same options as provided to http://leafletjs.com/reference.html#featuregroup, as well as:
|
Example:
var markerLayer = L.mapbox.markerLayer(geojson)
.addTo(map);
Returns a L.mapbox.markerLayer
object.
Load GeoJSON data for this layer from the URL given by url
.
Options | Value | Description |
---|---|---|
url | string | A map id |
Example:
var markerLayer = L.mapbox.markerLayer()
.addTo(map);
markerLayer.loadURL('my_local_markers.geojson');
Returns: the layer object
Load marker GeoJSON data from a map with the given id
on MapBox.
Options | Value | Description |
---|---|---|
url (required) | string | A map id |
Example:
var markerLayer = L.mapbox.markerLayer()
.addTo(map);
// loads markers from the map `examples.map-0l53fhk2` on MapBox,
// if that map has markers
markerLayer.loadID('examples.map-0l53fhk2');
Returns: the layer object
Sets the filter function for this data layer.
Options | Value | Description |
---|---|---|
filter (required) | function | a function that takes GeoJSON features and returns true to show and false to hide features. |
Example:
var markerLayer = L.mapbox.markerLayer(geojson)
// hide all markers
.setFilter(function() { return false; })
.addTo(map);
Returns the markerLayer object.
Gets the filter function for this data layer.
Example:
var markerLayer = L.mapbox.markerLayer(geojson)
// hide all markers
.setFilter(function() { return false; })
.addTo(map);
// get the filter function
var fn = markerLayer.getFilter()
Returns the filter function.
Set the contents of a markers layer: run the provided features through the filter function and then through the factory function to create elements for the map. If the layer already has features, they are replaced with the new features. An empty array will clear the layer of all features.
Options | Value | Description |
---|---|---|
geojson (required) | object | features , an array of GeoJSON feature objects, or omitted to get the current value. |
Example:
var markerLayer = L.mapbox.markerLayer(geojson)
.addTo(map);
// a simple GeoJSON featureset with a single point
// with no properties
markerLayer.setGeoJSON({
type: "FeatureCollection",
features: [{
type: "Feature",
geometry: {
type: "Point",
coordinates: [102.0, 0.5]
},
properties: { }
}]
});
Returns the markerLayer object
Get the contents of this layer as GeoJSON data.
Returns the GeoJSON represented by this layer
A low-level interface to geocoding, useful for more complex uses and reverse-geocoding.
Options | Value | Description |
---|---|---|
id or url | string | Value must be
|
Returns a L.mapbox.geocoder
object.
Queries the geocoder with a query string, and returns its result, if any.
Options | Value | Description |
---|---|---|
queryString (required) | string | a query, expressed as a string, like 'Arkansas' |
callback (required) | function | a callback |
The callback is called with arguments
The result. This is an object with the following members:
{
results: // raw results
latlng: // a map-friendly latlng array
bounds: // geojson-style bounds of the first result
lbounds: // leaflet-style bounds of the first result
}
Returns: the geocoder object. The return value of this function is not useful - you must use a callback to get results.
Queries the geocoder with a location, and returns its result, if any.
Options | Value | Description |
---|---|---|
location (required) | object | A query, expressed as an object:
|
callback (required) | function | The callback is called with arguments
|
Returns: the geocoder object. The return value of this function is not useful - you must use a callback to get results.
A map control that shows legends added to maps in MapBox. Legends are auto-detected from active layers.
Options | Value | Description |
---|---|---|
options optional | object | An options object. Beyond the default options for map controls, this object has one special parameter: sanitizer : A function that accepts a string containing legend data, and returns a sanitized result for HTML display. The default will remove dangerous script content, and is recommended. |
Example:
var map = L.mapbox.map('map').setView([38, -77], 5);
map.addControl(L.mapbox.legendControl());
Returns: a L.mapbox.legendControl
object.
Adds a legend to the legendControl.
Options | Value | Description |
---|---|---|
legend required | string | legend data, a string which may contain HTML. It will be sanitized by the legendControl's sanitizer option. |
Removes a legend from the legendControl.
Options | Value | Description |
---|---|---|
legend required | string | legend data to remove. |
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.
Options | Value | Description |
---|---|---|
layer | L.mapbox.gridLayer | The first argument must be a layer created with L.mapbox.gridLayer() |
options | object | Valid options are:
|
Example:
var map = L.mapbox.map('map').setView([38, -77], 5);
var gridLayer = L.mapbox.gridLayer('examples.map-8ced9urs');
map.addLayer(L.mapbox.tileLayer('examples.map-8ced9urs'));
map.addLayer(gridLayer);
map.addControl(L.mapbox.gridControl(gridLayer));
Returns: a L.mapbox.gridControl
object.
Adds geocoder functionality as well as a UI element to a map. This uses the MapBox Geocoding API.
Options | Value | Description |
---|---|---|
id or url (required) | string | Either a
|
options | object | An options argument with the same options as the L.Control class , as well as:
|
Example:
var map = L.map('map')
.setView([37, -77], 5)
.addControl(L.mapbox.geocoderControl('examples.map-i875kd35'));
Returns a L.mapbox.geocoderControl
object.
Set the url used for geocoding.
Options | Value | Description |
---|---|---|
url | string | A geocoding url |
Returns: the geocoder control object
Set the map id used for geocoding.
Options | Value | Description |
---|---|---|
id | string | A map id to geocode from |
Returns: the geocoder control object
Set the TileJSON used for geocoding.
Options | Value | Description |
---|---|---|
tilejson | object | A Tilejson object |
Returns: the geocoder object
Bind a listener to an event emitted by the geocoder control. Supported additional events are
Options | Value | Description |
---|---|---|
event | string |
|
Adds a "Share" button to the map, which can be used to share the map to Twitter or Facebook, or generate HTML for a map embed.
Extends: L.Control
Options | Value | Description |
---|---|---|
id or url optional | string | Either a
|
options | object | Options for L.Control Also accepts the following options:
|
Example:
var map = L.map('map', 'examples.map-i875kd35')
.setView([37, -77], 5)
.addControl(L.mapbox.shareControl());
Returns:
Returns a L.mapbox.shareControl
object.
A core icon generator used in L.mapbox.marker.style
Options | Value | Description |
---|---|---|
feature | object | A GeoJSON feature object |
Returns:
A L.Icon
object with custom settings for iconUrl
, iconSize
, iconAnchor
,
and popupAnchor
.
An icon generator for use in conjunction with pointToLayer
to generate
markers from the MapBox Markers API
and support the simplestyle-spec for
features.
Options | Value | Description |
---|---|---|
feature | object | A GeoJSON feature object |
latlon | object | The latitude, longitude position of the marker |
Examples:
L.geoJson(geoJson, {
pointToLayer: L.mapbox.marker.style,
});
Returns:
A L.Marker
object with the latitude, longitude position and a styled marker
A HTML sanitization function, with the same effect as the default value of the sanitizer
option of L.mapbox.markerLayer
, L.mapbox.gridControl
, and L.mapbox.legendControl
.
Options | Value | Description |
---|---|---|
text | string | String of content you wish to sanitize. |
A mustache template rendering function, as used by the templating feature provided by L.mapbox.gridControl
.
Options | Value | Description |
---|---|---|
template | string | The template string |
data | object | Data you wish to pass into the template string |
Example:
var output = L.mapbox.template('Name: {{name}}', {name: 'John'});
// output is "Name: John"
Mapbox.js implements a simple, light style on all interaction elements. A dark theme
is available by applying class="dark"
to the map div.
Example:
<div id="map" class="dark"></div>