Overview

The tile access API is the HTTP API you can use to get raster images of the Mappable Maps layer.

The API returns one tile image per request. Tiles are squares of 256x256 pixels the map image is segmented into (see the image below). Each tile is a separate PNG file. To generate an entire map, you need to send requests for the tiles you want visible.

LimitationsLimitations

Please pay attention to the following limitations:

• Requests per second (RPS): Up to 50.
• You can use the API to get tiles only for maps of the roadmap type.
• You can't use the API to add any items to the map (such as placemarks, lines, or controls). If necessary, you can draw these items on top of the map.

What are tiles?What are tiles?

The Mappable services store sections of the map instead of the entire map. The map image is divided into squares that are 256x256 pixels in size –tiles. Each tile is stored in a separate PNG file. This saves the internet traffic when loading the map: the apps load only the tiles that are visible right now instead of the entire map.

Each tile has a serial number [x, y], where x is the tile number at the X axis and y is the tile number at the Y axis. The numbering starts at the top left corner of the world map and continues down to the right. The numbering starts from zero.

Tiles are created separately for each map scale level. At the smallest scale (zoom level 0), the entire territory is covered by a single tile (see the image below). At the next scale level (zoom level 1), the entire territory is made up of four tiles. At zoom level 2, the map is covered by a grid of 16 tiles, and so on. This means that each zoom level divides the map into 4^z tiles, where z is the zoom level.

To get the image of the tile you need:

1. Calculate the tile number.
2. Send a GET request to the API specifying the tile numbers in the parameters.

How to calculate the tile numberHow to calculate the tile number

To calculate the number of the tile:

1. Determine the geographical coordinates of the item that the tile should display (in degrees).

2. Render the item's geographical coordinates into global pixel coordinates.

   Formulas for calculating global pixel coordinates

   Let's introduce the following terms:

   • lat, lon: Latitude and longitude in degrees.
   • z: Map zoom level.
   • ε: The eccentricity of the Earth ellipsoid. If you need tiles for the elliptical Mercator projection, ε=0.0818191908426. If for the spherical projection, ε=0. By default, Mappable use the elliptical Mercator projection.

   Then the global pixel coordinates [x_p, y_p] for the specified zoom level z can be calculated using the formulas:

   

   

   where:
   
   

   

   

3. Divide the global pixel coordinates by 256 and round down. The resulting values are the tile number.

Using the Mappable logoUsing the Mappable logo

When working with the API, you need to observe the condition: the map must feature the Mappable logo.

You must add the Mappable logo on top of the map manually. Below are the main requirements for the use of the logo.

1. Placement1. Placement

The logo can be placed only in the corner of the map. Any of the four corners is acceptable:

2. Indentation from the map borders2. Indentation from the map borders

The logo images already contain the indentation area. On the image below, the indentations are highlighted in orange. There's no need to set additional indentations from the map borders.

3. Language3. Language

4. Clickability4. Clickability

The logo must be a hyperlink to the Mappable Maps website home page.