How web maps work

What you see when you view a map on Mapbox or an embedded map on your website is the result of many moving parts working together, from Mapbox servers, to a worldwide distribution system, to client code running in your browser.

This guide will walk you through how single tiles work together to create a web map.

Continuity in space and detail

Web maps are now so ubiquitous that it can be easy to forget the qualities that distinguish them from a typical paper city map or world atlas. When you browse a web map, the experience is like panning across a very large, continuous image. You can view New York, Paris, and Tokyo in the same contiguous space by panning (great distances) across the map. By zooming in and out, the amount of detail increases from country labels to city streets and buildings.

Instead of jumping between country, state, and city maps, web maps let you navigate with a single continuous system. Despite the name, this concept is shared by many mobile maps and there are just as many maps on the web that take the approach of an isolated paper map. Nevertheless, from here on out we’ll refer loosely to this approach as web maps.

Tiles and zoom levels

A continuous image of the world at street level detail would be millions of pixels wide – much too large to download or hold in memory at once. In reality, web maps are made up of many small, square images called tiles. These tiles are typically 256×256 pixels and are placed side-by-side in order to create the illusion of a very large seamless image.

single tile

The way that we can see more detail in maps, the difference between country-level maps and street maps, is zoom levels. Higher zoom levels increase the physical size of the displayed map but also increase the amount of detail shown.

To organize these millions of images, web maps use a simple coordinate system. Each tile has a z coordinate describing its zoom level and x and y coordinates describing its position within a square grid for that zoom level: z/x/y.

The very first tile in the web map system is at 0/0/0. Zoom level 0 covers the entire globe.

0/0/0

The very next zoom level divides z0 into four equal squares such that 1/0/0 and 1/1/0 cover the northern hemisphere while 1/0/1 and 1/1/1 cover the southern hemisphere.

1/0/0 1/1/0
1/0/1 1/1/1

Zoom levels are related to each other by powers of four:

  • z0 contains 1 tile.
  • z1 contains 4 tiles.
  • z2 contains 16 tile.

And so on.

Because of this exponential relationship the amount of detail increases at every zoom level, but so does the amount of bandwidth and storage required to serve up tiles.

For example, a map at z15, about when city building footprints first become visible, requires about 1.1 billion tiles to cover the entire world. At z17, just two zoom levels greater, the world requires 17 billion tiles.

Why tiles?

Put simply, web maps use tiles because they work well.

  • Tiled maps cache efficiently. If you download tiles of Manhattan to view a map of Central Park your browser can make use of those same tiles from cache instead of downloading them again when showing a map of Jersey City.
  • Tiled maps load progressively. Central Park will load before the outer edges of Manhattan letting you pan or zoom into a particular spot even if tiles at the edges of your map view haven’t finished loading.
  • Tiled maps are simple to use. The coordinate scheme describing map tiles is simple, making it easy to implement integrating technologies on the server, web, desktop, and mobile devices.

Map clients and tiles

Let’s say you want a map of Central Park. Since map tiles are images on the web, you could start by putting this HTML in your web page:

<img src='https://api.mapbox.com/v4/mapbox.streets/0/0/0.png?access_token=pk.eyJ1IjoibWFwYm94IiwiYSI6ImNpejY5YzJzczA2ejIzM29hNGQ3emFsMXgifQ.az9JUrQP7klCgD3W-ueILQ' />

You’ll see the 0/0/0 tile in your browser.

You’ll need to zoom in a lot more to focus in on Central Park. With a little HTML, CSS and JS wizardry, you could show a map of Central Park by:

  • Figuring out what z/x/y coordinates cover Manhattan at enough detail to show parks.
  • Adding a bunch of <img> tags to your page with appropriate CSS positioning to arrange them in the proper grid.
  • Adding zoom buttons and event handlers for drag events that zoom or pan and start the process all over again.

Thankfully, you don’t need to do any of this. This is what a map client does. A map client is a library, typically written in JavaScript, whose job is to figure out what tiles are needed when, download them from the map server, and position them correctly on a page. Mapbox.js is one example of a map client, though you can use many others.

A map client typically works by having an idea of your desired centerpoint and zoom level. You can enter in the coordinates of a location and Mapbox.js will figure out what tiles are needed.

Central Park’s coordinates are 40.783, -73.966 and 13 is a comfortable zoom level to view the park. We can use setView() to tell Mapbox.js to center the map on those coordinates and to zoom at that level.

<!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-two' class='map'> </div>
<script>
L.mapbox.accessToken = '<your access token here>';
L.mapbox.map('map-two', 'mapbox.streets').setView([40.783, -73.966], 13);
</script>
</body>
</html>
View source

Using Mapbox.js is much easier than sourcing and patching tiles by hand.

Next steps

Now that you know how web maps work, we recommend that you check out Mapbox GL JS fundamentals or learn about the Open platform.

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