Translate your project from Google to Mapbox

Are you using Google Maps and searching for the equivalent code in the Mapbox JavaScript API? You’ve come to the right place.

This guide walks you through examples in the Google Maps API v3 and then shows you how to do it in Mapbox.js.

Getting started

To start, you’ll need the latest version of Mapbox.js and CSS. You can link directly to the Mapbox hosted versions by copying this snippet into the head of your HTML document.

<script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
<link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />

You’ll also need to set an access token. Reference your access token by adding this snippet of code to your HTML.

L.mapbox.accessToken = '<your access token here>';

In each of the examples below, we’ll show you how Google does it and then we’ll show you how it’s done with Mapbox.

New to Mapbox.js? You might want to take a look at our Extending with Mapbox.js guide.

Initializing a map

To add a web map to a page, you need to initialize it first.

// Google
var map = new google.maps.Map(document.getElementById('map'), {
  center: new google.maps.LatLng(40.718217, -73.998284),
  zoom: 13,
  mapTypeId: google.maps.MapTypeId.ROADMAP
});

Mapbox initializes a map with L.mapbox.map.

// Mapbox
var map = L.mapbox.map('map', 'mapbox.streets')
  .setView([40.718217, -73.998284], 13);
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-init' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-init', 'mapbox.streets')
  .setView([40.718217, -73.998284], 13);
</script>
</body>
</html>
View source

For this guide, we’ll use the map variable in examples to represent this initialized map.

Adding a marker

You can create a single marker on a map by creating a marker object.

// Google
var marker = new google.maps.Marker({
  position: new google.maps.LatLng(40.718217, -73.998284),
  map: map
});

With Mapbox, you can drop a marker using L.Marker and then add it to a map with addLayer.

// Mapbox
var marker = new L.Marker(new L.LatLng(40.718217, -73.998284));
map.addLayer(marker);
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-marker' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-marker', 'mapbox.streets')
  .setView([40.718217, -73.998284], 13);
var marker = new L.Marker(new L.LatLng(40.718217, -73.998284));
map.addLayer(marker);
</script>
</body>
</html>
View source

Adding a custom marker

If you don’t like the marker icon, you can swap it for an image.

// Google
var marker = new google.maps.Marker({
  position: new google.maps.LatLng(40.718217, -73.998284),
  map: map,
  icon: 'https://bit.ly/QIMos7'
});

To get your custom marker working, Mapbox uses L.icon().

// Mapbox
var marker = L.icon({
  iconUrl: 'https://bit.ly/QIMos7',
  iconAnchor: [20, 50]
});

L.marker([40.718217, -73.998284], { icon: marker }).addTo(map);
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-custom' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-custom', 'mapbox.streets')
  .setView([40.718217, -73.998284], 13);
var marker = L.icon({
  iconUrl: 'https://www.mapbox.com/help/img/screenshots/rocket.png',
  iconAnchor: [20, 50]
});

L.marker([40.718217, -73.998284], { icon: marker }).addTo(map);
</script>
</body>
</html>
View source

Modifying map controls

Removing default controls

Most map controls are added by default, but you can remove them with a little code. In this example, we’ll remove the zoom controls.

// Google
var map = new google.maps.Map(document.getElementById('map'), {
  zoom: 13,
  center: new google.maps.LatLng(40.718217, -73.998284),
  zoomControl: false
});

With Mapbox, you can also set zoomControl to false.

// Mapbox
var map = L.mapbox.map('map', 'mapbox.streets', {
  zoomControl: false
}).setView([40.718217, -73.998284], 13);
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-zoom' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-zoom', 'mapbox.streets', {
  zoomControl: false
}).setView([40.718217, -73.998284], 13);
</script>
</body>
</html>
View source

Control position

Don’t like where the map controls are located? You can reposition them. In this example, we’ll move the zoom in and out buttons to the bottom left corner of the map.

// Google
var map = new google.maps.Map(document.getElementById('map'), {
  zoom: 13,
  center: new google.maps.LatLng(40.718217, -73.998284),
  zoomControlOptions: {
    position: google.maps.ControlPosition.BOTTOM_LEFT
  }
});

Mapbox rearranges the controls with L.Control.

// Mapbox
var map = L.mapbox.map('map', 'mapbox.streets')
  .setView([40.718217, -73.998284], 13);
map.zoomControl.setPosition('bottomleft');
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-position' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-position', 'mapbox.streets')
  .setView([40.718217, -73.998284], 13);
map.zoomControl.setPosition('bottomleft');
</script>
</body>
</html>
View source

Adding GeoJSON

If you have a GeoJSON file filled with your own data, then you can load the features on a map.

// Google
map.data.loadGeoJson('/help/data/examples/data.geojson');

Mapbox will house your data in the featureLayer object with the loadURL method.

// Mapbox
L.mapbox.featureLayer()
  .loadURL('/help/data/examples/data.geojson')
  .addTo(map);
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-json' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-json', 'mapbox.streets')
  .setView([38.8929, -77.0252], 14);
L.mapbox.featureLayer()
  .loadURL('/help/data/examples/data.geojson')
  .addTo(map);
</script>
</body>
</html>
View source

Styling a map

To give your map some personality, you can style it. Google Maps stores styles in an array of objects that target map features.

// Google
var stylesArray = [
  {
    featureType: '',
    elementType: '',
    stylers: [
      { hue: '' },
      { saturation: '' },
      { lightness: '' },
      // etc...
    ]
  },
  {
    featureType: '',
    // etc...
  }
];

map.setOptions({ styles: stylesArray });

With Mapbox, you have a few options to customize maps and features.

Any customized project created in the Mapbox Editor or uploaded from Mapbox Studio Classic will have a Map ID. Use the Map ID when initializing the map to add it as the active layer.

// Mapbox
L.mapbox.map('map', 'mapbox.streets');
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-styled' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-styled', 'mapbox.streets');
</script>
</body>
</html>
View source

Geocoding

You can convert addresses to coordinates with geocoding. This example geocodes New York City and places a marker on the map based on the first result returned.

// Google
var geocoder = new google.maps.Geocoder();
geocoder.geocode({ address: 'New York City' }, function(results, status) {
  if (status === google.maps.GeocoderStatus.OK) {
    map.setCenter(results[0].geometry.location);
    var marker = new google.maps.Marker({
      map: map,
      position: results[0].geometry.location
    });
  }
});

With Mapbox, L.mapbox.geocoder() will gladly geocode your addresses.

// Mapbox
var geocoder = L.mapbox.geocoder('mapbox.places-v1');
geocoder.query('New York City', showMap);

function showMap(err, data) {
  if (err) throw err;
  if (data.lbounds) {
    map.fitBounds(data.lbounds);
    var marker = L.marker([data.latlng[0], data.latlng[1]]).addTo(map);
  } else if (data.latlng) {
    map.setView([data.latlng[0], data.latlng[1]], 13);
  }
}
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-geocoding' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var geocoder = L.mapbox.geocoder('mapbox.places-v1');
var mapG = L.mapbox.map('map-geocoding', 'mapbox.streets');
geocoder.query('New York City', showMap);
function showMap(err, data) {
  if (err) throw err;
  if (data.lbounds) {
    mapG.fitBounds(data.lbounds);
    var marker = L.marker([data.latlng[0], data.latlng[1]]).addTo(mapG);
  } else if (data.latlng) {
    mapG.setView([data.latlng[0], data.latlng[1]], 13);
  }
}
</script>
</body>
</html>
View source

Drawing

You can even add controls to your map to draw features.

// Google
var draw = new google.maps.drawing.DrawingManager();
draw.setMap(map);

Mapbox teams up with Leaflet’s draw plugin to provide you with similar interactive draw tools.

// Mapbox
L.control.draw().addTo(map);
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-drawing' class='map'> </div>
<link href='https://api.mapbox.com/mapbox.js/plugins/leaflet-draw/v0.2.2/leaflet.draw.css' rel='stylesheet' />
<script src='https://api.mapbox.com/mapbox.js/plugins/leaflet-draw/v0.2.2/leaflet.draw.js'></script>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-drawing', 'mapbox.streets')
  .setView([38.89399, -77.03659], 17);
var featureGroup = L.featureGroup().addTo(map);
var circleOptions = {
  color: '#fff',      // Stroke color
  opacity: 1,         // Stroke opacity
  weight: 10,         // Stroke weight
  fillColor: '#000',  // Fill color
  fillOpacity: 0.6    // Fill opacity
};
var circleOne = L.circle([38.89415, -77.03738], 20, circleOptions).addTo(featureGroup);
var circleTwo = L.circle([38.89415, -77.03578], 20, circleOptions).addTo(featureGroup);
var linePoints = [
  [38.893596444352134, -77.0381498336792],
  [38.89337933372204, -77.03792452812195],
  [38.89316222242831, -77.03761339187622],
  [38.893028615148424, -77.03731298446655],
  [38.892920059048464, -77.03691601753235],
  [38.892903358095296, -77.03637957572937],
  [38.89301191422077, -77.03592896461487],
  [38.89316222242831, -77.03549981117249],
  [38.89340438498248, -77.03514575958252],
  [38.893596444352134, -77.0349633693695]
];

var polylineOptions = {
  color: '#000'
};
var polyline = L.polyline(linePoints, polylineOptions).addTo(featureGroup);

var drawControl = new L.Control.Draw({
  edit: {
    featureGroup: featureGroup
  }
}).addTo(map);

map.on('draw:created', function(e) {
  featureGroup.addLayer(e.layer);
});
</script>
</body>
</html>
View source

Event handling

You can make your map do something on a mouseover, click, or drag with event handling. For example, you can create a double click event to alert you with the latitude and longitude of a particular spot on the map.

// Google
google.maps.event.addListener(map, 'dblclick', function(event) {
  alert('LatLng(' + event.latLng.lat() + ', ' + event.latLng.lng() + ')');
});

Mapbox supports these events, too. Read map events to learn more about the supported methods.

// Mapbox
map.on('dblclick', function(e) {
  alert(e.latlng);
});
<!DOCTYPE html>
<html>
<head>
  <meta charset=utf-8 />
  <title></title>
  <script src='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.js'></script>
  <link href='https://api.mapbox.com/mapbox.js/v3.0.1/mapbox.css' rel='stylesheet' />
  <style>
    body { margin:0; padding:0; }
    .map { position:absolute; top:0; bottom:0; width:100%; }
  </style>
</head>
<body>
<div id='map-event' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
var map = L.mapbox.map('map-event', 'mapbox.streets', {
  doubleClickZoom: false
})
.setView([42, -72], 4);
map.on('dblclick', function(e) {
  alert(e.latlng);
});
</script>
</body>
</html>
View source

Static maps

You access maps without JavaScript with static maps. Static maps are images of maps. Customize the URL with your parameters and then use it like you would an image.

<!-- Google -->
<img src='https://maps.googleapis.com/maps/api/staticmap?center=40.714728,-73.998672&zoom=12&size=640x300&sensor=false' alt='Google map'>

Google map

The Mapbox static API has a similar format.

<!-- Mapbox -->
<img src='https://api.mapbox.com/v4/mapbox.streets/-73.998672,40.714728,12/640x300.png?access_token=<your access token>' alt='Mapbox map'>

Mapbox map

Next steps

Now that you’re mapping with Mapbox, have a look at Mapbox.js examples to learn ways to build completely interactive web applications.

Next article:

Build a store locator using Mapbox.js

Let's build a map application with Mapbox.js. This guide walks you through all the code that you need to build a store locator.

Additional questions? Ask our support team or learn more about How Mapbox Works.