--- layout: api title: v1.0.0 categories: api version: v1.0.0 navigation: - title: MapBox.js & Leaflet items: - title: L.mapbox.map items: - title: map.getTileJSON items: - title: L.mapbox.tileLayer items: - tileLayer.getTileJSON - tileLayer.setFormat - title: L.mapbox.gridLayer items: - gridLayer.getTileJSON - gridLayer.getData - title: L.mapbox.markerLayer items: - markerLayer.loadURL - markerLayer.loadID - markerLayer.setFilter - markerLayer.getFilter - markerLayer.setGeoJSON - markerLayer.getGeoJSON - title: L.mapbox.geocoder items: - geocoder.query - geocoder.reverseQuery - title: L.mapbox.legendControl items: - title: L.mapbox.gridControl items: - title: L.mapbox.geocoderControl items: - geocoderControl.setURL - geocoderControl.setID - geocoderControl.setTileJSON - geocoderControl.setErrorHandler - geocoderControl.getErrorHandler - title: L.mapbox.marker.icon items: - title: L.mapbox.marker.style items: --- {% raw %}

Map

L.mapbox.map(element: Element, id: string | url: string | tilejson: object, [options: object])

Create and automatically configure a map with layers, markers, and interactivity.

Arguments:

The first argument is required and must be the id of an element, or a DOM element reference.

The second argument is optional and can be:

The third argument is optional. 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

map.getTileJSON()

Returns this map's TileJSON object which determines its tile source, zoom bounds and other metadata.

Arguments: none

Returns: the TileJSON object

Layers

L.mapbox.tileLayer(id: string | url: string | tilejson: object, [options: object])

You can add a tiled layer to your map with L.mapbox.tileLayer(), a simple interface to layers from MapBox and elsewhere.

Arguments:

The first argument is required and must be:

The second argument is optional. If provided, it is the same options as provided to L.TileLayer with one addition:

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'
});

Returns a L.mapbox.tileLayer object.

tileLayer.getTileJSON()

Returns this layer's TileJSON object which determines its tile source, zoom bounds and other metadata.

Arguments: none

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

tileLayer.setFormat(format: string)

Set the image format of tiles in this layer. You can use lower-quality tiles in order to load maps faster

Arguments:

  1. 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

L.mapbox.gridLayer(id: string | url: string | tilejson: object, [options: object])

An L.mapbox.gridLayer loads UTFGrid tiles of interactivity into your map, which you can easily access with L.mapbox.gridControl.

Arguments:

The first argument is required and must be:

Example:

// the second argument is optional
var layer = L.mapbox.gridLayer('examples.map-20v6611k');

Returns a L.mapbox.gridLayer object.

gridLayer.getTileJSON()

Returns this layer's TileJSON object which determines its tile source, zoom bounds and other metadata.

Arguments: none

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

gridLayer.getData(latlng: LatLng, callback: function)

Load data for a given latitude, longitude point on the map, and call the callback function with that data, if any.

Arguments:

  1. latlng an L.LatLng object
  2. callback a function that is called with the grid data as an argument

Returns: the L.mapbox.gridLayer object

L.mapbox.markerLayer(id: string | url: string | tilejson: object, [options: object])

L.mapbox.markerLayer provides an easy way to integrate GeoJSON from MapBox and elsewhere into your map.

Arguments:

  1. required and must be:

  2. An id string examples.map-foo

  3. A URL to TileJSON, like http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json
  4. A GeoJSON object, from your own Javascript code

The second argument is optional. If provided, it is the same options as provided to L.FeatureGroup with one addition:

Example:

var markerLayer = L.mapbox.markerLayer(geojson)
    .addTo(map);

Returns a L.mapbox.markerLayer object.

markerLayer.loadURL(url: string)

Load GeoJSON data for this layer from the URL given by url.

Arguments:

  1. string a map id

Example:

var markerLayer = L.mapbox.markerLayer(geojson)
    .addTo(map);

markerLayer.loadURL('my_local_markers.geojson');

Returns: the layer object

markerLayer.loadID(id: string)

Load tiles from a map with the given id on MapBox.

Arguments:

  1. string a map id

Example:

var markerLayer = L.mapbox.markerLayer(geojson)
    .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

markerLayer.setFilter(filter: function)

Sets the filter function for this data layer.

Arguments:

  1. 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.

markerLayer.getFilter()

Gets the filter function for this data layer.

Arguments: none

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.

markerLayer.setGeoJSON(geojson: object)

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.

Arguments:

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

markerLayer.getGeoJSON()

Get the contents of this layer as GeoJSON data.

Arguments: none

Returns the GeoJSON represented by this layer

Geocoding

L.mapbox.geocoder(id: string | url: string)

A low-level interface to geocoding, useful for more complex uses and reverse-geocoding.

  1. (required) must be:

  2. An id string examples.map-foo

  3. A URL to TileJSON, like http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json

Returns a L.mapbox.geocoder object.

geocoder.query(queryString: string, callback: function)

Queries the geocoder with a query string, and returns its result, if any.

Arguments:

  1. (required) a query, expressed as a string, like 'Arkansas'
  2. (required) a callback

The callback is called with arguments

  1. An error, if any
  2. 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.

geocoder.reverseQuery(location: object, callback: function)

Queries the geocoder with a location, and returns its result, if any.

Arguments:

  1. (required) a query, expressed as an object:

      [lon, lat] // an array of lon, lat
      { lat: 0, lon: 0 } // a lon, lat object
      { lat: 0, lng: 0 } // a lng, lat object

The first argument can also be an array of objects in that form to geocode more than one item.

  1. (required) a callback

The callback is called with arguments

  1. An error, if any
  2. The result. This is an object of the raw result from MapBox.

Returns: the geocoder object. The return value of this function is not useful - you must use a callback to get results.

Controls

L.mapbox.legendControl()

A map control that shows legends added to maps in MapBox. Legends are auto-detected from active layers.

Arguments:

  1. (optional) an options object. Beyond the default options for map controls, this object has one special parameter:

  2. 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.

L.mapbox.gridControl()

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..

Arguments:

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.

L.mapbox.geocoderControl(id: string | url: string)

Adds geocoder functionality as well as a UI element to a map. This uses the MapBox Geocoding API.

This function is currently in private beta: contact MapBox before using this functionality.

Arguments:

  1. (required) either:

  2. An id string examples.map-foo

  3. A URL to TileJSON, like http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json

Example

var map = L.map('map')
    .setView([37, -77], 5)
    .addControl( L.mapbox.geocoder('examples.map-i875kd35'));

Returns a L.mapbox.geocoderControl object.

geocoderControl.setURL(url: string)

Set the url used for geocoding.

Arguments:

  1. a geocoding url

Returns: the geocoder control object

geocoderControl.setID(id: string)

Set the map id used for geocoding.

Arguments:

  1. a map id to geocode from

Returns: the geocoder control object

geocoderControl.setTileJSON(tilejson: object)

Set the TileJSON used for geocoding.

Arguments:

  1. A TileJSON object

Returns: the geocoder object

geocoderControl.setErrorHandler(errorhandler: function)

Set the function called if a geocoding request returns an error.

Arguments:

  1. a function that takes an error object - typically an XMLHttpRequest, and handles it.

Returns: the geocoder control object

geocoderControl.getErrorHandler()

Returns the current function used by this geocoderControl for error handling.

Arguments: none

Returns: the geocoder control's error handler

Markers

L.mapbox.marker.icon(feature: object)

A core icon generator used in L.mapbox.marker.style

Arguments:

  1. A GeoJSON feature object

Returns:

A L.Icon object with custom settings for iconUrl, iconSize, iconAnchor, and popupAnchor.

L.mapbox.marker.style(feature: object | latlon: object)

An icon generator for use in conjunction with pointToLayer to generate markers from the MapBox Markers API and support the simplestyle-spec for features.

Arguments:

  1. A GeoJSON feature object
  2. 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

Theming

Dark theme

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>
{% endraw %}