Tile providers

How to point StaticMaps at tile providers other than OpenStreetMap, and what each one's terms allow. Every entry is a StaticMaps.Source.Template configuration you can paste into source:.

Last checked against each provider's own documentation on 2026-09-29. Providers change their URLs, limits and terms; read the linked terms before you depend on one. Where a detail could not be confirmed from the provider's documentation, the entry says to check it rather than guessing.

Read this first: two licence traps

Server-side caching. StaticMaps keeps fetched tiles in its tile cache by default. MapTiler, Stadia Maps, CARTO and Mapbox forbid storing their tiles on a server, and Thunderforest forbids caching proxies. For those providers, set cache: false, and every render fetches its tiles fresh:

source: {StaticMaps.Source.Template, url: "…", attribution: "…", cache: false}

Static images. Rendering tiles into an image on your server and serving that image is itself restricted by some providers. MapTiler and Mapbox forbid serving "a screenshot or other static image" in place of accessing their API, and Stadia Maps allows saving and redistributing rendered images only on a paid plan. cache: false does not fix this. You need a plan or licence that covers static maps.

The providers without either restriction are the community OpenStreetMap servers below and your own tiles, and those ask for light use only.

Attribution

Each entry gives the credit the provider requires, which goes in the source's :attribution and is drawn on every image. Most providers also require links, such as to openstreetmap.org/copyright. An image cannot carry a link, so put the linked credit next to the image on your page as well.

Commercial providers

MapTiler Cloud

source: {StaticMaps.Source.Template,
         url: "https://api.maptiler.com/maps/streets-v4/256/{z}/{x}/{y}{r}.png?key=YOUR_KEY",
         attribution: "© MapTiler © OpenStreetMap contributors",
         cache: false}

Tiles: 512 px by default; the /256/ path segment serves 256 px, and @2x gives high-density tiles. Maximum zoom: check MapTiler's docs.
Account: key required. The free plan is for non-commercial use and development.
Licence: forbids server-side caching and serving static images instead of the API. The free plan also requires the MapTiler logo.
Terms · Tile API · Attribution

Stadia Maps

Includes the Stamen styles Stadia hosts.

source: {StaticMaps.Source.Template,
         url: "https://tiles.stadiamaps.com/tiles/alidade_smooth/{z}/{x}/{y}{r}.png?api_key=YOUR_KEY",
         attribution: "© Stadia Maps © OpenMapTiles © OpenStreetMap",
         zoom: 0..20,
         cache: false}

Styles: alidade_smooth, alidade_smooth_dark, stamen_toner, stamen_terrain, stamen_watercolor and others. Stamen styles add "© Stamen Design" to the credit. Watercolor uses .jpg, goes to zoom 16, and is credited "© Stadia Maps © Stamen Design © OpenStreetMap".
Tiles: 256 px; @2x gives 512 px. Most styles go to zoom 20. An EU endpoint is tiles-eu.stadiamaps.com.
Account: key required for server use. The key can also go in an Authorization: Stadia-Auth YOUR_KEY header, through a source that implements headers/2. The free tier is for non-commercial or evaluation use.
Licence: forbids proxying and server-side caching. Saving and redistributing rendered images needs a paid plan.
Terms · Raster tiles · Attribution

Thunderforest

source: {StaticMaps.Source.Template,
         url: "https://api.thunderforest.com/cycle/{z}/{x}/{y}{r}.png?apikey=YOUR_KEY",
         attribution: "Maps © Thunderforest, Data © OpenStreetMap contributors",
         zoom: 0..22,
         cache: false}

Styles: cycle, transport, landscape, outdoors, atlas and others.
Tiles: @2x for high density; zoom 0–22. The base tile size is not stated in the docs; 256 px is the usual size, but check before relying on it.
Credit: must name both Thunderforest and OpenStreetMap contributors, with links to thunderforest.com and openstreetmap.org/copyright. The wording above is one way to do that; Thunderforest does not prescribe an exact string.
Account: key required. The free Hobby plan allows 150,000 tiles a month.
Licence: "Caching proxies or other redistribution methods are not permitted", and pre-downloading needs an appropriate plan.
Terms · Tile API

Mapbox Static Tiles

source: {StaticMaps.Source.Template,
         url: "https://api.mapbox.com/styles/v1/mapbox/streets-v12/tiles/512/{z}/{x}/{y}{r}?access_token=YOUR_TOKEN",
         attribution: "© Mapbox © OpenStreetMap",
         tile_size: 512,
         zoom: 0..22,
         cache: false}

Tiles: 512 px, or 256 px at four times the request count; @2x doubles them. Zoom 0–22. The Mapbox Standard styles are not available through this API.
Account: token required. There is a monthly free allowance; check Mapbox's pricing page for the current figure.
Licence: caching is allowed only on an end user's device, and serving "a screenshot or other static image" instead of the API is forbidden. The Mapbox logo is also required.
Product terms · Static Tiles API · Attribution

CARTO basemaps

source: {StaticMaps.Source.Template,
         url: "https://{s}.basemaps.cartocdn.com/light_all/{z}/{x}/{y}{r}.png?key=YOUR_KEY",
         subdomains: ~w(a b c d),
         attribution: "© OpenStreetMap, © CARTO",
         zoom: 0..20,
         cache: false}

Styles: light_all (Positron), dark_all (Dark Matter), rastertiles/voyager, and _nolabels and _only_labels variants.
Tiles: @2x for high density; zoom 0–20. The base tile size is not stated; check CARTO's docs.
Account: a key is now required; older guides show keyless URLs that no longer apply. Free up to a monthly tile allowance, which is lower for commercial use.
Licence: credit must be prominent on each map. Server-side caching and proxying are forbidden.
Terms · Styles · Keys

Esri (ArcGIS)

Esri's servers put the row before the column: {z}/{y}/{x}. Source.Template handles that, since placeholders can go in any order.

source: {StaticMaps.Source.Template,
         url: "https://services.arcgisonline.com/ArcGIS/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}",
         attribution: "Source: Esri, Vantor, Earthstar Geographics, and the GIS User Community",
         zoom: 0..23}

Services: the long-standing World_Imagery and World_Street_Map services serve 256-px tiles. World_Street_Map is no longer updated. The current product, the Static Basemap Tiles service, serves 512-px tiles at zoom 0–22 and needs an ArcGIS Location Platform account; how its token is passed is not covered in the docs this guide was checked against, so read its API reference.
Licence: the Esri Master License Agreement. The service pages say the layers are "not intended to be used to export tiles for offline" use. Whether the older services need a key, and what their terms say about server-side rendering, is not clear from their pages; confirm with Esri before production use.
World Imagery · Static Basemap Tiles

Community servers

These run on donated or community resources, need no key, and allow server-side rendering with caching. They ask for light use and offer no uptime guarantee. The OpenStreetMap Foundation's tile policy covers only tile.openstreetmap.org, but the same courtesy applies: an identifying User-Agent, which StaticMaps sends, honouring cache headers, which the tile cache does, and no bulk downloading.

OpenStreetMap France and Humanitarian (HOT)

source: {StaticMaps.Source.Template,
         url: "https://{s}.tile.openstreetmap.fr/osmfr/{z}/{x}/{y}.png",
         subdomains: ~w(a b c),
         attribution: "données © OpenStreetMap/ODbL - rendu OSM France",
         zoom: 0..20}

source: {StaticMaps.Source.Template,
         url: "https://{s}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png",
         subdomains: ~w(a b c),
         attribution: "données © OpenStreetMap/ODbL - Tiles courtesy of Humanitarian OpenStreetMap Team",
         zoom: 0..19}

Credit: must be visible in the map corner, with a link to https://osm.org/copyright.
Licence: "Any abusive usage may result in traffic limitation or blocking."
Usage

OpenTopoMap

source: {StaticMaps.Source.Template,
         url: "https://{s}.tile.opentopomap.org/{z}/{x}/{y}.png",
         subdomains: ~w(a b c),
         attribution: "Kartendaten: © OpenStreetMap-Mitwirkende, SRTM | Kartendarstellung: © OpenTopoMap (CC-BY-SA)",
         zoom: 0..15}

Zoom: the maximum is not stated reliably; zoom 16 and 17 are reported as unreliable, so the configuration above stops at 15. Raise it if it works for you.
Licence: free, including commercial use, with attribution and share-alike, as long as the server is not overloaded by bulk downloads. The credit above is the German original from OpenTopoMap's about page.
About and terms

CyclOSM

source: {StaticMaps.Source.Template,
         url: "https://{s}.tile-cyclosm.openstreetmap.fr/cyclosm/{z}/{x}/{y}.png",
         subdomains: ~w(a b c),
         attribution: "CyclOSM & OSM-FR, © OpenStreetMap contributors",
         zoom: 0..20}

Credit: OpenStreetMap contributors, and ideally CyclOSM and OSM-FR. The exact wording is not prescribed.
Licence: reusable under the OpenStreetMap tile usage policy.
CyclOSM · Tile policy

Your own tile servers

Several servers serving identical tiles are mirrors: pass a list of templates, and each tile goes to a mirror chosen from its position, falling back to the next mirror if that one fails.

source: {StaticMaps.Source.Template,
         url: ["https://tiles1.example.com/{z}/{x}/{y}.png",
               "https://tiles2.example.com/{z}/{x}/{y}.png"],
         attribution: "© OpenStreetMap contributors",
         max_concurrency: 16}

:max_concurrency is the limit across all the mirrors together, so no single server ever sees more than that many requests, even while another mirror is down and its tiles go elsewhere. Mirrors must serve the same tiles; to fall back to a different provider, list it as a fallback source instead: source: [primary, fallback].

← Previous Page LICENSE

Next Page → Architecture