This article explains what are the several types of rasterized map tiles available in MapTiler Cloud.
You will learn what is the difference between larger tile size and scale as well as what to choose when developing your application.
The differences between rasterized map tiles described in this article only apply to on-the-fly rasterized Maps requested from MapTiler Cloud (and MapTiler Server).
It does not apply when requesting Tiles, which are pre-generated and there is no dynamic processing involved.
The maps available in MapTiler Cloud are primarily vector-based and it is recommended to display the maps as vectors whenever possible.
In case your application is not able to display the vector maps directly, or if you need the maps as raster tiles for compatibility or performance reasons, it is possible to use the on-the-fly rasterized map tiles.
There are two different endpoint parameters, which affect how the resulting tile is rasterized from the vector data. See the API specification of the endpoint for details on how to use them.
Larger size → larger area
The first parameter is the size of the tile. By default, MapTiler Cloud rasterizes each requested tile as a 512x512 image, but you can also explicitly request a 256x256 image instead (using a
We recommend sticking with the 512x512 tiles because these usually result in better application performance – fewer network requests are required to cover the same area.
Both 256x256 and 512x512 have exactly the same content scale (identical pixel size of features and labels), the only difference is in the covered area.
Note: The StyleJSON specification and the Style editor use the zoom-level numbering based on the 512x512 tile size, so when requesting the 256x256 tiles instead, you need to shift the zoom levels by 1 to get the same visual style.
HiDPI/retina → better resolution
In addition to the different tile sizes, it is also possible to request a HiDPI (also called “retina”) version of the tile by adding a
@2x suffix before the extension.
Both the default and the HiDPI versions display exactly the same area and content, but the HiDPI version simply contains more pixels. Therefore all the lines are “thicker” and all the labels are “bigger”.
It is intended to be used on devices with very fine pixels (such as mobile phones) so that the labels remain readable and the map style looks as intended.
Device pixel ratio
In reality, the devices have various displays with different physical sizes and pixel resolutions. The device pixel ratio tells you how many pixels you need to use on the specific device so that the final content looks the same across all the devices.
@2x suffix generates images that are double the size in both dimensions, so it’s ideal for devices with a device pixel ratio equal to 2. However, many devices have this ratio different and ideally, you would need different tiles for different devices.
The correct solution to this issue is to use the vector tiles instead because then each feature of the map is actually rendered client-side taking into account all the specifics of the device and its display.
Note: The HiDPI/retina suffix can also be used when requesting images via the Static Maps API.
Choosing the correct variant
As previously mentioned, we strongly recommend using the vector maps wherever possible. The MapLibre project provides great SDKs for both browser and mobile platforms. It is also possible to use OpenLayers for displaying the map in the browser (which does not require WebGL). There are also code samples available in MapTiler Cloud for both MapLibre GL JS and OpenLayers. This is the best way to achieve a really sharp-looking map.
In case you want to use the raster tiles, MapTiler Cloud provides the standard TileJSON for both 512x512 and 256x256 map tiles. These can be used in OpenLayers, Leaflet (with a plugin), and many other applications.
You can also use the XYZ tiles directly (without requesting the TileJSON), but this usually requires a little more setup (e.g. make sure to correctly display the attribution).
If possible, we recommend using the 512x512 tiles, which usually result in better performance and a better user experience. Use the 256x256 only when working with legacy application/software/framework, which is unable to use the larger tiles.
For using the HiDPI/retina tiles, there is an official OpenLayers example of how to do it. But once again, using the vector tiles is the superior approach to achieve the best-looking result across different devices.
If your application/framework can only display rasterize maps tiles:
the default 512x512 is usually the best choice
use the legacy 256x256 rasterized map tiles only if you have no other option
you can use the HiDPI/retina tiles if you want to make the map look sharper on mobile devices. (And your application/framework is able to handle it correctly.)