Skip to content

Creating raster maps with OpenLayers

Free

Starter

Standard

Professional

OpenLayers is a popular, mature, feature rich JavaScript mapping library. It integrates seamlessly with OGC mapping services, supports vector layers in multiple formats, and a lot more. If you're a GIS professional, OpenLayers probably needs no introduction.

Looking for something really simple?

Check out Leaflet! It's extremely easy to use, has a great plugin ecosystem, and suits most use cases quite well.

In this tutorial you'll learn how to build a simple raster map using OpenLayers. We'll keep things straightforward and operate in the context of a plain web page, but this works equally well with JavaScript build tooling and npm.

Code

Let's dive in with some example code on how to use our raster tiles in OpenLayers.

If you are implementing the code locally, nothing special is required. If you are developing outside of localhost, only a free account is required. You can learn more about our accounts and authentication here.

You can play around immediately with the example code by clicking on the Try it in JSFiddle link. A new tab will open, allowing you to interact with the map, along with making adjustments to the code.

OpenLayers v8.0.0 and newer

Since OpenLayers v8.0.0, Stadia Maps is a built-in tile source!

Try it in JSFiddle 
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <title>Raster Map Demo (OpenLayers)</title>

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@9.1.0/ol.min.css" type="text/css">
    <script src="https://cdn.jsdelivr.net/npm/ol@9.1.0/dist/ol.js"></script>

    <style type="text/css">
      html, body, #map {
          width: 100%;
          height: 100%;
          margin: 0;
        }
    </style>
  </head>
  <body>
    <div id="map" class="map"></div>
    <script type="text/javascript">
      const map = new ol.Map({
        target: 'map',
        layers: [
          new ol.layer.Tile({
            source: new ol.source.StadiaMaps({
              // See our gallery for more styles: https://docs.stadiamaps.com/themes/
              layer: 'stamen_toner',
              retina: true,  // Set to false for stamen_watercolor
            }),
          }),
        ],
        view: new ol.View({
          center: ol.proj.fromLonLat([-122.416667, 37.783333]),
          zoom: 14
        })
      });
    </script>
  </body>
</html>

OpenLayers versions older than v8.0.0

If you're using an earlier version, it's still quite easy to add our tiles as an XYZ source.

Try it in JSFiddle 
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />
    <title>Raster Map Demo (OpenLayers)</title>

    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@7.4.0/ol.min.css" type="text/css">
    <script src="https://cdn.jsdelivr.net/npm/ol@7.4.0/dist/ol.js"></script>

    <style type="text/css">
      html, body, #map {
          width: 100%;
          height: 100%;
          margin: 0;
        }
    </style>
  </head>
  <body>
    <div id="map" class="map"></div>
    <script type="text/javascript">
      const map = new ol.Map({
        target: 'map',
        layers: [
          new ol.layer.Tile({
            // Configure an XYZ source
            source: new ol.source.XYZ({
              // See our style gallery for more: https://docs.stadiamaps.com/themes/
              url: 'https://tiles.stadiamaps.com/tiles/stamen_toner/{z}/{x}/{y}@2x.png',
              attributions: [
                '&copy; <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a>',
                '&copy; <a href="https://stamen.com/" target="_blank">Stamen Design</a>',  // Required for Stamen styles
                '&copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a>',
                '&copy; <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a>'
              ],
              tilePixelRatio: 2,  // Set to 2 for retina/hidpi tiles. Not supported by Stamen Watercolor.
              maxZoom: 20  // Max zoom should be 16 for Stamen Watercolor
            })
          })
        ],
        view: new ol.View({
          center: ol.proj.fromLonLat([-122.416667, 37.783333]),
          zoom: 14
        })
      });
    </script>
  </body>
</html>

Next Steps

This tutorial doesn't even begin to show what's possible with OpenLayers. Now that you have a map, you can get inspiration from what others have built at the OpenLayers Examples page or work through a comprehensive overview of the library through the OpenLayers Workshop.

Once you're ready to move beyond localhost testing, sign up for a free Stadia Maps account, and we'll walk through the next steps.

Get Started With a Free Account