Vector Map Tiles¶

Vector map tiles look great at any zoom level and allow dynamic styling (like changing the language) unlike raster tiles. Our tiles are distributed in the ubiquitous Mapbox Vector Tile format. We recommend the web and mobile renderers from MapLibre, but our tiles will work in any MVT-compatible renderer. Our tile schema is compatible with OpenMapTiles, and allows easy customization if you want to build a custom style

Tile URLs¶

In most cases, all you need is a MapLibre JSON Style URL. Renderers like MapLibre GL JS and MapLibre Native will handle the rest for you! We have a number of styles to get you started. If you are using a renderer that doesn't use MapLibre JSON styles, or need the raw tiles for some other purpose like spatial analysis, there are a few ways you can access them.

TileJSONDirect Access

TileJSON is a widely supported tileset description file. It includes the URL as well as other metadata such as the bounds, attribution, and supported zoom levels.

Standard URL

https://tiles.stadiamaps.com/data/openmaptiles.json

If you want to explicitly route all tile requests to our EU servers, we offer a separate URL See our EU Endpoints page for more details.

EU URL

https://tiles-eu.stadiamaps.com/data/openmaptiles.json

If you need raw access to the tiles, you can access them with the following URL format. Your application or framework must fill in the placeholder values with an XYZ (not TMS) tile number. We support zoom levels 0 through 14. Any additional rendering beyond zooom 14 is done by "over-zooming" the z14 tile, which contains all possible information.

Standard URL format

https://tiles.stadiamaps.com/data/openmaptiles/{z}/{x}/{y}.pbf

If you want to explicitly route all tile requests to our EU servers, we offer a separate URL See our EU Endpoints page for more details.

EU URL format

https://tiles-eu.stadiamaps.com/data/openmaptiles/{z}/{x}/{y}.pbf

Authentication¶

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¶

Tutorials¶

We have an extensive tutorial library to help you get started with the most popular libraries/frameworks. If your library/framework isn't listed, let us know! Our tiles are compatible with vector map renderers capable of loading Mapbox Vector Tiles.

Web¶

Mobile¶

Alternative Renderers¶

Stadia Maps serves tiles that conform to the MVT specification, which means you have the option of using any renderer that supports the MVT format, not just MapLibre GL JS. You can use our vector tiles with Leaflet, OpenLayers and Tangram with varying degrees of support and polish.

Stadia Maps will always support your rights to use any library that you choose. While we aren't quite ready to distribute styles for alternative renderers with our stamp of quality, we have official styles for other renderers on our roadmap. Please reach out if this is important for you and your project.

OpenLayers¶

You can use any (OpenMapTiles schema-compatible) JSON style with OpenLayers thanks to the ol-mapbox-style plugin. This library will attempt to convert a GL JSON stylesheet into an OpenLayers one. You’ll notice there are a some differences between the OpenLayers version and the MapLibre GL rendering, but it is close enough for many applications and enables you to leverage the power of OpenLayers with our vector tiles.

<!DOCTYPE html>
<html>
    <head>
        <title>OpenLayers Vector Tile Demo</title>
        <!-- Note that fonts will not perfectly match our Mapbox GL styles at present -->
        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v7.4.0/ol.css">
        <style>
            html, body {
                height: 100%;
                margin: 0;
            }
            #map {
                width: 100%;
                height: 100%;
                background-color: #f8f4f0;
            }
        </style>
    </head>
    <body>
        <div id="map"></div>
        <script src="https://cdn.polyfill.io/v2/polyfill.min.js?features=fetch,Promise"></script>
        <script src="https://cdn.jsdelivr.net/npm/ol@v7.4.0/dist/ol.js"></script>
        <script src="https://unpkg.com/ol-mapbox-style@9.4.0/dist/olms.js"></script>
        <script>
            olms.apply('map', 'https://tiles.stadiamaps.com/styles/alidade_smooth_dark.json').then(function(map) {
                // Callback to configure the map if necessary
            });
        </script>
    </body>
</html>

Tangram¶

Tangram offers a number of unique features compared to other vector renderers, including custom GLSL shaders, unique 3D rendering customizations, and custom camera and lighting controls. We don't yet offer official styles, but have an experimental tool that attempts to migrate our JSON styles to Tangram ones. You can follow the development of the Cartogrify project on GitHub.