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

One of the features of modern browsers is a default restriction on the number of image requests that can be made simultaneously to the one domain. This makes sense for many scenarios, but for a high-throughput map tile service, it can slow things down unnecessarily. It is particularly noticeable on high-latency networks, or where the maps occupy a large part of the screen. It’s common to max out the browser limits of simultaneous requests - normally only 8 images or thereabouts per domain.

To work around these limitations, we can make simultaneous requests to multiple domain names, even if they all ultimately point to the same service. By convention they 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 are entirely optional, so if you don’t need this subdomain trick, you can drop them and instead request from our main domain:

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

Check the documentation of the map display library that you are using 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.