Creating raster maps with Leaflet¶

Free

Starter

Standard

Professional

Displaying a grid of image tiles is the traditional way of displaying electronic maps. Due to their nature, raster tiles are limited in functionality, such as the ability to create 3D effects or change styling on the fly, but some use cases or libraries require them.

Leaflet is a well-known, mature JavaScript mapping library with an active community and a variety of plugins, giving you plenty of room to grow. Most users will find that Leaflet works well for their use cases and has the added bonus of being super lightweight.

What if I have a more advanced use case?

We recommend using Leaflet for your raster maps unless you know you need something more advanced. For more complex geospatial applications, we typically recommend OpenLayers.

In this tutorial you'll learn how to build a simple raster map using Leaflet. We'll keep things simple and operate in the context of a simple web page.

Using a framework like React or Vue?

If you're using a framework, check out our quickstart tutorials specific to what you're using. We have tutorials for React and Vue.

Code¶

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

For local development on a web server at localhost or 127.0.0.1, you can get started without any API keys or domain setup!

For mobile, backend, and non-local web development, you'll need either domain auth or an API key. If you don't already have a Stadia Maps account, sign up for a free to get started.

Domain-based authentication

Domain-based authentication is the easiest form of authentication for production web apps. No additional application code is required, and you don't need to worry about anyone scraping your API keys. We recommend this for most browser-based applications.

Sign in to the client dashboard.
Click "Manage Properties."
Under "Authentication Configuration," click the button to add your domain.

API key authentication

Authenticating requests via API key¶

You can authenticate your requests by adding an API key to the query string or HTTP header.

The simplest is to add a query string parameter api_key=YOUR-API-KEY to your request URL. For example, to access the /tz/lookup API endpoint, your request URL might look like this.

Example URL with an API key placeholder

https://api.stadiamaps.com/tz/lookup/v1?lat=59.43696&lng=24.75357&api_key=YOUR-API-KEY

You can also use an Authorization HTTP header instead of a query string as shown below. Don't forget the Stadia-Auth prefix!

Example Authorization header with an API key placeholder

Authorization: Stadia-Auth YOUR-API-KEY

How to get an API key¶

Don't have an API key yet? Follow these easy steps!

Sign in to the client dashboard. (If you don't have an account yet, sign up for free; no credit card required!)
Click "Manage Properties."
If you have more than one property (ex: for several websites or apps), make sure you have selected the correct property from the dropdown at the top of the page.
Under "Authentication Configuration," you can generate, view or revoke your API key.

Video: How to generate your API key¶

To make experimenting even easier, we've packaged the example code as a JSFiddle playground. Click the "Try it in JSFiddle" button to start experimenting right from your web browser.

<!DOCTYPE html>
<html>
    <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 (Leaflet)</title>
        <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
        <script type="text/javascript" src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>
        <style type="text/css">
        html, body, #map {
            width: 100%;
            height: 100%;
            margin: 0;
        }
        </style>
    </head>
    <body>
        <div id="map"></div>
        <script type="text/javascript">
            // Initialize a map centered at (53, 12) at zoom level 5
            var map = L.map('map').setView([53, 12], 5);

            // Style URL format in XYZ PNG format; see our documentation for more options
            L.tileLayer('https://tiles.stadiamaps.com/tiles/alidade_smooth/{z}/{x}/{y}{r}.png', {
                maxZoom: 20,
                attribution: '&copy; <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a>, &copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a> &copy; <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a>',
            }).addTo(map);
        </script>
    </body>
</html>

Code Walkthrough¶

First, we'll add some opening HTML content that will make the document standard compliant:

<!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 (Leaflet)</title>

Next, we'll include the Leaflet libraries:

        <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" />
        <script type="text/javascript" src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js"></script>

Now, we'll add some CSS to handle the size of the map class and then close the <head> tag:

         <style type="text/css">
         html, body, #map {
             width: 100%;
             height: 100%;
             margin: 0;
         }
         </style>
     </head>

With the <head> details in, we can now add the body for our page. This is where we'll create the map element:

     <body>
         <div id="map"></div>

Next, we'll add the JavaScript for:

initializing the map, including its center point and zoom level:

         <script type="text/javascript">
         // Initialize a map centered at (53, 12) at zoom level 5
         var map = L.map('map').setView([53, 12], 5);

styling it with Alidade Smooth raster tiles:

          // Style URL format in XYZ PNG format; see our map style library for more options: https://docs.stadiamaps.com/themes/
          // Be sure to include the `{r}` placeholder as shown below to support retina screens.
          L.tileLayer('https://tiles.stadiamaps.com/tiles/alidade_smooth/{z}/{x}/{y}{r}.png', {
              maxZoom: 20,

and adding proper attribution, drawing it to the map element, and closing the <script> tag:

                   attribution: '&copy; <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a>, &copy; <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a> &copy; <a href="https://www.openstreetmap.org/copyright" target="_blank">OpenStreetMap</a>',
               }).addTo(map);
       </script>

Finally, we'll close up the <body>, and <html> tags:

                </body>
            </html>

And that's it. Congratulations!

All the code, put together, will match the code at the start of this tutorial. Now you can play around with the starting point, zoom level, and styles to customize the map to your liking.

Next Steps¶

This tutorial doesn't even begin to show what's possible with Leaflet. Now that you have a map, you can get inspiration from what others have built at the Leaflet Examples page. They have in-depth examples covering everything from custom markers to interactive choropleth maps. And don't forget to check out the plugins and the rest of the Leaflet documentation either.

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