### developers

## MapBox.js v1.4.0

Viewing an older version of MapBox.js. Check out v1.5.0 for the latest.

## Reading this Documentation

MapBox.js is built on top of Leaflet and should be read in conjunction with the Leaflet API reference.

The documentation is organized by methods. Each method is shown with potential arguments along with it's type and description in a table. When the API has a Javascript constructor function that returns an object, the constructor is documented with its full name and the methods 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.

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, or book. If you'd like to learn more about maps, we've provided a helpful article explaining how web maps work.

### The `ready` event

MapBox.js is asynchronous - when you create a layer like `L.mapbox.tileLayer('examples.map-9ijuk24y')`, the layer doesn't immediately know which tiles to load and its attribution information. Instead, it loads the information in 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-9ijuk24y');
      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:

      var layer = L.mapbox.tileLayer('examples.map-9ijuk24y');
      layer.on('error', function(err) { // Handle error });

# Map

## L.mapbox.map(element, id | url | tilejson, options)

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

- `string` if id or url
- `object` if tilejson

url can be

- a map `id` string `examples.map-foo`
- a URL to TileJSON, like `http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json`
- a TileJSON object, from your own Javascript code

options

object

If provided, it is the same options as provided to L.Map with the following additions:

- `tileLayer` (boolean). Whether or not to add a `L.mapbox.tileLayer` based on the TileJSON. Default: `true`
- `markerLayer` (boolean). Whether or not to add a `L.mapbox.markerLayer` based on the TileJSON. Default: `true`.
- `gridLayer` (boolean). Whether or not to add a `L.mapbox.gridLayer` based on the TileJSON. Default: `true`.
- `legendControl` (boolean). Whether or not to add a `L.mapbox.legendControl`. Default: `true`.

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.

Returns: the TileJSON object

# Layers

## L.mapbox.tileLayer(id | url | tilejson, options)

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)

- `string` if id or url
- `object` if tilejson

Value must be

- An `id` string `examples.map-foo`
- A URL to TileJSON, like `http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json`
- A TileJSON object, from your own Javascript code

options

object

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

- `retinaVersion`, if provided, is an alternative value for the first argument to `L.mapbox.tileLayer` which, if retina is detected, is used instead.

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.

### tileLayer.getTileJSON()

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

### tileLayer.setFormat(format)

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

## L.mapbox.gridLayer(id | url | tilejson, options)

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)

- `string` if id or url
- `object` if tilejson

- An `id` string `examples.map-foo`
- A URL to TileJSON, like `http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json`
- A TileJSON object, from your own Javascript code

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.

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, callback)

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(id | url | tilejson, options)

`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

- `string` if id or url
- `object` if tilejson

Must be either

- An id string examples.map-foo
- A URL to TileJSON, like `http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json`
- A GeoJSON object, from your own Javascript code
- `null`, if you wish to only provide `options` and not initial data.

options

object

If provided, it is the same options as provided to http://leafletjs.com/reference.html#featuregroup, as well as:

- `filter`: A function that accepts a feature object and returns `true` or `false` to indicate whether it should be displayed on the map. This can be changed later using `setFilter`.
- `sanitizer`: A function that accepts a string containing tooltip data, and returns a sanitized result for HTML display. The default will remove dangerous script content, and is recommended.

Example:

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

Returns a `L.mapbox.markerLayer` object.

### markerLayer.loadURL(url)

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

### markerLayer.loadID(id)

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

### markerLayer.setFilter(filter)

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.

### markerLayer.getFilter()

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.

### markerLayer.setGeoJSON(geojson)

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

### markerLayer.getGeoJSON()

Get the contents of this layer as GeoJSON data.

Returns the GeoJSON represented by this layer

# Geocoding

## L.mapbox.geocoder(id | url)

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

Options | Value | Description
--- | --- | ---

id or url

string

Value must be

- An `id` string `examples.map-foo`
- A URL to TileJSON, like `http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json`

Returns a `L.mapbox.geocoder` object.

### geocoder.query(queryString, callback)

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

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, callback)

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

Options | Value | Description
--- | --- | ---

location (required)

object

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.

callback (required)

function

The callback is called with arguments

- An error, if any
- 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(options)

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.

### legendControl.addLegend(legend)

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.

### legendControl.removeLegend(legend)

Removes a legend from the legendControl.

Options | Value | Description
--- | --- | ---
legend required | string | legend data to remove.

## L.mapbox.gridControl(layer, options)

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:

- `sanitizer`: A function that accepts a string containing interactivity data, and returns a sanitized result for HTML display. The default will remove dangerous script content, and is recommended.
- `template`: A string in the Mustache template language that will be evaluated with data from the grid to produce HTML for the interaction.
- `follow`: Whether the tooltip should follow the mouse in a constant relative position, or should be fixed in the top-right side of the map. By default, this is `false` and the tooltip is stationary.
- `pinnable`: Whether clicking will 'pin' the tooltip open and expose a 'close' button for the user to close the tooltip. By default, this is `true`.
- `touchTeaser`: On touch devices, show the teaser formatter if there is no output from the full formatter. By default, this is `true`.
- `location`: Evaluate the location formatter on click events, and if it provides output, navigate to that location. By default, this is `true`.

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 | url, options)

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.

Options | Value | Description
--- | --- | ---

id or url (required)

string

Either a

- An `id` string `examples.map-foo`
- A URL to TileJSON, like `http://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json`

options

object

An options argument with the same options as the `L.Control class`, as well as:

- `keepOpen`: a boolean for whether the control will stay open always rather than being toggled. Default `false`.

Example:

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

Returns a `L.mapbox.geocoderControl` object.

### geocoderControl.setURL(url)

Set the url used for geocoding.

Options | Value | Description
--- | --- | ---
url | string | A geocoding url

Returns: the geocoder control object

### geocoderControl.setID(id)

Set the map id used for geocoding.

Options | Value | Description
--- | --- | ---
id | string | A map id to geocode from

Returns: the geocoder control object

### geocoderControl.setTileJSON(tilejson)

Set the TileJSON used for geocoding.

Options | Value | Description
--- | --- | ---
tilejson | object | A Tilejson object

Returns: the geocoder object

### geocoderControl.on(event, callback)

Bind a listener to an event emitted by the geocoder control. Supported additional events are

Options | Value | Description
--- | --- | ---

event

string

- `found`: success in finding a location. Called with a single argument, the result.
- `error`: failure to find a location. Called with the raw HTTP error from MapBox.

## L.mapbox.shareControl(id | url, options)

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

- `id` string `examples.map-foo`
- A URL to TileJSON, like `https://a.tiles.mapbox.com/v3/examples.map-0l53fhk2.json` If not supplied, the TileJSON from the map is used.

options

object

Options for L.Control Also accepts the following options:

- url: the `URL` of a page to which the share control will link instead of the URL of the current page or that specified in TileJSON data.

Example:

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

Returns: Returns a `L.mapbox.shareControl` object.

# Markers

## L.mapbox.marker.icon(feature)

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

## L.mapbox.marker.style(feature, latlon)

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

# Utility

## L.mapbox.sanitize(string)

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.

## L.mapbox.template(template, data)

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"

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

The code and documentation to mapbox.js is hosted on GitHub where you can contribute changes and improvements.