Raster Map Tiles¶
While vector tiles have replaced the classic image grid for many applications, raster map tiles are battle-tested and easy to render. They also benefit from a rich ecosystem of rendering libraries like OpenLayers and Leaflet.
All of our house styles are available as PNG raster tiles in 256x256 px and 512x512 px "retina" sizes.
Tile URL Format¶
Most renderers use a format string like the one below and will automatically
replace the placeholders for you. The only thing you'll need to replace yourself in most cases is the <style>
placeholder. You can find the URLs for all our styles in the style gallery.
Max Zoom
For most raster styles, we support up to zoom 20 (Stamen Watercolor is an exception and may have missing tiles at zoom greater than 16).
If your library of choice supports specifying a max zoom, we recommend adding it to prevent visual errors.
Our standard endpoints will serve tiles from the fastest server no matter where your users are, and is backed by our global CDN with multiple layers of redundancy.
https://tiles.stadiamaps.com/tiles/<style>/{z}/{x}/{y}{r}.png
https://tiles.stadiamaps.com/tiles/<style>/{z}/{x}/{y}.png
https://tiles.stadiamaps.com/tiles/<style>/{z}/{x}/{y}@2x.png
Our EU endpoints allow you to explicitly route all requests to our EU servers. See our EU Endpoints page for more details.
https://tiles-eu.stadiamaps.com/tiles/<style>/{z}/{x}/{y}{r}.png
https://tiles-eu.stadiamaps.com/tiles/<style>/{z}/{x}/{y}.png
https://tiles-eu.stadiamaps.com/tiles/<style>/{z}/{x}/{y}@2x.png
What do {x}, {y}, {z}, and {r} mean?
The {x}, {y}, and {z} placeholders represent x, y, and zoom
following the standard slippy map tilename
convention. This format is used by most popular libraries. Note that our tile numbering uses the XYZ
scheme, not TMS.
The {r} placeholder is used for HiDPI ("retina") display suppoort. Popular web map renderers like Leaflet
understand this placeholder. If your renderer does not understand this (e.g., MapLibre GL JS or QGIS),
you can either remove the placeholder to get raw 256x256 PNGs, or replace it with @2x for 2x scaled images.
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.
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¶
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 can be used with any raster map renderer capable of loading PNG tiles.