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.
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.
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!
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.
OpenLayers v8.0.0 and newer¶
Since OpenLayers v8.0.0, Stadia Maps is a built-in tile source!
<!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.
<!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: [
'© <a href="https://stadiamaps.com/" target="_blank">Stadia Maps</a>',
'© <a href="https://stamen.com/" target="_blank">Stamen Design</a>', // Required for Stamen styles
'© <a href="https://openmaptiles.org/" target="_blank">OpenMapTiles</a>',
'© <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.