Map Tiles API

Our Maps Tiles API follows the standard format for Web Mercator map tile services. In most cases you’ll be using a library (such as Leaflet or OpenLayers) which will fill in most of these parameters for you, for example the library will calculate the z, x and y parameters automatically as you move the map. Other parameters, such as the map style or format, you will choose yourself.

The URL format for the Maps Tiles API is:

https://{s}.tile.thunderforest.com/{style}/{z}/{x}/{y}{scale}.{format}?apikey={apikey}
s

(optional) The tileserver subdomains. Valid domains are a,b and c.

style

The id for the map style, e.g. cycle or transport

z

The zoom level of the tile. Range from 0 to 22 inclusive.

x

The horizontal tile number.

y

The vertical tile number.

scale

(optional) The scale modifier, e.g. @2x. When omitted, a scale of 1 is used.

format

The image format, e.g. .png or .jpg90.

apikey

Your API Key.

Tileserver Subdomains

A feature of modern web browsers is that they have a restriction on the number of image requests that can be made simultaneously to the one domain. This might make sense for many scenarios, but not for a high-throughput map tile service, where it can slow map display down unnecessarily. It is particularly noticeable on high-latency networks, or where the maps occupy a large part of the screen. The default limits are typically 6-8 simultaneous connections per server, so for large maps it’s common to see delays where some tile requests are queued by the browser.

Our tileserver subdomains allow your site to make simultaneous requests to multiple domain names, even though they all ultimately point to the same service. This effectively increases the number of simultaneous tile requests, that would otherwise be limited by the browser. By convention the different tileservers are labeled a, b, and c - so the following three URLs all point to the same service, and give the same tiles in response.

https://a.tile.thunderforest.com/cycle/3/3/3.png?apikey=<insert-your-apikey-here>
https://b.tile.thunderforest.com/cycle/3/3/3.png?apikey=<insert-your-apikey-here>
https://c.tile.thunderforest.com/cycle/3/3/3.png?apikey=<insert-your-apikey-here>

The tileserver subdomains configuration is entirely optional. If you don’t need this subdomain feature, for example if your application is not using a browser component to load the map images, you can safely remove them and instead send all requests to our main domain:

https://tile.thunderforest.com/cycle/3/3/3.png?apikey=<insert-your-apikey-here>

Check the documentation of your map display library to see if it supports multiple subdomains for faster parallel requests.

Tile Numbers (z/x/y)

Our tile numbering follows the standard Web Mercator scheme, with 0,0 in the top left on each zoom level. You can read more about the tile numbering but most libraries calculate these for you.

Retina Tiles

The scale parameter allows you to request ‘retina’ or ‘hidpi’ map images. For example, setting the scale to @2x will return map tiles at double scale, but otherwise showing exactly the same features and labels. Some map libraries support automatic detection for retina screens, including Leaflet.