2.1.38 (current version)

Hotspot descriptions

Descriptions of hotspots must be generated separately for each tile and for all zoom levels. In the standard API implementation, JSON is used as the format for describing data.

The JSON description of a hotspot must specify:

  • Hotspot ID.
  • Hotspot position on the tile, in pixel coordinates.
  • Type of geometric shape that represents the hotspot.

The hotspot ID must be generated independently. It must be unique within a single layer.

The position of the shape is set in pixel coordinates relative to the upper-left corner of the corresponding tile.

Geometry types for hotspots are strictly defined in the API. The table below lists acceptable types:

ExampleGeometry typeDescription

* Polygons can have an inner contour. If a polygon is convex, its inner contour must also be convex.

ConvexPolygonConvex polygon.
MultipolygonComplex shape. Consists of multiple polygons.
MultiConvexPolygonComplex shape. Consists of multiple convex polygons.

* Polygons can have an inner contour. If a polygon is convex, its inner contour must also be convex.

In addition, the hotspot description may specify a number of properties, such as the content of a balloon or hint, or the z-index of the hotspot relative to other hotspots.

An example of hotspot descriptions is provided below:

"data": {
    "type": "FeatureCollection",
    // Array of hotspots.
    "features": [{
        "type": "Feature",
        // Hotspot data.
        "properties": {
            "hintContent": "Textual hint content.",
                "balloonContentBody": "Balloon content.",
                "balloonContentHeader": "Balloon title.",
                "balloonContentFooter": "Lower part of balloon.",
            // The balloonContent property can be set instead of Body/Header/Footer

            // Mandatory field
           "HotspotMetaData": {
               // Hotspot ID.
               "id": 10469893,

               // Data used as the basis for creating the hotspot geometry.
               // Mandatory field.
               "RenderedGeometry": {
                        "type": "Polygon",
                   // Polygon coordinates.
                   "coordinates": [
                       // First contour of the polygon.
                           [-315, 280], [32, 442], [141, 208], [-206, 46], [-315, 280]
                       // Second contour of the polygon.
                           [-186, 155], [-238, 265], [-152, 306], [-100, 196], [-186, 155]
        "type": "Feature",
        "properties": {
            // description of the next hotspot object...

Sometimes a hotspot may fall onto several tiles at once. When creating a description of such a hotspot, you do not need to divide it into shapes along tile borders. The description is set for the entire shape as a whole. This means that the same ID must be specified in the hotspot description for each tile. In addition, coordinates of the shape's vertices must be specified relative to the tile that the description is being created for.

The pictures below provide an example of specifying coordinates of rectangle vertices that fall on the tiles [0,0], [1,0] and [1,1] (examples are provided for the first two tiles).

Coordinates of rectangle vertices relative to the tile [0,0]:

Coordinates of rectangle vertices relative to the tile [1,0]:

Storing data about hotspots

Hotspot descriptions for each file can be stored in a separate file. These files reside on the server, and the API will access it each time it needs to get data for the necessary tile.

The API provides the ability to use templates for naming data files. If files are named according to a specific template, to get the URL for data for each tile, the API only needs to know which template is used.

For example, let's assume the template for the URL for tile data looks like this:


The API makes the following value substitutions: in place of %z, the value of the zoom level is inserted; in place of %x and %y, the number of the tile on the x and y axes are used. Then, using the resulting address, the API will access the server for data for the corresponding tile.

For example, for the tile [2,3] with z=4, the URL for data will be: http://server.domain/4/2/3.

For more information about using templates, see the Reference.

Note. The API user must independently generate descriptions of all hotspots and make sure that the server returned this data to the API, wrapped in a json-callback (for more information, see the section Data source).