Slippy map tilenames

From OpenStreetMap Wiki
Jump to navigation Jump to search
Tile numbering for zoom=2

This article describes the file naming conventions for the Slippy Map application in the OpenStreetMap website.

  • Tiles are 256 × 256 pixel PNG files
  • Each zoom level is a directory, each column is a subdirectory, and each tile in that column is a file
  • Filename (URL) format is /zoom/x/y.png

The slippy map expects tiles to be served up at URLs following this scheme, so all tile server URLs look pretty similar.

Tile servers

two merging arrows

It has been proposed that this page or section be merged with TMS. (Discuss)

The first part of the URL specifies the tile server. The tile coordinates are typically specified by /zoom/x/y.png tail. Some tileservers will use a directory (e.g. "/cycle/") to specify a particular stylesheet. (Historically several subdomains were often provided to get around browser limitations on the number of simultaneous HTTP connections to each host - such as a.tile, b.tile, c.tile - but this is less important with modern browsers.)

Here are some examples:

Name URL template zoomlevels
OSM 'standard' style https://tile.openstreetmap.org/zoom/x/y.png 0-19
OpenCycleMap http://[abc].tile.thunderforest.com/cycle/zoom/x/y.png 0-22
Thunderforest Transport http://[abc].tile.thunderforest.com/transport/zoom/x/y.png 0-22
MapTiles API Standard https://maptiles.p.rapidapi.com/local/osm/v1/zoom/x/y.png?rapidapi-key=YOUR-KEY 0-19 globally
MapTiles API English https://maptiles.p.rapidapi.com/en/map/v1/zoom/x/y.png?rapidapi-key=YOUR-KEY 0-19 globally with English labels

Further tilesets are available from various '3rd party' sources.

Zoom levels

The zoom parameter is an integer between 0 (zoomed out) and 18 (zoomed in). 18 is normally the maximum, but some tile servers might go beyond that.

zoom level tile coverage number of tiles tile size(*) in degrees
0 1 tile covers whole world 1 tile 360° x 170.1022°
1 2 × 2 tiles 4 tiles 180° x 85.0511°
2 4 × 4 tiles 16 tiles 90° x [variable]
n 2n × 2n tiles 22n tiles 360/2n° x [variable]
12 4096 x 4096 tiles 16 777 216 0.0879° x [variable]
16 232 ≈ 4 295 million tiles
17 17.2 billion tiles
18 68.7 billion tiles
19 Maximum zoom for Mapnik layer 274.9 billion tiles

(*) While the width (longitude) in degrees is constant, given a zoom level, for all tiles, this does not happen for the height. In general, tiles belonging to the same row have equal height in degrees, but it decreases moving from the equator to the poles.

See Zoom levels for more details

Derivation of tile names

The following is identical to the well-known Web Mercator projection.

  • Reproject the coordinates to the Spherical Mercator projection (from EPSG:4326 to EPSG:3857):
    • x = lon
    • y = arsinh(tan(lat)) = log[tan(lat) + sec(lat)]
    (lat and lon are in radians)
  • Transform range of x and y to 0 – 1 and shift origin to top left corner:
    • x = [1 + (x / π)] / 2
    • y = [1 − (y / π)] / 2
  • Calculate the number of tiles across the map, n, using 2zoom
  • Multiply x and y by n. Round results down to give tilex and tiley.

Implementations

Pseudo-code

For those who like pseudo-code, here's some hints:

sec = 1/cos
arsinh(x) = log(x + (x^2 + 1)^0.5)
sec^2(x) = tan^2(x) + 1
→ arsinh(tan(x)) = log(tan(x) + sec(x))

Please note that "log" represents the natural logarithm (also known as ln or loge), not decimal logarithm (log10), as used on some calculators.

Lon./lat. to tile numbers

n = 2 ^ zoom
xtile = n * ((lon_deg + 180) / 360)
ytile = n * (1 - (log(tan(lat_rad) + sec(lat_rad)) / π)) / 2

Tile numbers to lon./lat.

n = 2 ^ zoom
lon_deg = xtile / n * 360.0 - 180.0
lat_rad = arctan(sinh(π * (1 - 2 * ytile / n)))
lat_deg = lat_rad * 180.0 / π


This code returns the coordinate of the _upper left_ (northwest-most)-point of the tile.

Mathematics

Idem with mathematic signs (lat and lon in degrees):

Latlon to tile.pngTile to latlon.png

Example: Convert a GPS coordinate to a pixel position in a Web Mercator tile

This example shows how to determine which tile (and what pixel coordinate within the tile) the Hachiko Statue near the Shibuya scramble crossing can be found in:

https://www.openstreetmap.org/node/597685675

1. Choose the coordinates you are interested in

Variable Formula Example (Hachiko Statue)
lonEPSG:4326 The familiar "GPS"-style longitude, which is recorded on a Node in OpenStreetMap.

Positive is east, negative is west.

+139.7006793°
latEPSG:4326 The familiar "GPS"-style latitude, which is recorded on a Node in OpenStreetMap.

Positive is north, negative is south.

+35.6590699°

2. Convert the coordinate to the Web Mercator projection (https://epsg.io/3857)

Variable Formula Example (Hachiko Statue)
xEPSG:3857 lonEPSG:4326

This value will fall in the range (-180°, 180°).

139.7006793°
yEPSG:3857 ln(tan(latEPSG:4326) + 1 / cos(latEPSG:4326))

OR, equivalently,

arsinh(tan(latEPSG:4326))

This value will fall in the range (-π, π) for latitudes between 85.0511 °S and 85.0511 °N.

For the curious, the number 85.0511 is the result of arctan(sinh(π)). By using this bound, the entire map becomes a (very large) square.

0.66693624687

3. Transform the projected point onto the unit square

Variable Formula Example (Hachiko Statue)
x 0.5 + xEPSG:3857 / 360°

This value will fall in the range (0, 1). x=0 is the left (180° west) edge of the map. x=1 is the right (180° east) edge of the map. x=0.5 is the middle, the prime meridian.

0.8880574425
y 0.5 − yEPSG:3857 / (2π)

This value will fall in the range (0, 1). y=0 is the top (north) edge of the map, at 85.0511 °N. y=1 is the bottom (south) edge of the map, at 85.0511 °S. y=0.5 is the middle, the equator.

0.3938537996

4. Determine the zoom level and horizontal/vertical location of individual tiles

Variable Formula Example (Hachiko Statue)
zoom At a zoom level of 0, the entire earth is shown in a single tile.

At a zoom level of 18, detail is visible in individual city blocks.

18
N 2zoom

This is the number of tiles horizontally or vertically from one edge of the map to the other.

262144
xtile N * x

The whole-number part of xtile is the "x" value of the tile overall. The fractional part of xtile indicates the internal horizontal position of the coordinate within that tile.

The first tile will have a xtile=0, with a left edge at 180° W. The last tile will have a xtile=2zoom−1, with a right edge at 180° E.

232798.930207

tile x = 232798

fractional x = 93.02%

ytile N * y

The whole-number part of ytile is the "y" value of the tile overall. The fractional part of ytile indicates the internal vertical position of the coordinate within that tile.

The first tile will have a ytile=0, with a top edge at 85.0511 °N. The last tile will have a ytile=2zoom−1, with a bottom edge at 85.0511 °S.

103246.410442

tile y = 103246

fractional y = 41.04%

This results in the following tile URL:

Variable Formula Example (Hachiko Statue)
URL Most tile servers use a path similar to /(zoom)/(xtile)/(ytile).png. https://tile.openstreetmap.org/18/232798/103246.png

103246.png

5. Transform the projected point into tile space

Variable Formula Example (Hachiko Statue)
dimension By convention, this is 256 pixels for "standard resolution" tiles.

For "high resolution" or "retina" tiles, it's typically 512 pixels.

256 pixels
xpixel fract(xtile) * dimension

This is a number between 0 and dimension, which is the x offset of this coordinate within the tile.

238.1 px
ypixel fract(xtile) * dimension

This is a number between 0 and dimension, which is the y offset of this coordinate within the tile.

105.1 px

Common programming languages

Subtiles

If you're looking at tile x,y and want to zoom in, the subtiles are (in the next zoom-level's coordinate system):

2x, 2y 2x + 1, 2y
2x, 2y + 1 2x + 1, 2y + 1

Similarly, zoom out by halving x and y (in the previous zoom level)

Resolution and Scale

Exact length of the equator (according to Wikipedia) is 40075.016686 km in WGS-84. At zoom 0, one pixel would equal 156543.03 meters (assuming a tile size of 256 px):

40075.016686 * 1000 / 256 ≈ 6378137.0 * 2 * pi / 256 ≈ 156543.03

Which gives us a formula to calculate resolution at any given zoom:

resolution = 156543.03 meters/pixel * cos(latitude) / (2 ^ zoomlevel)

Some applications need to know a map scale, that is, how 1 cm on a screen translates to 1 cm of a map.

scale = 1 : (screen_dpi * 1/0.0254 in/m * resolution)

And here is the table to rid you of those calculations. All values are shown for equator, and you have to multiply them by cos(latitude) to adjust to a given latitude. For example, divide those by 2 for latitude 60 (Oslo, Helsinki, Saint-Petersburg).

zoom resolution, m/px scale 90 dpi 1 screen cm is scale 96 dpi scale 120 dpi
0 156543.03 1 : 554 680 041 5547 km 1 : 591 658 711 1 : 739 573 389
1 78271.52 1 : 277 340 021 2773 km 1 : 295 829 355 1 : 369 786 694
2 39135.76 1 : 138 670 010 1387 km 1 : 147 914 678 1 : 184 893 347
3 19567.88 1 : 69 335 005 693 km 1 : 73 957 339 1 : 92 446 674
4 9783.94 1 : 34 667 503 347 km 1 : 36 978 669 1 : 46 223 337
5 4891.97 1 : 17 333 751 173 km 1 : 18 489 335 1 : 23 111 668
6 2445.98 1 : 8 666 876 86.7 km 1 : 9 244 667 1 : 11 555 834
7 1222.99 1 : 4 333 438 43.3 km 1 : 4 622 334 1 : 5 777 917
8 611.50 1 : 2 166 719 21.7 km 1 : 2 311 167 1 : 2 888 959
9 305.75 1 : 1 083 359 10.8 km 1 : 1 155 583 1 : 1 444 479
10 152.87 1 : 541 680 5.4 km 1 : 577 792 1 : 722 240
11 76.437 1 : 270 840 2.7 km 1 : 288 896 1 : 361 120
12 38.219 1 : 135 420 1.35 km 1 : 144 448 1 : 180 560
13 19.109 1 : 67 710 677 m 1 : 72 224 1 : 90 280
14 9.5546 1 : 33 855 339 m 1 : 36 112 1 : 45 140
15 4.7773 1 : 16 927 169 m 1 : 18 056 1 : 22 570
16 2.3887 1 : 8 464 84.6 m 1 : 9 028 1 : 11 285
17 1.1943 1 : 4 232 42.3 m 1 : 4 514 1 : 5 642
18 0.5972 1 : 2 116 21.2 m 1 : 2 257 1 : 2 821

See also Zoom levels

Tools

References

(note: Slippy tiles and Google map tiles count tile 0,0 down from the top-left of the tile grid; the TMS spec specifies tiles count up from 0,0 in the lower-left!)