API reference

mapzen.js is an open-source JavaScript SDK and an extension of Leaflet for making maps for the web and mobile devices. mapzen.js simplifies the process of using Mapzen’s maps within Leaflet.

API key

mapzen.js requires an API key for access to Mapzen services. These services include Mapzen Search and the vector tile service used by Mapzen Basemaps.

While rate limits apply to each service individually, mapzen.js allows one global key to be set and used by all services. (Don’t worry–sharing the same API key between different services will not affect individual rate limits. They don’t share limits.) Find out more about how to get started or sign up for your own key now.

Define your API key before adding other Mapzen components by setting:

L.Mapzen.apiKey = 'your-mapzen-api-key';


L.Mapzen.map extends Leaflet L.Map with additional options.


Option Type Default Description
apiKey String L.Mapzen.apiKey Mapzen API key to be used for the components.
attribution String © <a href="https://www.mapzen.com/rights">Mapzen</a>, <a href="https://openstreetmap.org/copyright">OpenStreetMap</a>, and <a href="https://www.mapzen.com/rights/#services-and-data-sources">others</a> Attribution data in a small text box. Leaflet attribution is always there; attribution from this option is placed before Leaflet attribution.
debugTangram Boolean false Whether to load the debug (non-minified) version of Tangram or not.
Deprecated; no longer works from v0.9.
fallbackTile L.TileLayer L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {}) TileLayer to fall back when WebGL is not available.
iframeDetection Boolean false Whether to turn off scroll zoom when the map is in an iframe.
scene String L.Mapzen.BasemapStyles.BubbleWrap Tangram scene URL, included in L.Mapzen.BasemapStyles object.
scene can also be a single-quoted URL that points to any .yaml Tangram scene file
Deprecated; will be removed in v1.0. See tangramOptions below.
tangramOptions Object See below See tangramOptions below


Set of options related to the appearance and behavior of the Tangram layer. In addition to the options below, tangramOptions may also include any of the options available in the Tangram options object.

Option Type Default Description
debug Boolean false Whether to load the debug (non-minified) version of Tangram or not. Deprecated; no longer works from v0.9. Use non-minified mapzen.js to load non-minified Tangram
scene String L.Mapzen.BasemapStyles.BubbleWrap Tangram scene URL, included in L.Mapzen.BasemapStyles object.
scene can also be a single-quoted URL that points to any .yaml Tangram scene file
apiKey String L.Mapzen.apiKey Mapzen API key to be used for Vector Tiles.


var map = L.Mapzen.map('map', {
  tangramOptions: {
    debug: true,
    scene: 'my-scene-file.yaml'


Method Returns Description
getTangramLayer Tangram Leaflet Layer Returns current TangramLayer added to the map.

Example of how to use the getTangramLayer method to access Tangram’s scene object:

var tangramLayer = map.getTangramLayer();


All of Leaflet’s event methods are available, such as on, off, or once. In addition, mapzen.js provides these events:

Event Description
tangramloaded Fired when a Tangram layer is loaded in the map. This event allows user to access to TangramLayer through event.tangramLayer Deprecated;will be removed in v1.0. Please use getTangramLayer instead.

For access to Tangram’s scene object or config object (interfaces for controlling your Tangram scene at runtime), listen for the tangramloaded event on the map. It is available as a property of the Tangram Leaflet layer, which you will find in the event property tangramLayer.

Example of how to use the tangramloaded event to access Tangram’s scene object:

// tangramloaded event is deprecated. Please use getTangramLayer
map.on('tangramloaded', function (event) {
  var scene = event.tangramLayer.scene;

Draw a map with a map component

You can pass one of Mapzen’s basemap styles as the scene via tangramOptions, or you can provide the path to your own Tangram scene file. If there is no scene file declared, mapzen.js will default to BubbleWrap.


var map = L.Mapzen.map('map', {
  center: [40.74429, -73.99035],
  zoom: 15,
  tangramOptions: {
    scene: L.Mapzen.BasemapStyles.Refill

The center parameter sets the center point of the map ([latitude, longitude]), in decimal degrees. The next line sets the zoom level, which is like a map scale or resolution. A small zoom level will show a larger area in less detail, and a larger zoom level value depicts smaller area in greater detail.

The scene: L.Mapzen.BasemapStyles.Refill line sets the style used for the map. In this case, it is Mapzen’s Refill style, which provides a high contrast, black & white basemap useful for data visualization.

Basemap styles

mapzen.js provides a set of constants for easier access to Mapzen’s basemap styles. These are available under the L.Mapzen.BasemapStyles namespace.

Constant Value
BubbleWrap https://mapzen.com/carto/bubble-wrap-style/7/bubble-wrap-style.zip
BubbleWrapMoreLabels https://mapzen.com/carto/bubble-wrap-style-more-labels/7/bubble-wrap-style-more-labels.zip
BubbleWrapNoLabels https://mapzen.com/carto/bubble-wrap-style-no-labels/7/bubble-wrap-style-no-labels.zip
Cinnabar https://mapzen.com/carto/cinnabar-style/7/cinnabar-style.zip
CinnabarMoreLabels https://mapzen.com/carto/cinnabar-style-more-labels/7/cinnabar-style-more-labels.zip
CinnabarNoLabels https://mapzen.com/carto/cinnabar-style-no-labels/7/cinnabar-style-no-labels.zip
Refill https://mapzen.com/carto/refill-style/7/refill-style.zip
RefillMoreLabels https://mapzen.com/carto/refill-style-more-labels/7/refill-style-more-labels.zip
RefillNoLabels https://mapzen.com/carto/refill-style-no-labels/7/refill-style-no-labels.zip
Zinc https://mapzen.com/carto/zinc-style/6/zinc-style.zip
ZincMoreLabels https://mapzen.com/carto/zinc-style-more-labels/6/zinc-style-more-labels.zip
ZincNoLabels https://mapzen.com/carto/zinc-style-no-labels/6/zinc-style-no-labels.zip
Walkabout https://mapzen.com/carto/walkabout-style/5/walkabout-style.zip
WalkaboutMoreLabels https://mapzen.com/carto/walkabout-style-more-labels/5/walkabout-style-more-labels.zip
WalkaboutNoLabels https://mapzen.com/carto/walkabout-style-no-labels/5/walkabout-style-no-labels.zip
Tron https://mapzen.com/carto/tron-style/4/tron-style.zip
TronMoreLabels https://mapzen.com/carto/tron-style-more-labels/4/tron-style-more-labels.zip
TronNoLabels https://mapzen.com/carto/tron-style-no-labels/4/tron-style-no-labels.zip


var map = L.Mapzen.map('map', {
  tangramOptions: {
    scene: L.Mapzen.BasemapStyles.Refill

Learn more about Mapzen basemaps and options for customization in Mapzen’s Cartography documentation.

Note: L.Mapzen.HouseStyles has been deprecated for L.Mapzen.BasemapStyles. Starting with mapzen.js 1.0, you must use only L.Mapzen.BasemapStyles.

Geocoder control

Add a Mapzen Search box, also known as the geocoder, to your map to allow your map users to quickly jump to anywhere in the world.


var geocoder = L.Mapzen.geocoder('your-mapzen-api-key');

The geocoder has many options for customization. See the Geocoder API reference for more information.

Note: Mapzen Search requires an API key. Get your free API key through the Mapzen developer portal.

Bug (“Scarab”) Control

L.Mapzen.bug implements a small header for Mapzen demos, with the company logo and social media links. It provides Mapzen attribution, a link to the Mapzen website, and provides a way for viewers to share the map. It is mostly intended for Mapzen internal use.

The term bug is borrowed from broadcast television (officially, “digital on-screen graphic”) where a show is branded in the lower corner to identify the broadcast network.


  name: 'Web Map',
  link: 'https://erasermap.com/maps',
  tweet: '@mapzen',
  repo: 'https://github.com/mapzen/web-map'


Option Type Default Description
name String 'Web Map' Name of this map.
link String 'https://erasermap.com/maps' Permalink to this map.
tweet String '{name}, powered by @mapzen' Default tweet text for Twitter button.
repo String 'https://github.com/mapzen/' GitHub link for map source code.

Locator control

L.Mapzen.locator adds a geolocation control to the map. This integrates the Leaflet.Locate control. See the Leaflet.Locate documentation for additional options.


var locator = L.Mapzen.locator();

Hash control

L.Mapzen.hash adds a URL hash to a map, so you can link to map location and state. The Hash function accepts components whose state can be linked.


  map: map


Option Type Default Description
map L.Mapzen.map null Instance of map.
geocoder L.Mapzen.geocoder null Instance of geocoder.